@clien-ai/mcp 0.11.0 → 0.12.1

package/dist/types/report.js

@@ -12,12 +12,16 @@
  * — see how research.ts handles it.
  */
 import { z } from 'zod';
+import { CONFIDENCE_BASES, CONFIDENCE_LEVELS, EVIDENCE_SUFFICIENCY_LEVELS, HYPOTHESIS_PRIORITIES, HYPOTHESIS_SEMANTICS_VERSION, ROBUSTNESS_OUTCOMES, VERDICT_STATUSES, hasCoherentRobustnessWorking, normalizeFinalHypothesisState, readRobustnessCounts, robustnessWorkingContradictsSummary, } from '../hypothesis-semantics.js';
 // ⚠️ A types module importing from `tools/` reads backwards, and it is deliberate.
 // `content-type-display.ts` imports NOTHING — it is the package's content-type vocabulary, which
 // happens to live beside the two renderers that were its first callers, and the FUL-341 coupling
 // test parses `CANONICAL_CONTENT_TYPES` out of that exact path as TEXT. Moving the file to break
 // the layering would cost more than the layering does.
 import { CONTENT_TYPE_EXCLUSIONS, CONTENT_TYPE_STATES } from '../tools/content-type-display.js';
+import { parseReceiptId } from '../tools/receipt-children.js';
+import { readSemanticTheme } from './semantic-theme.js';
+export { CONFIDENCE_BASES, CONFIDENCE_LEVELS, EVIDENCE_SUFFICIENCY_LEVELS, HYPOTHESIS_SEMANTICS_VERSION, ROBUSTNESS_OUTCOMES, VERDICT_STATUSES, } from '../hypothesis-semantics.js';
 /**
  * A competitor discovered during the research run.
  *
@@ -190,8 +194,6 @@ export const ReportSourceSchema = z
         'single excerpt in `quote`.'),
 })
     .passthrough();
-/** The machine verdict statuses a hypothesis / robustness re-ask can return. MIRROR of `VERDICT_STATUSES`. */
-export const VERDICT_STATUSES = ['validated', 'invalidated', 'inconclusive'];
 /**
  * One reworded re-ask of a hypothesis verdict (robustness probe). MIRROR of
  * `RobustnessVariantSchema` in `agent/src/types.ts`. Failed/flipped variants are
@@ -201,7 +203,7 @@ export const RobustnessVariantSchema = z
     .object({
     framing: z.string().describe('The exact reworded question the verdict was re-asked under.'),
     returnedStatus: z.enum(VERDICT_STATUSES).describe('The verdict this framing returned.'),
-    returnedConfidence: z.number().describe('Confidence (0-1) of this framing\'s verdict.'),
+    returnedConfidence: z.number().min(0).max(1).describe('Confidence (0-1) of this framing\'s verdict.'),
     agreed: z.boolean().describe('True when this framing returned the same verdict as the original synthesis.'),
     reasoning: z.string().optional().describe('One-line reason for this framing\'s verdict.'),
 })
@@ -216,16 +218,70 @@ export const RobustnessVariantSchema = z
 export const RobustnessResultSchema = z
     .object({
     originalStatus: z.enum(VERDICT_STATUSES).describe('The synthesiser verdict that was re-tested.'),
-    survived: z.number().describe('How many framings returned the same verdict.'),
-    total: z.number().describe('How many framings were re-asked (may be < intended if budget-capped).'),
+    survived: z.number().int().min(0).describe('How many framings returned the same verdict.'),
+    total: z.number().int().positive().describe('How many framings were re-asked (may be < intended if budget-capped).'),
     flipped: z.boolean().describe('True when at least one framing returned a different verdict.'),
     downgradedStatus: z
         .enum(VERDICT_STATUSES)
         .optional()
         .describe('Weaker verdict displayed when the original flipped under a rephrasing; absent when it held.'),
     variants: z.array(RobustnessVariantSchema).describe('Every re-ask, passed AND failed — the inspectable working behind the survival count.'),
+})
+    .passthrough()
+    .superRefine((value, ctx) => {
+    if (!readRobustnessCounts(value)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['survived'],
+            message: 'Robustness survival count must be a possible survived/total ratio',
+        });
+    }
+    if (!hasCoherentRobustnessWorking(value)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['variants'],
+            message: 'Robustness variants must prove the recorded survival summary',
+        });
+    }
+});
+/**
+ * The effective-result vocabulary (FUL-358). MIRRORS of `CONFIDENCE_LEVELS`,
+ * `EVIDENCE_SUFFICIENCY_LEVELS`, `ROBUSTNESS_OUTCOMES` and `CONFIDENCE_BASES` in
+ * `agent/src/types.ts`, pinned by the schema-coupling test at the repo root.
+ */
+/**
+ * THE effective hypothesis result — verdict, reliability, coverage and robustness outcome,
+ * reconciled once by the producer. MIRROR of `FinalHypothesisStateSchema` in
+ * `agent/src/types.ts`.
+ *
+ * ⚠️ CODE-DERIVED by the agent, never model-written, so it can be quoted as-is. Three separate
+ * axes on purpose: `verdict` is which way the evidence pointed, `sufficiency` is how much of it
+ * there was, and `confidence` is how RELIABLE the verdict is — never the probability the
+ * hypothesis is true. `confidence` ABSENT means WITHHELD; read `confidenceBasis` for why.
+ *
+ * Absent on a legacy report, where the row's numeric `confidence` is the retired measure and is
+ * not comparable with these words.
+ */
+export const FinalHypothesisStateSchema = z
+    .object({
+    version: z.literal(HYPOTHESIS_SEMANTICS_VERSION).describe('Which semantics contract this block was written under.'),
+    verdict: z.enum(VERDICT_STATUSES).describe('The EFFECTIVE verdict every surface shows. A robustness downgrade is applied only when it makes a strictly weaker claim, so a malformed re-ask block can never upgrade a row.'),
+    originalVerdict: z.enum(VERDICT_STATUSES).describe('The synthesiser\'s own verdict, preserved for audit even when the row was downgraded.'),
+    confidence: z.enum(CONFIDENCE_LEVELS).optional().describe('How reliable the final verdict is. ABSENT means withheld — see confidenceBasis. Never a probability that the hypothesis is true.'),
+    confidenceBasis: z.enum(CONFIDENCE_BASES).describe('Why confidence says what it says: read off the evidence, recomputed after the verdict flipped under rephrasing, or withheld because the run attached no evidence.'),
+    sufficiency: z.enum(EVIDENCE_SUFFICIENCY_LEVELS).describe('How much evidence sits behind the verdict, across how many research methods. A coverage axis, independent of which way the verdict pointed.'),
+    robustness: z.enum(ROBUSTNESS_OUTCOMES).describe('What the robustness pass did: held, flipped, or never re-asked. `not_retested` is explicit — it is not the same as held.'),
+    priority: z.enum(HYPOTHESIS_PRIORITIES).optional().catch(undefined).describe('The product priority of the underlying hypothesis, for ranking what to go and ask about first.'),
 })
     .passthrough();
