opencandle 0.6.0 → 0.7.0

package/src/providers/reddit.ts

@@ -1,53 +1,23 @@
 import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { httpGet } from "../infra/http-client.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
 import { BEARISH_TERMS, BULLISH_TERMS } from "../sentiment/keywords.js";
 import type { RedditSentimentResult } from "../types/sentiment.js";
-
-interface RedditListingResponse {
-  data: {
-    children: Array<{
-      data: {
-        id: string;
-        title: string;
-        selftext: string;
-        author: string;
-        score: number;
-        num_comments: number;
-        permalink: string;
-        created_utc: number;
-      };
-    }>;
-  };
-}
-
-const REDDIT_HEADERS = { "User-Agent": "OpenCandle/1.0 (financial analysis agent)" };
+import { listSubredditPosts, readRedditPost, searchRedditPosts } from "./reddit-cli.js";
 
 export async function getSubredditPosts(
   subreddit: string,
   limit: number = 25,
+  query?: string,
 ): Promise<RedditSentimentResult> {
-  const cacheKey = `reddit:${subreddit}:${limit}`;
+  const cacheKey = `reddit:${subreddit}:${query ?? "hot"}:${limit}`;
   const cached = cache.get<RedditSentimentResult>(cacheKey);
   if (cached) return cached;
 
   try {
     await rateLimiter.acquire("reddit");
-    const url = `https://www.reddit.com/r/${encodeURIComponent(subreddit)}/hot.json?limit=${limit}`;
-    const data = await httpGet<RedditListingResponse>(url, {
-      headers: REDDIT_HEADERS,
-    });
-
-    const posts = data.data.children.map((child) => ({
-      id: child.data.id,
-      title: child.data.title,
-      selftext: child.data.selftext ?? "",
-      author: child.data.author ?? "unknown",
-      score: child.data.score,
-      comments: child.data.num_comments,
-      url: `https://reddit.com${child.data.permalink}`,
-      created: new Date(child.data.created_utc * 1000).toISOString(),
-    }));
+    const posts = query
+      ? await searchRedditPosts(query, { subreddit, limit })
+      : await listSubredditPosts(subreddit, { limit });
 
     // Extract ticker-like mentions ($AAPL, $TSLA, etc.)
     const tickerRegex = /\$([A-Z]{1,5})\b/g;
@@ -107,33 +77,7 @@ export async function getPostComments(
   if (cached) return cached;
 
   await rateLimiter.acquire("reddit_comments");
-  const url = `https://www.reddit.com/r/${encodeURIComponent(subreddit)}/comments/${postId}.json`;
-  const data = await httpGet<
-    Array<{
-      data: {
-        children: Array<{
-          kind: string;
-          data: { id: string; body?: string; author?: string; score?: number; permalink?: string };
-        }>;
-      };
-    }>
-  >(url, {
-    headers: REDDIT_HEADERS,
-  });
-
-  // Comments are in the second listing element
-  const commentListing = data[1]?.data?.children ?? [];
-  const comments: RedditComment[] = commentListing
-    .filter((c) => c.kind === "t1" && c.data.body)
-    .sort((a, b) => (b.data.score ?? 0) - (a.data.score ?? 0))
-    .slice(0, limit)
-    .map((c) => ({
-      id: c.data.id,
-      body: c.data.body!,
-      author: c.data.author ?? "unknown",
-      score: c.data.score ?? 0,
-      permalink: `https://reddit.com${c.data.permalink ?? ""}`,
-    }));
+  const { comments } = await readRedditPost(postId, { limit });
 
   cache.set(cacheKey, comments, COMMENT_TTL);
   return comments;

package/src/providers/twitter-cli.ts

@@ -0,0 +1,233 @@
+import { spawn } from "node:child_process";
+import type { TwitterTweet } from "../types/sentiment.js";
+import { ExternalToolError, ExternalToolNotInstalled } from "./external-tool-error.js";
+
+const TWITTER_CLI_BINARY = "twitter";
+const TWITTER_CLI_TOOL_NAME = "twitter-cli";
+const TWITTER_CLI_INSTALL_CMD = "uv tool install twitter-cli";
+const COMMAND_TIMEOUT_MS = 20_000;
+const MAX_OUTPUT_CHARS = 2_000_000;
+
+export interface RawTweet {
+  readonly id?: string;
+  readonly text?: string;
+  readonly author?: {
+    readonly username?: string;
+    readonly screenName?: string;
+    readonly name?: string;
+  };
+  readonly username?: string;
+  readonly url?: string;
+  readonly permanentUrl?: string;
+  readonly createdAt?: string | number;
+  readonly created_at?: string | number;
+  readonly likeCount?: number;
+  readonly likes?: number;
+  readonly retweetCount?: number;
+  readonly retweets?: number;
+  readonly replyCount?: number;
+  readonly replies?: number;
+  readonly viewCount?: number | null;
+  readonly views?: number | null;
+  readonly metrics?: {
+    readonly likes?: number;
+    readonly retweets?: number;
+    readonly replies?: number;
+    readonly views?: number | null;
+  };
+}
+
+interface TwitterCliEnvelope<T> {
+  readonly ok: boolean;
+  readonly schema_version: string;
+  readonly data: T;
+  readonly error?: {
+    readonly code?: string;
+    readonly message?: string;
+  };
+}
+
+interface CommandResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+type TwitterCliCommandRunner = (command: string, args: readonly string[]) => Promise<CommandResult>;
+
+let commandRunner: TwitterCliCommandRunner = runCommand;
+
+export function setTwitterCliCommandRunnerForTests(runner: TwitterCliCommandRunner): void {
+  commandRunner = runner;
+}
+
+export function resetTwitterCliCommandRunnerForTests(): void {
+  commandRunner = runCommand;
+}
+
+export async function searchTweets(query: string, max = 20): Promise<TwitterTweet[]> {
+  const envelope = await runTwitterCli<TwitterCliEnvelope<RawTweet[]>>([
+    "search",
+    query,
+    "--max",
+    String(max),
+    "-t",
+    "Latest",
+    "--json",
+  ]);
+
+  if (!envelope.ok) {
+    throw new ExternalToolError(
+      TWITTER_CLI_TOOL_NAME,
+      redactSensitiveOutput(envelope.error?.message ?? "twitter-cli returned an error"),
+      envelope.error?.code,
+    );
+  }
+  if (!Array.isArray(envelope.data)) {
+    throw new ExternalToolError(TWITTER_CLI_TOOL_NAME, "twitter-cli returned invalid tweet data");
+  }
+  return envelope.data.map(adaptRawTweet);
+}
+
+async function runTwitterCli<T>(args: readonly string[]): Promise<T> {
+  let result: CommandResult;
+  try {
+    result = await commandRunner(TWITTER_CLI_BINARY, args);
+  } catch (err) {
+    const nodeError = err as NodeJS.ErrnoException;
+    if (nodeError.code === "ENOENT") {
+      throw new ExternalToolNotInstalled(TWITTER_CLI_TOOL_NAME, TWITTER_CLI_INSTALL_CMD);
+    }
+    throw new ExternalToolError(
+      TWITTER_CLI_TOOL_NAME,
+      redactSensitiveOutput(err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  if (result.code !== 0) {
+    const envelopeError = parseCliErrorEnvelope(result.stdout);
+    if (envelopeError) {
+      throw new ExternalToolError(
+        TWITTER_CLI_TOOL_NAME,
+        redactSensitiveOutput(envelopeError.message),
+        envelopeError.code,
+      );
+    }
+    throw new ExternalToolError(
+      TWITTER_CLI_TOOL_NAME,
+      redactSensitiveOutput(result.stderr.trim() || `twitter-cli exited with code ${result.code}`),
+    );
+  }
+
+  try {
+    return JSON.parse(result.stdout) as T;
+  } catch {
+    throw new ExternalToolError(
+      TWITTER_CLI_TOOL_NAME,
+      `twitter-cli returned non-JSON output: ${redactSensitiveOutput(result.stdout.slice(0, 200))}`,
+    );
+  }
+}
+
+function parseCliErrorEnvelope(stdout: string): { code?: string; message: string } | null {
+  try {
+    const parsed = JSON.parse(stdout) as {
+      ok?: unknown;
+      error?: { code?: unknown; message?: unknown };
+    };
+    if (parsed.ok !== false || typeof parsed.error?.message !== "string") return null;
+    return {
+      code: typeof parsed.error.code === "string" ? parsed.error.code : undefined,
+      message: parsed.error.message,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function adaptRawTweet(raw: RawTweet): TwitterTweet {
+  return {
+    id: stringValue(raw.id),
+    text: stringValue(raw.text).slice(0, 280),
+    author:
+      stringValue(raw.author?.username) ||
+      stringValue(raw.author?.screenName) ||
+      stringValue(raw.username) ||
+      "unknown",
+    likes: numberValue(raw.metrics?.likes ?? raw.likeCount ?? raw.likes),
+    retweets: numberValue(raw.metrics?.retweets ?? raw.retweetCount ?? raw.retweets),
+    replies: numberValue(raw.metrics?.replies ?? raw.replyCount ?? raw.replies),
+    views: nullableNumberValue(raw.metrics?.views ?? raw.viewCount ?? raw.views),
+    url: stringValue(raw.url ?? raw.permanentUrl),
+    created: normalizeCreatedAt(raw.createdAt ?? raw.created_at),
+  };
+}
+
+function normalizeCreatedAt(value: string | number | undefined): string {
+  if (typeof value === "number") {
+    const millis = value > 1_000_000_000_000 ? value : value * 1000;
+    return new Date(millis).toISOString();
+  }
+  if (typeof value === "string" && value.length > 0) {
+    const millis = Date.parse(value);
+    if (!Number.isNaN(millis)) return new Date(millis).toISOString();
+  }
+  return new Date(0).toISOString();
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function nullableNumberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function redactSensitiveOutput(input: string): string {
+  const xCookieNames =
+    "auth_token|ct0|twid|kdt|guest_id|guest_id_ads|guest_id_marketing|personalization_id";
+  return input
+    .slice(0, MAX_OUTPUT_CHARS)
+    .replace(/\b(cookie|set-cookie)\s*:\s*[^\r\n]+/gi, "$1: [redacted]")
+    .replace(new RegExp(`\\b(${xCookieNames})\\b\\s*[:=]\\s*[^;\\s,)]+`, "gi"), "$1=[redacted]")
+    .replace(new RegExp(`\\b(${xCookieNames})=([^;\\s,)]+)`, "gi"), "$1=[redacted]");
+}
+
+function runCommand(command: string, args: readonly string[]): Promise<CommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(new Error(`${command} timed out after ${COMMAND_TIMEOUT_MS}ms`));
+    }, COMMAND_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout = (stdout + chunk.toString("utf8")).slice(0, MAX_OUTPUT_CHARS);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr = (stderr + chunk.toString("utf8")).slice(0, MAX_OUTPUT_CHARS);
+    });
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}

package/src/providers/twitter.ts

@@ -1,37 +1,7 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { Scraper, SearchMode } from "@the-convocation/twitter-scraper";
-import Database from "better-sqlite3";
 import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { getBrowserProfileDir } from "../infra/opencandle-paths.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
 import type { TwitterSentimentResult, TwitterTweet } from "../types/sentiment.js";
-
-// ── Cookie extraction ────────────────────────────────────
-
-interface FirefoxCookie {
-  name: string;
-  value: string;
-  domain: string;
-  path: string;
-}
-
-export function readTwitterCookies(profileDir: string): FirefoxCookie[] {
-  const dbPath = join(profileDir, "cookies.sqlite");
-  if (!existsSync(dbPath)) return [];
-
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    const rows = db
-      .prepare(
-        `SELECT name, value, host AS domain, path FROM moz_cookies WHERE host LIKE ? OR host LIKE ?`,
-      )
-      .all("%x.com%", "%twitter.com%") as FirefoxCookie[];
-    return rows;
-  } finally {
-    db.close();
-  }
-}
+import { searchTweets } from "./twitter-cli.js";
 
 // ── Sentiment scoring ────────────────────────────────────
 
@@ -87,49 +57,10 @@ export async function getTwitterSentiment(
   await rateLimiter.acquire("twitter");
 
   try {
-    const profileDir = getBrowserProfileDir();
-    const cookies = readTwitterCookies(profileDir);
-
-    const authToken = cookies.find((c) => c.name === "auth_token");
-    const ct0 = cookies.find((c) => c.name === "ct0");
-
-    if (!authToken || !ct0) {
-      throw new Error("No Twitter session found.");
-    }
-
-    const scraper = new Scraper();
-    const cookieStrings = cookies.map(
-      (c) => `${c.name}=${c.value}; Domain=${c.domain}; Path=${c.path}`,
-    );
-    await scraper.setCookies(cookieStrings);
-
-    const loggedIn = await scraper.isLoggedIn();
-    if (!loggedIn) {
-      throw new Error("Twitter session expired.");
-    }
-
     const cutoff = new Date(Date.now() - hours * 3_600_000);
-    const tweets: TwitterTweet[] = [];
-    const results = scraper.searchTweets(normalizedQuery, limit, SearchMode.Latest);
-
-    for await (const tweet of results) {
-      const created = tweet.timeParsed ?? new Date(0);
-      if (created < cutoff) continue;
-
-      tweets.push({
-        id: tweet.id ?? "",
-        text: tweet.text?.slice(0, 280) ?? "",
-        author: tweet.username ?? "unknown",
-        likes: tweet.likes ?? 0,
-        retweets: tweet.retweets ?? 0,
-        replies: tweet.replies ?? 0,
-        views: tweet.views ?? null,
-        url: tweet.permanentUrl ?? "",
-        created: created.toISOString(),
-      });
-
-      if (tweets.length >= limit) break;
-    }
+    const tweets: TwitterTweet[] = (await searchTweets(normalizedQuery, limit))
+      .filter((tweet) => new Date(tweet.created) >= cutoff)
+      .slice(0, limit);
 
     // Extract co-mentioned cashtags
     const tickerRegex = /\$([A-Z]{1,5})\b/g;

package/src/providers/wrap-provider.ts

@@ -2,6 +2,7 @@ import { runWithStaleMetadata } from "../infra/cache.js";
 import type { ProviderResult } from "../runtime/evidence.js";
 import { getProviderTracker } from "../runtime/run-context.js";
 import { InvalidSymbolError } from "./errors.js";
+import { ExternalToolError, ExternalToolNotInstalled } from "./external-tool-error.js";
 import { ProviderCredentialError } from "./provider-credential-error.js";
 
 /**
@@ -51,6 +52,13 @@ export async function wrapProvider<T>(
     if (error instanceof ProviderCredentialError) {
       throw error;
     }
+    if (isExternalToolSetupError(error)) {
+      return {
+        status: "unavailable",
+        reason: error.message,
+        provider: providerId,
+      };
+    }
     if (error instanceof InvalidSymbolError) {
       return {
         status: "unavailable",
@@ -67,3 +75,29 @@ export async function wrapProvider<T>(
     };
   }
 }
+
+function isExternalToolSetupError(
+  error: unknown,
+): error is ExternalToolError | ExternalToolNotInstalled {
+  if (error instanceof ExternalToolNotInstalled) return true;
+  if (!(error instanceof ExternalToolError)) return false;
+
+  const code = error.code?.toLowerCase() ?? "";
+  const message = error.message.toLowerCase();
+  return (
+    code.includes("auth") ||
+    code.includes("session") ||
+    code.includes("unauthorized") ||
+    code.includes("expired") ||
+    message.includes("no twitter cookies") ||
+    message.includes("no twitter session") ||
+    message.includes("no reddit cookies") ||
+    message.includes("session missing") ||
+    message.includes("not authenticated") ||
+    message.includes("no cookies") ||
+    message.includes("rdt login") ||
+    message.includes("401") ||
+    message.includes("unauthorized") ||
+    message.includes("expired")
+  );
+}

package/src/providers/yahoo-finance.ts

@@ -1,4 +1,5 @@
-import { StealthBrowser } from "../infra/browser.js";
+import YahooFinance from "yahoo-finance2";
+import type { OptionsResult as YahooFinance2OptionsResult } from "yahoo-finance2/modules/options";
 import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
 import { HttpError, httpGet } from "../infra/http-client.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
@@ -17,6 +18,15 @@ const BASE_URL = "https://query1.finance.yahoo.com/v8/finance/chart";
 const QUOTE_SUMMARY_URL = "https://query1.finance.yahoo.com/v10/finance/quoteSummary";
 const STALE_QUOTE_MAX_RETRY_AFTER_MS = 1_000;
 
+let yahooFinance2Client: InstanceType<typeof YahooFinance> | undefined;
+
+function getYahooFinance2Client(): InstanceType<typeof YahooFinance> {
+  yahooFinance2Client ??= new YahooFinance({
+    suppressNotices: ["yahooSurvey", "ripHistorical"],
+  });
+  return yahooFinance2Client;
+}
+
 type YahooNumber = number | { raw?: number; fmt?: string };
 
 interface YahooChartResponse {
@@ -410,9 +420,9 @@ export async function getOptionsChain(symbol: string, expiration?: number): Prom
   if (!res?.ok) {
     let browserError: unknown;
     try {
-      const browserData = await fetchOptionsViaBrowser(symbol, expiration);
-      if (browserData) {
-        const chain = parseOptionsResponse(browserData);
+      const fallbackData = await fetchOptionsViaYahooFinance2(symbol, expiration);
+      if (fallbackData) {
+        const chain = parseOptionsResponse(fallbackData);
         cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
         return chain;
       }
@@ -425,14 +435,14 @@ export async function getOptionsChain(symbol: string, expiration?: number): Prom
     if (res) {
       const message = `Yahoo Finance options: HTTP ${res.status}`;
       if (browserError instanceof Error) {
-        throw new Error(`${message}; browser fallback failed: ${browserError.message}`);
+        throw new Error(`${message}; yahoo-finance2 fallback failed: ${browserError.message}`);
       }
       throw new Error(message);
     }
     if (browserError instanceof Error) {
       const message =
         fetchError instanceof Error ? fetchError.message : "Yahoo Finance options: fetch failed";
-      throw new Error(`${message}; browser fallback failed: ${browserError.message}`);
+      throw new Error(`${message}; yahoo-finance2 fallback failed: ${browserError.message}`);
     }
     throw fetchError instanceof Error
       ? fetchError
@@ -602,38 +612,61 @@ function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
 }
 
 /**
- * Fallback: fetch options data via Camoufox stealth browser.
- * Bypasses Yahoo's TLS fingerprinting and rate limiting.
+ * Fallback: fetch options data via yahoo-finance2 when the raw Yahoo path is blocked.
  */
-async function fetchOptionsViaBrowser(
+async function fetchOptionsViaYahooFinance2(
   symbol: string,
   expiration?: number,
 ): Promise<YahooOptionsResponse | null> {
   try {
-    // Avoid loading the script-heavy Yahoo Finance homepage: Playwright 1.60
-    // can crash on some pageerror payloads emitted by finance.yahoo.com.
-    // Navigating directly to Yahoo's JSON endpoints still uses the browser's
-    // cookies/TLS fingerprint without requiring cross-origin fetch from page JS.
-    const dateParam = expiration ? `&date=${expiration}` : "";
-    return await StealthBrowser.run(async (page) => {
-      await page.goto("https://query2.finance.yahoo.com/v1/test/getcrumb", {
-        waitUntil: "domcontentloaded",
-        timeout: 15000,
-      });
-      const crumb = (await page.locator("body").innerText()).trim();
-      if (!crumb) return null;
-
-      const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
-      const response = await page.goto(url, {
-        waitUntil: "domcontentloaded",
-        timeout: 15000,
-      });
-      if (!response?.ok()) return null;
-
-      const text = (await page.locator("body").innerText()).trim();
-      return JSON.parse(text) as YahooOptionsResponse;
-    });
+    const result = await getYahooFinance2Client().options(
+      symbol,
+      expiration ? { date: new Date(expiration * 1000) } : undefined,
+    );
+    return normalizeYahooFinance2OptionsResponse(result);
   } catch (error) {
     throw error instanceof Error ? error : new Error(String(error));
   }
 }
+
+function normalizeYahooFinance2OptionsResponse(
+  data: YahooFinance2OptionsResult | YahooOptionsResponse,
+): YahooOptionsResponse {
+  if ("optionChain" in data) return data as YahooOptionsResponse;
+
+  const options = data.options.map((option) => ({
+    expirationDate: toYahooUnixSeconds(option.expirationDate),
+    calls: option.calls,
+    puts: option.puts,
+  }));
+  const strikes = [
+    ...new Set(
+      options
+        .flatMap((option) => [...option.calls, ...option.puts])
+        .map((contract) => Number((contract as { strike?: unknown }).strike))
+        .filter((strike) => Number.isFinite(strike)),
+    ),
+  ].sort((a, b) => a - b);
+
+  return {
+    optionChain: {
+      result: [
+        {
+          underlyingSymbol: data.underlyingSymbol,
+          expirationDates: data.expirationDates.map(toYahooUnixSeconds),
+          strikes,
+          quote: data.quote as Record<string, any>,
+          options,
+        },
+      ],
+    },
+  };
+}
+
+function toYahooUnixSeconds(value: Date | number | string): number {
+  if (value instanceof Date) return Math.floor(value.getTime() / 1000);
+  if (typeof value === "number") {
+    return value > 1_000_000_000_000 ? Math.floor(value / 1000) : value;
+  }
+  return Math.floor(new Date(value).getTime() / 1000);
+}

package/src/routing/planning.ts

@@ -98,6 +98,7 @@ export type StructuredCheckId =
   | "freshness_disclosed"
   | "data_gap_disclosed"
   | "commitment_mode_respected"
+  | "required_final_fields_present"
   | "source_coverage_disclosed"
   | "capability_gap_disclosure"
   | "assumption_disclosed"

package/src/runtime/answer-contracts.ts

@@ -18,7 +18,9 @@ export type FinalAnswerField =
   | "freshness_disclosure"
   | "data_gap_disclosure"
   | "risk_downside"
-  | "source_coverage";
+  | "source_coverage"
+  | "sentiment_rationale"
+  | "confidence_or_caveats";
 
 export type FrameworkFallbackMode =
   | "not_allowed"
@@ -342,7 +344,12 @@ export const ANSWER_CONTRACT_REGISTRY: Record<AnswerContractId, AnswerContractDe
     commitmentMode: "framework",
     implemented: true,
     requiredEvidenceTypes: [],
-    requiredFinalFields: ["source_coverage", "data_gap_disclosure"],
+    requiredFinalFields: [
+      "source_coverage",
+      "sentiment_rationale",
+      "confidence_or_caveats",
+      "data_gap_disclosure",
+    ],
     requiresFreshness: false,
     requiresDataGapDisclosure: true,
     requiresRiskDownside: false,
@@ -408,6 +415,7 @@ export function runStructuredChecks(input: StructuredCheckInput): StructuredChec
     checkFreshness(input.contract, input.finalAnswerMetadata),
     checkDataGapDisclosure(input.contract, input.evidenceRecords, input.finalAnswerMetadata),
     checkCommitmentMode(input.contract, input.finalAnswerMetadata),
+    checkRequiredFinalFields(input.contract, input.finalAnswerMetadata),
     checkSourceCoverage(input.contract, input.finalAnswerMetadata),
     checkCapabilityGapDisclosure(input.contract, input.evidenceRecords, input.finalAnswerMetadata),
     ...semanticChecks(requestedChecks, input.answerText),
@@ -620,6 +628,19 @@ function checkCommitmentMode(
   );
 }
 
+function checkRequiredFinalFields(
+  contract: AnswerContractDefinition,
+  metadata: FinalAnswerMetadata,
+): StructuredCheckResult {
+  const fields = new Set(metadata.finalFields);
+  const missing = contract.requiredFinalFields.filter((field) => !fields.has(field));
+  return structuredResult(
+    "required_final_fields_present",
+    missing.length === 0,
+    missing.length > 0 ? `Missing required final fields: ${missing.join(", ")}` : undefined,
+  );
+}
+
 function checkSourceCoverage(
   contract: AnswerContractDefinition,
   metadata: FinalAnswerMetadata,