@clien-ai/mcp 0.12.0 → 0.12.2

package/dist/types/report.js

@@ -19,6 +19,8 @@ import { CONFIDENCE_BASES, CONFIDENCE_LEVELS, EVIDENCE_SUFFICIENCY_LEVELS, HYPOT
 // 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.
@@ -500,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
@@ -511,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.'),
@@ -835,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 —
@@ -873,9 +942,17 @@ export const ResearchReportDataSchema = 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)
@@ -1005,20 +1082,279 @@ 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 && !hasHypothesisResults)
+    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)
+            projected.interviewHighlights = highlights.data;
+        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))
@@ -1079,13 +1415,6 @@ export function projectReportDataForMcp(raw) {
             return safeRow;
         });
     }
-    if (hasHighlights) {
-        const highlights = z.array(InterviewHighlightSchema).safeParse(record.interviewHighlights);
-        if (highlights.success)
-            projected.interviewHighlights = highlights.data;
-        else
-            delete projected.interviewHighlights;
-    }
     // ⚠️ 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
@@ -1323,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.
@@ -1333,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) => {
@@ -1362,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();
 /**
@@ -1377,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(),
     /**
@@ -1451,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