+/**
+ * The cross-field trust boundary for a producer-owned `final` block. Shape-valid enums are not
+ * enough: the block must name the row's original verdict, never strengthen any recorded verdict,
+ * and carry an axis combination the producer can actually emit.
+ */
+export function isSemanticallyValidFinalHypothesisState(row) {
+    return normalizeFinalHypothesisState(row) !== null;
+}
 /** One piece of evidence for/against a hypothesis. MIRROR of `EvidenceSchema`. */
 export const EvidenceSchema = z
     .object({
@@ -246,14 +302,31 @@ export const HypothesisResultSchema = z
     statement: z.string(),
     category: z.enum(['problem', 'solution', 'market', 'willingness_to_pay']),
     status: z.enum(VERDICT_STATUSES).describe('The verdict for this hypothesis.'),
-    confidence: z.number().describe('Confidence (0-1) in the verdict.'),
+    confidence: z.number().describe('Legacy numeric confidence stored on either the retired 0-1 or 0-100 scale. Preserve and label it as legacy; never compare it with final.confidence, rank on it, or trend it.'),
     supportingEvidence: z.array(EvidenceSchema).optional(),
     contradictingEvidence: z.array(EvidenceSchema).optional(),
     robustness: RobustnessResultSchema.optional().describe('Robustness re-ask survival count for this verdict (absent on legacy reports / when not re-tested).'),
     scopeCaveat: z.string().optional().describe('Belief-adjacent scope-mismatch note (FUL-102): present when this hypothesis\'s persona support came from a persona speaking outside its credibility domain. Treat such support as directional, not grounded.'),
+    final: FinalHypothesisStateSchema.optional().describe('THE effective result (FUL-358) — verdict, reliability, evidence sufficiency and robustness outcome, reconciled once and read by every surface. Prefer `final.verdict` over `status` and `final.confidence` over the numeric `confidence` above. Absent on legacy reports, where the numeric `confidence` is the retired measure.'),
     evidenceReading: z.string().optional().describe('One plain-language line naming what this verdict rests on — how many findings support and contradict it, and which research methods they came from. CODE-COMPOSED from this row\'s own evidence arrays, never written by the model, so it can be quoted as-is. It deliberately says nothing about whether the personas disagreed: that is `sycophancySignals.disagreements`, a stricter predicate over persona identity, and reading a split out of this line would contradict it. Absent on reports written before FUL-396 and on a hypothesis the run attached no evidence to.'),
 })
-    .passthrough();
+    .passthrough()
+    .superRefine((row, ctx) => {
+    if (row.robustness && row.robustness.originalStatus !== row.status) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['robustness', 'originalStatus'],
+            message: 'Robustness must re-test this hypothesis result status',
+        });
+    }
+    if (row.final !== undefined && !isSemanticallyValidFinalHypothesisState(row)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['final'],
+            message: 'Final hypothesis semantics are incoherent with the row',
+        });
+    }
+});
 /**
  * Something a persona explicitly rejected — the willingness-to-say-no signal.
  *
@@ -429,6 +502,19 @@ export const ReportIdentityPriorsSchema = z
         .describe('How the persona got to this role and where they are heading — a short trajectory arc, e.g. "engineer → engineering manager".'),
 })
     .passthrough();
+/**
+ * Frozen, decorative persona portraits a report may carry (FUL-771).
+ *
+ * This is deliberately a closed list of bundled Clien assets, not a URL schema.
+ * Treating any syntactically valid URL as a portrait would turn report_data into
+ * an arbitrary remote-image channel and could also leak a live persona identity.
+ */
+export const REPORT_PORTRAIT_PATHS = [
+    '/avatars/maya-chen.png',
+    '/avatars/james-rodriguez.png',
+    '/avatars/sarah-thompson.png',
+];
+export const ReportPortraitSchema = z.enum(REPORT_PORTRAIT_PATHS);
 /**
  * A report persona carrying its source RECEIPTS. Lean surface — `.passthrough()`
  * keeps the full persona profile (goals, painPoints, psychographic, tools) the
@@ -440,6 +526,9 @@ export const ReportPersonaSchema = z
     .object({
     name: z.string(),
     role: z.string().optional(),
+    portrait: ReportPortraitSchema.optional()
+        .catch(undefined)
+        .describe('Frozen decorative portrait selected from Clien bundled assets. Never a live persona join or an arbitrary remote URL.'),
     sources: z.array(ReportSourceSchema).optional().describe('The real forum posts this persona is composited from — the receipts a claim\'s sourceId points at (may be empty when evidence was sparse).'),
     insufficientEvidence: z.boolean().optional().describe('True when the forum pre-pass found too few real posts to ground this persona.'),
     sourcesFound: z.number().optional().describe('Count of unique real posts the pre-pass surfaced for this persona.'),
@@ -764,13 +853,64 @@ export const MethodologyNoteSchema = z
  * ⚠️ DELIBERATELY NOT `.passthrough()`. The producer also carries
  * `researchTaskId`, an internal `validation_research_tasks.id` that is not an
  * interview-link contract. Zod's default strip behaviour is the privacy boundary:
- * only these four fields cross into MCP's structured report payload.
+ * only these fields cross into MCP's structured report payload. The content-addressed evidence
+ * block is public report identity; the internal research-task id remains excluded.
  */
 export const InterviewHighlightSchema = z.object({
     personaName: z.string(),
     personaRole: z.string(),
     overallImpression: z.string(),
     quotesByHypothesis: z.record(z.string(), z.array(z.string())),
+    evidenceReference: z.object({
+        interviewId: z.string().min(1),
+        quotes: z.array(z.object({
+            quoteId: z.string().min(1),
+            hypothesisId: z.string().min(1),
+            text: z.string(),
+        })),
+    }).optional(),
+});
+export const EvidenceRefSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('report_evidence'), sourceId: z.string().min(1) }),
+    z.object({
+        kind: z.literal('forum_receipt'),
+        receiptId: z.string().refine((value) => parseReceiptId(value) !== null, {
+            message: 'Invalid receipt id',
+        }),
+    }),
+    // Kept in the parser for compatibility, but stripped by projectReportDataForMcp because the
+    // researchTaskId is private and this surface has no external interview-receipt contract.
+    z.object({ kind: z.literal('interview_quote'), researchTaskId: z.string(), quoteId: z.string() }),
+    z.object({ kind: z.literal('interview_quote_v2'), interviewId: z.string().min(1), quoteId: z.string().min(1) }),
+    z.object({ kind: z.literal('hypothesis'), hypothesisId: z.string().min(1) }),
+]);
+export const CrossCuttingEvidenceRefSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('report_evidence'), sourceId: z.string().min(1) }),
+    z.object({
+        kind: z.literal('forum_receipt'),
+        receiptId: z.string().refine((value) => parseReceiptId(value) !== null, {
+            message: 'Invalid receipt id',
+        }),
+    }),
+    z.object({ kind: z.literal('interview_quote_v2'), interviewId: z.string().min(1), quoteId: z.string().min(1) }),
+]);
+export const CrossCuttingFindingSchema = z.object({
+    claim: z.string().min(1),
+    whyItMatters: z.string().min(1),
+    confidence: z.enum(['low', 'medium', 'high']),
+    evidenceRefs: z.array(CrossCuttingEvidenceRefSchema),
+});
+export const MCP_OVERVIEW_SPAN_CAP = 8;
+export const MCP_OVERVIEW_REF_CAP = 4;
+export const ReportOverviewSchema = z.object({
+    text: z.string(),
+    claimSpansTruncated: z.boolean().optional(),
+    claimSpans: z.array(z.object({
+        span: z.string(),
+        claimType: z.enum(['externally_checkable', 'inference']),
+        evidenceRefsTruncated: z.boolean().optional(),
+        evidenceRefs: z.array(EvidenceRefSchema).transform((refs) => refs.slice(0, MCP_OVERVIEW_REF_CAP)),
+    })).transform((spans) => spans.slice(0, MCP_OVERVIEW_SPAN_CAP)),
 });
 /**
  * The MCP-exposed shape of `_meta.report_data`. All fields optional —
@@ -797,14 +937,22 @@ export const ResearchReportDataSchema = z
     hypothesisResults: z
         .array(HypothesisResultSchema)
         .optional()
-        .describe('Per-hypothesis verdicts (status + confidence + evidence), each carrying its robustness re-ask survival count when re-tested.'),
+        .describe('Per-hypothesis results. Prefer `final`: it is the effective verdict, categorical reliability, evidence sufficiency and robustness outcome. Raw `status` and numeric `confidence` are legacy compatibility fields; do not rank or compare the numeric measure.'),
     insights: z
         .array(InsightSchema)
         .optional()
         .describe('Typed insight findings. Fresh source rows carry exact RRCP ids; legacy string rows remain inert text.'),
+    crossCuttingFindings: z
+        .array(CrossCuttingFindingSchema.optional().catch(undefined))
+        .optional()
+        .catch(undefined)
+        .describe('Evidence-gated cross-method findings. Present empty means the gate ran and no candidate qualified.'),
     keyFindings: z.array(z.string()).optional(),
     recommendations: z.array(z.unknown()).optional(),
     executiveSummary: z.string().optional(),
+    reportTitle: z.string().optional(),
+    marketOverview: ReportOverviewSchema.optional().catch(undefined),
+    communityOverview: ReportOverviewSchema.optional().catch(undefined),
     personasSynthesis: PersonasSynthesisSchema
         .optional()
         .catch(undefined)
@@ -934,19 +1082,195 @@ export const ResearchReportDataSchema = z
  * rather than represented as empty; absence says "unreadable", while `[]` would
  * falsely say the run recorded no highlights.
  */
+const MCP_REPORT_TITLE_MAX_CODE_POINTS = 160;
+export function sanitizeMcpMarkdownTitle(value) {
+    if (typeof value !== 'string')
+        return 'Report';
+    const title = value
+        .replace(/[\p{Cc}\p{Cf}]/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return title && Array.from(title).length <= MCP_REPORT_TITLE_MAX_CODE_POINTS ? title : 'Report';
+}
+export function sanitizeMcpReportTitle(value) {
+    const title = sanitizeMcpMarkdownTitle(value);
+    const latinWords = title.match(/[\p{L}\p{N}]+(?:['’-][\p{L}\p{N}]+)*/gu) ?? [];
+    const cjkCharacters = title.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu) ?? [];
+    const words = latinWords.filter((word) => !/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u.test(word)).length + cjkCharacters.length;
+    return words >= 6 && words <= 12 ? title : 'Report';
+}
 export function projectReportDataForMcp(raw) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
         return raw;
     const record = raw;
+    const asProjectionRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+    const safeProjectionUrl = (value) => {
+        if (typeof value !== 'string' || !/^https?:\/\//i.test(value))
+            return false;
+        try {
+            const url = new URL(value);
+            return (url.protocol === 'http:' || url.protocol === 'https:') &&
+                !url.username && !url.password;
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasProjectionVisibleContent = (value) => typeof value === 'string' &&
+        value.replace(/[\p{C}\p{Z}\p{Default_Ignorable_Code_Point}]/gu, '').length > 0;
     const hasHighlights = Object.prototype.hasOwnProperty.call(record, 'interviewHighlights');
+    const hasHypothesisResults = Object.prototype.hasOwnProperty.call(record, 'hypothesisResults');
+    const hasReportTitle = Object.prototype.hasOwnProperty.call(record, 'reportTitle');
+    const hasOverview = Object.prototype.hasOwnProperty.call(record, 'marketOverview') ||
+        Object.prototype.hasOwnProperty.call(record, 'communityOverview');
+    const hasCrossCutting = Object.prototype.hasOwnProperty.call(record, 'crossCuttingFindings');
+    const hasPersonas = Object.prototype.hasOwnProperty.call(record, 'personas');
+    const hasForumResearch = Object.prototype.hasOwnProperty.call(record, 'forumResearch');
     const methodology = record.methodology;
     const hasRedditNote = methodology !== null &&
         typeof methodology === 'object' &&
         !Array.isArray(methodology) &&
         Object.prototype.hasOwnProperty.call(methodology, 'redditRetrieval');
-    if (!hasHighlights && !hasRedditNote)
+    if (!hasHighlights && !hasRedditNote && !hasHypothesisResults && !hasOverview && !hasReportTitle && !hasCrossCutting && !hasPersonas && !hasForumResearch)
         return raw;
     const projected = { ...record };
+    if (hasReportTitle)
+        projected.reportTitle = sanitizeMcpReportTitle(record.reportTitle);
+    // Validate the frozen decoration before either the typed parse or raw schema-drift exit.
+    // Rebuilding only this field preserves the full forward-compatible persona object while an
+    // object, identifier-bearing value or arbitrary URL fails closed to the normal initials path.
+    if (hasPersonas && Array.isArray(record.personas)) {
+        projected.personas = record.personas.map((rawPersona) => {
+            const persona = asProjectionRecord(rawPersona);
+            if (!persona)
+                return rawPersona;
+            const nextPersona = { ...persona };
+            const portrait = ReportPortraitSchema.safeParse(persona.portrait);
+            if (portrait.success)
+                nextPersona.portrait = portrait.data;
+            else
+                delete nextPersona.portrait;
+            return nextPersona;
+        });
+    }
+    else if (hasPersonas) {
+        // A malformed container must not survive the raw schema-drift exit with an arbitrary nested
+        // URL or identifier. Absence is the only honest forward-compatible projection here.
+        delete projected.personas;
+    }
+    // `forumResearch` is intentionally forward-compatible and currently crosses the full-report
+    // schema through `.passthrough()`. Scrub its optional display label before both the typed and
+    // raw-drift exits so a source-title copy cannot survive in `_meta.report_data` even when the
+    // prose renderer correctly withholds it.
+    if (hasForumResearch) {
+        const forum = asProjectionRecord(record.forumResearch);
+        if (forum) {
+            const nextForum = { ...forum };
+            if (Array.isArray(forum.threads)) {
+                nextForum.threads = forum.threads.map((rawThread) => {
+                    const thread = asProjectionRecord(rawThread);
+                    if (!thread)
+                        return rawThread;
+                    const nextThread = { ...thread };
+                    const theme = typeof thread.title === 'string'
+                        ? readSemanticTheme(thread.theme, thread.title)
+                        : null;
+                    if (theme === null) {
+                        delete nextThread.theme;
+                    }
+                    else {
+                        nextThread.theme = theme;
+                    }
+                    return nextThread;
+                });
+            }
+            else {
+                delete nextForum.threads;
+            }
+            projected.forumResearch = nextForum;
+        }
+        else {
+            delete projected.forumResearch;
+        }
+    }
+    const projectOverviewRef = (rawRef) => {
+        if (rawRef === null || typeof rawRef !== 'object' || Array.isArray(rawRef))
+            return null;
+        const ref = rawRef;
+        if (ref.kind === 'report_evidence' && typeof ref.sourceId === 'string' && ref.sourceId.length > 0) {
+            return { kind: 'report_evidence', sourceId: ref.sourceId };
+        }
+        if (ref.kind === 'forum_receipt' &&
+            parseReceiptId(ref.receiptId)) {
+            return { kind: 'forum_receipt', receiptId: ref.receiptId };
+        }
+        if (ref.kind === 'interview_quote_v2' &&
+            typeof ref.interviewId === 'string' && ref.interviewId.length > 0 &&
+            typeof ref.quoteId === 'string' && ref.quoteId.length > 0) {
+            return { kind: 'interview_quote_v2', interviewId: ref.interviewId, quoteId: ref.quoteId };
+        }
+        if (ref.kind === 'hypothesis' && typeof ref.hypothesisId === 'string' && ref.hypothesisId.length > 0) {
+            return { kind: 'hypothesis', hypothesisId: ref.hypothesisId };
+        }
+        // Interview references and unknown future variants are private by default. Rebuilding every
+        // surviving object from an allowlist prevents schema-drift fallback from carrying opaque ids.
+        return null;
+    };
+    for (const key of ['marketOverview', 'communityOverview']) {
+        const overview = record[key];
+        if (overview === null || typeof overview !== 'object' || Array.isArray(overview)) {
+            delete projected[key];
+            continue;
+        }
+        const overviewRecord = overview;
+        if (typeof overviewRecord.text !== 'string' || !Array.isArray(overviewRecord.claimSpans)) {
+            delete projected[key];
+            continue;
+        }
+        const claimSpans = overviewRecord.claimSpans.slice(0, MCP_OVERVIEW_SPAN_CAP).flatMap((rawClaim) => {
+            if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim))
+                return [];
+            const claim = rawClaim;
+            if (typeof claim.span !== 'string' ||
+                (claim.claimType !== 'externally_checkable' && claim.claimType !== 'inference'))
+                return [];
+            const rawEvidenceRefs = Array.isArray(claim.evidenceRefs) ? claim.evidenceRefs : [];
+            const evidenceRefs = [];
+            const seenRefs = new Set();
+            for (const rawRef of rawEvidenceRefs.slice(0, MCP_OVERVIEW_REF_CAP)) {
+                const safeRef = projectOverviewRef(rawRef);
+                if (!safeRef)
+                    continue;
+                const refKey = safeRef.kind === 'report_evidence'
+                    ? `${safeRef.kind}:${safeRef.sourceId}`
+                    : safeRef.kind === 'forum_receipt'
+                        ? `${safeRef.kind}:${safeRef.receiptId}`
+                        : safeRef.kind === 'interview_quote_v2'
+                            ? `${safeRef.kind}:${safeRef.interviewId}:${safeRef.quoteId}`
+                            : `${safeRef.kind}:${safeRef.hypothesisId}`;
+                if (seenRefs.has(refKey))
+                    continue;
+                seenRefs.add(refKey);
+                evidenceRefs.push(safeRef);
+            }
+            return [{
+                    span: claim.span,
+                    claimType: claim.claimType,
+                    evidenceRefsTruncated: rawEvidenceRefs.length > MCP_OVERVIEW_REF_CAP,
+                    evidenceRefs,
+                }];
+        });
+        projected[key] = {
+            text: overviewRecord.text,
+            claimSpansTruncated: overviewRecord.claimSpans.length > MCP_OVERVIEW_SPAN_CAP,
+            claimSpans,
+        };
+    }
+    // Cross-cutting refs must resolve against the exact public projection. A malformed sibling
+    // withdraws the all-or-nothing highlight block below, so validating against the raw array would
+    // retain a finding whose cited quote is absent from structured output and rendered evidence.
     if (hasHighlights) {
         const highlights = z.array(InterviewHighlightSchema).safeParse(record.interviewHighlights);
         if (highlights.success)
@@ -954,6 +1278,143 @@ export function projectReportDataForMcp(raw) {
         else
             delete projected.interviewHighlights;
     }
+    if (hasCrossCutting) {
+        // Current reports replace the legacy surface. The projection is itself externally visible
+        // under `_meta.report_data`, so suppressing only the composed prose would still leak it.
+        delete projected.insights;
+        const resolvesCrossCuttingRef = (ref) => {
+            if (ref.kind === 'report_evidence') {
+                const match = /^RRCP-s(0|[1-9]\d*)$/.exec(ref.sourceId ?? '');
+                const source = match && asProjectionRecord(Array.isArray(record.reportEvidence)
+                    ? record.reportEvidence[Number(match[1])]
+                    : undefined);
+                return Boolean(source &&
+                    safeProjectionUrl(source.url) &&
+                    (source.section === 'market' || source.section === 'competitor' || source.section === 'summary'));
+            }
+            if (ref.kind === 'forum_receipt') {
+                const matches = (Array.isArray(asProjectionRecord(record.forumResearch)?.threads)
+                    ? asProjectionRecord(record.forumResearch).threads
+                    : []).flatMap((rawThread) => {
+                    const thread = asProjectionRecord(rawThread);
+                    return (Array.isArray(thread?.receipts) ? thread.receipts : []).filter((rawReceipt) => {
+                        const receipt = asProjectionRecord(rawReceipt);
+                        return Boolean(receipt && receipt.receiptId === ref.receiptId &&
+                            hasProjectionVisibleContent(receipt.excerpt));
+                    });
+                });
+                return matches.length === 1;
+            }
+            if (ref.kind === 'interview_quote_v2') {
+                const matches = (Array.isArray(projected.interviewHighlights) ? projected.interviewHighlights : [])
+                    .flatMap((rawHighlight) => {
+                    const evidence = asProjectionRecord(asProjectionRecord(rawHighlight)?.evidenceReference);
+                    if (!evidence || evidence.interviewId !== ref.interviewId)
+                        return [];
+                    return (Array.isArray(evidence.quotes) ? evidence.quotes : []).filter((rawQuote) => {
+                        const quote = asProjectionRecord(rawQuote);
+                        return Boolean(quote && quote.quoteId === ref.quoteId &&
+                            hasProjectionVisibleContent(quote.text));
+                    });
+                });
+                return matches.length === 1;
+            }
+            return false;
+        };
+        projected.crossCuttingFindings = Array.isArray(record.crossCuttingFindings)
+            ? record.crossCuttingFindings.slice(0, 5).flatMap((rawFinding) => {
+                if (rawFinding === null || typeof rawFinding !== 'object' || Array.isArray(rawFinding))
+                    return [];
+                const finding = rawFinding;
+                if (!hasProjectionVisibleContent(finding.claim) ||
+                    !hasProjectionVisibleContent(finding.whyItMatters) ||
+                    !['low', 'medium', 'high'].includes(String(finding.confidence)))
+                    return [];
+                const rawEvidenceRefs = Array.isArray(finding.evidenceRefs) ? finding.evidenceRefs : [];
+                const evidenceRefs = rawEvidenceRefs
+                    .slice(0, 8)
+                    .flatMap((rawRef) => {
+                    const ref = projectOverviewRef(rawRef);
+                    return ref ? [ref] : [];
+                });
+                const methods = new Set(evidenceRefs.map((ref) => ref.kind));
+                const refKeys = new Set(evidenceRefs.map((ref) => JSON.stringify(ref)));
+                if (rawEvidenceRefs.length < 2 ||
+                    rawEvidenceRefs.length > 8 ||
+                    evidenceRefs.length !== rawEvidenceRefs.length ||
+                    refKeys.size < 2 ||
+                    methods.size < 2 ||
+                    !evidenceRefs.every(resolvesCrossCuttingRef))
+                    return [];
+                return [{
+                        claim: finding.claim,
+                        whyItMatters: finding.whyItMatters,
+                        confidence: finding.confidence,
+                        evidenceRefs,
+                    }];
+            })
+            : [];
+    }
+    if (hasHypothesisResults && Array.isArray(record.hypothesisResults)) {
+        projected.hypothesisResults = record.hypothesisResults.map((rawRow) => {
+            if (rawRow === null || typeof rawRow !== 'object' || Array.isArray(rawRow))
+                return rawRow;
+            const row = rawRow;
+            const safeRow = { ...row };
+            let changed = false;
+            if (Object.prototype.hasOwnProperty.call(row, 'final')) {
+                const normalized = normalizeFinalHypothesisState(row);
+                if (normalized)
+                    safeRow.final = normalized;
+                else
+                    delete safeRow.final;
+                changed = safeRow.final !== row.final;
+            }
+            const rawRobustness = row.robustness;
+            const robustnessRecord = rawRobustness !== null &&
+                typeof rawRobustness === 'object' &&
+                !Array.isArray(rawRobustness)
+                ? rawRobustness
+                : null;
+            const nonRecordRobustnessIsUnsafe = rawRobustness !== undefined && rawRobustness !== null && robustnessRecord === null;
+            const parentStatusIsUnsafe = robustnessRecord !== null &&
+                !VERDICT_STATUSES.includes(row.status);
+            const carriesMeasuredCounts = robustnessRecord !== null &&
+                (Object.prototype.hasOwnProperty.call(robustnessRecord, 'survived') ||
+                    Object.prototype.hasOwnProperty.call(robustnessRecord, 'total'));
+            const carriesVariants = robustnessRecord !== null &&
+                Object.prototype.hasOwnProperty.call(robustnessRecord, 'variants');
+            const carriesOriginalStatus = robustnessRecord !== null &&
+                Object.prototype.hasOwnProperty.call(robustnessRecord, 'originalStatus');
+            const originalStatusMatches = robustnessRecord !== null &&
+                robustnessRecord.originalStatus === row.status;
+            const workingIsUnsafe = carriesVariants && robustnessWorkingContradictsSummary(robustnessRecord);
+            const originalStatusIsUnsafe = carriesOriginalStatus && !originalStatusMatches;
+            const measuredCountsAreUnsafe = carriesMeasuredCounts && !readRobustnessCounts(robustnessRecord);
+            if (nonRecordRobustnessIsUnsafe || parentStatusIsUnsafe) {
+                delete safeRow.robustness;
+                changed = true;
+            }
+            else if (robustnessRecord && (workingIsUnsafe || originalStatusIsUnsafe || measuredCountsAreUnsafe)) {
+                // Keep a readable downgrade: a broken diagnostic ratio must not erase the weakest
+                // recorded verdict. Contradictory detail cannot authenticate the summary or dependent
+                // final block, so neither may cross the typed or raw-drift exit.
+                const safeRobustness = { ...robustnessRecord };
+                delete safeRobustness.survived;
+                delete safeRobustness.total;
+                delete safeRobustness.flipped;
+                if (workingIsUnsafe || originalStatusIsUnsafe)
+                    delete safeRobustness.variants;
+                if (originalStatusIsUnsafe)
+                    delete safeRobustness.originalStatus;
+                safeRow.robustness = safeRobustness;
+                changed = true;
+            }
+            if (!changed)
+                return rawRow;
+            return safeRow;
+        });
+    }
     // ⚠️ FUL-685 — THE REDDIT NOTE IS PROJECTED HERE FOR THE SAME REASON `researchTaskId` IS:
     // `prepareReportDataForMcp` returns this projection UNPARSED when the full schema drifts, so a
     // field stripped only by `RedditRetrievalNoteSchema` would come straight back on that path — and
@@ -1191,6 +1652,14 @@ export const MarketSizingLineSchema = z
         }
     }
 });
+export const MarketSignalReferenceSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('size'), scope: z.enum(['tam', 'sam', 'som']) }),
+    z.object({
+        kind: z.enum(['growth', 'buying_behavior', 'category_dynamics']),
+        claimId: z.string().regex(/^RCLM-m(?:0|[1-9]\d*)$/),
+        sourceId: z.string().regex(/^RRCP-s(?:0|[1-9]\d*)$/).optional(),
+    }),
+]);
 /**
  * The market block a run established — the shape `scan_market` (FUL-479) surfaces to the caller
  * and the server promotes into the Research → Market dossier.
@@ -1201,28 +1670,28 @@ export const MarketSizingLineSchema = z
  * benefit, not an agent's. `extractMarket` does the flattening so this mirror describes what the
  * agent is actually being told, and every field here maps 1:1 onto a `project_market` column.
  *
- * ⚠️ THESE FIGURES ARE UNGRADED ON THIS SURFACE, exactly as `get_market`'s are. Per-claim trust
- * state is reconstructed app-side from the run's claim spine and does not cross the package
- * boundary, so nothing here carries a `[GROUNDED]`-style bracket. Silence is not a clean bill of
- * health, and the tool description says so beside the figures.
+ * `marketSignals` below are producer selectors, not proof on their own. `extractMarket` resolves
+ * them against exact claims, receipts, and derivations and exposes only survivors as
+ * `resolvedSignals`. The other fields remain legacy recorded context and never inherit a
+ * selector's authority.
  */
 export const MarketFindingsSchema = z
     .object({
     estimatedMarketSize: z
         .string()
         .optional()
-        .describe('The run\'s headline market SIZE, in the source\'s own words. Derived by the producer as ' +
+        .describe('Legacy raw recorded market-size context, in the source\'s own words. Derived by the producer as ' +
         'the first claim that is a size (never a rate). Absent or empty when the run established ' +
-        'no size — which is a result, not a zero.'),
+        'no size — which is a result, not a zero. Neutral unless emitted separately as a strict resolved signal.'),
     growthTrend: z
         .string()
         .optional()
-        .describe('"growing" | "stable" | "declining" | "unknown". "unknown" is a real finding: the sources disagreed or said nothing.'),
-    keyTrends: z.array(z.string()).optional().describe('Industry trends this run found moving the market.'),
+        .describe('Raw reported direction: "growing" | "stable" | "declining" | "unknown". Neutral recorded context, never cited growth; "unknown" means the sources disagreed or said nothing.'),
+    keyTrends: z.array(z.string()).optional().describe('Neutral legacy context: industry trends this run recorded as moving the market.'),
     claims: z
         .array(MarketClaimLineSchema)
         .optional()
-        .describe('Every atomic market figure the run recorded, one figure per entry, each with its own scope label where the source named one.'),
+        .describe('Raw recorded atomic market figures, one per entry, with source-named scope where present. Neutral legacy context, not independently citable.'),
     marketSizing: z
         .array(z.unknown())
         .transform((items) => items.flatMap((item) => {
@@ -1230,11 +1699,19 @@ export const MarketFindingsSchema = z
         return parsed.success ? [parsed.data] : [];
     }))
         .optional()
-        .describe('Typed TAM/SAM/SOM entries. Malformed siblings are omitted; never infer a replacement.'),
+        .describe('Typed TAM/SAM/SOM proof candidates. Malformed siblings are omitted; only entries selected and proven in resolvedSignals are citable.'),
+    marketSignals: z
+        .array(z.unknown())
+        .transform((items) => items.slice(0, 3).flatMap((item) => {
+        const parsed = MarketSignalReferenceSchema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    }))
+        .optional()
+        .describe('Zero-to-three ordered producer selectors, not independently citable. extractMarket emits a selector in resolvedSignals only after strict sizing proof or an exact grounded claim, non-empty contained quote span, and receipt. Empty resolvedSignals means no selector survived proof, not that the raw context or market is absent, small, or zero.'),
     positioningGaps: z
         .array(z.string())
         .optional()
-        .describe('Segments the category under-serves and needs available tools do not meet, as the run\'s sources describe them — market-side observations, not a competitor comparison.'),
+        .describe('Neutral legacy context: segments the category under-serves and needs available tools do not meet, as recorded by the run; not independently citable or a competitor comparison.'),
 })
     .passthrough();
 /**
@@ -1245,6 +1722,14 @@ export const MarketFindingsSchema = z
 export const ForumThreadSchema = z
     .object({
     title: z.string(),
+    theme: z
+        .string()
+        .trim()
+        .max(48)
+        .regex(/^[\p{L}\p{N}]+(?:[\p{Pd}'’][\p{L}\p{N}]+)*(?: [\p{L}\p{N}]+(?:[\p{Pd}'’][\p{L}\p{N}]+)*)?$/u)
+        .optional()
+        .catch(undefined)
+        .describe('Producer-authored 1-2-word semantic theme. Distinct from title, which remains source metadata and the discussion link label.'),
     url: z.string().optional(),
     platform: z.string().optional(),
     /**
@@ -1319,5 +1804,16 @@ export const ForumThreadSchema = z
         .describe('Receipt children of this discussion, when it yielded several bounded excerpts. Each names ' +
         'one exact excerpt in `relevantQuotes`; absent means no rail minted per-excerpt ids for it.'),
 })
-    .passthrough();
+    .passthrough()
+    .overwrite((thread) => {
+    if (!thread.theme)
+        return thread;
+    const theme = readSemanticTheme(thread.theme, thread.title);
+    if (theme === null) {
+        const withoutTheme = { ...thread };
+        delete withoutTheme.theme;
+        return withoutTheme;
+    }
+    return theme === thread.theme ? thread : { ...thread, theme };
+});
 //# sourceMappingURL=report.js.map