Verified Financial Core

Provider-independent TypeScript contracts and infrastructure for traceable, historically correct A/H-share financial facts.

The repository separates two concerns:

• the Gateway determines whether a financial data package is reliable;
• downstream Research CI determines whether a report used that package correctly.

Research CI must consume a frozen VerifiedFactSet; it does not own another financial-data layer.

Current status

Implemented:

• canonical schema and concept registry;
• frozen VerifiedFactSet 1.1.0 wire contract with Zod and draft-07 JSON Schema exports;
• compatibility, source-independence, verification, derivations, and deterministic FactSet assembly;
• immutable SHA-256 raw snapshot storage and SQLite audit metadata;
• runtime-validated Provider contract;
• token-free CNINFO/HKEX official-filing, Eastmoney, Tencent, Baidu, and A-share THS financial Providers;
• optional local CNINFO OCR adapter for image-only Chinese financial statements, with page-level evidence and persisted OCR text snapshots;
• traceable, unadjusted Tencent/Eastmoney daily closes for historical asOf queries;
• annual A/H cash dividends per share with official CNINFO/HKEX arbitration, explicit aggregation, currency, scale, and conservative availability;
• exact cross-source comparison across different source scales;
• capability-aware Provider routing and request-level FactSet caching;
• automatic, traceable FCF, explicit-quarter TTM-flow, and market-cap derivation with direct-source facts taking precedence;
• offline FactSet replay and stale fallback on upstream failure;
• Gateway SDK orchestration and A/H instrument syntax resolution;
• offline-safe ah-context JSON CLI;
• provider-neutral fixture and Golden tests.

The local Gateway registers seven token-free Providers by default. CNINFO resolves A-share issuers and HKEX resolves H-share issuers; both discover periodic filings, snapshot official evidence, and extract a constrained set of financial facts. CNINFO's official implementation ledger and HKEX's EF001 cash-dividend announcements arbitrate Eastmoney's A/H dividend observations. Eastmoney also supplies A/H quotes and A-share statements; THS independently cross-checks A-share statements, Baidu independently cross-checks H-share statements, and Tencent/Baidu cover market and valuation fields. Official facts adjudicate compatible conflicts through the same verification core. A material official-versus-aggregator conflict remains fail-closed even when two aggregators agree, because they can share the same stale reporting version. HKEX preserves the statement currency and reported scale and uses the exchange's exact release minute for historical asOf filtering. H-share statements remain warning when HKEX is the only independent source. Current-view THS and Baidu facts do not claim a historical filing date and cannot independently backfill strict point-in-time requests. Tushare remains optional and the default runtime and test suite require no token or interface ledger.

Requirements

• Node.js 22 or newer (development baseline: 24.16.0)
• pnpm 8.15.6
• Bun 1.3 or newer (optional Dexter runtime compatibility test)

The project-local .npmrc uses the official npm registry without changing global npm configuration.

Development

pnpm install
pnpm check
pnpm test:coverage
pnpm test:bun

All default tests and the Bun/Dexter storage smoke test are offline. Public endpoint canaries are opt-in:

pnpm test:live

VerifiedFactSet contract

Gateway consumers validate the frozen handoff at their process boundary:

import { parseVerifiedFactSet } from "@verified-financial/schema";
import {
  VERIFIED_FACT_SET_JSON_SCHEMA,
} from "@verified-financial/schema/json-schema";

The Zod parser is authoritative for financial semantics; the draft-07 JSON Schema supports other runtimes and CI tooling. Newly generated FactSets also carry concept-registry, validation-rule, Provider mapping, and formula versions in lineageVersions.

See the VerifiedFactSet 1.1.0 compatibility contract.

CLI

Build and inspect the local Gateway:

pnpm build
pnpm --silent ah-context doctor
pnpm --silent ah-context resolve 600519.SH

TypeScript clients use the same local runtime as the CLI:

import { createLocalGateway } from "@verified-financial/local-gateway";

const local = createLocalGateway("./data");
try {
  const factSet = await local.gateway.facts(request);
  // Pass the frozen FactSet to Dexter, AI Berkshire, or Research CI.
} finally {
  local.close();
}

The shared runtime owns the default Provider registration and local snapshot stores. Client adapters must not recreate that data-routing layer.

Optional CNINFO OCR

The default Gateway remains text-only and does not load a Chinese OCR model or native Canvas runtime. Consumers that need image-only CNINFO statements can opt in through the separate TypeScript package:

import {
  createDefaultProviders,
  createLocalGateway,
} from "@verified-financial/local-gateway";
import {
  createCninfoOcrTextExtractor,
} from "@verified-financial/provider-cninfo-ocr";

const providers = createDefaultProviders({
  cninfo: {
    extractTextImplementation: createCninfoOcrTextExtractor({
      cacheDirectory: "./data/ocr-cache",
    }),
  },
});
const local = createLocalGateway("./data", providers);

The adapter first runs normal PDF text extraction and OCRs only a bounded blank page run that looks like an embedded financial-statement section. It renders locally at 3x scale, uses the bundled simplified-Chinese Tesseract model, and reconstructs table rows from OCR coordinates. OCR page numbers, engine version, language, transformations, and recognized text are preserved in lineage and content-addressed snapshots. Facts still pass through the normal independent source comparison and fail closed on conflicts. Because OCR is CPU-intensive, enable it only for workflows that need image-only statement coverage.

cacheDirectory is optional. When present, the adapter persists only the OCR page replacements in a content-addressed cache keyed by PDF bytes, OCR scale, selected pages, cache schema, and engine/model identity. Corrupt or stale cache entries are ignored and regenerated. Custom recognizers must also set a stable cacheIdentity to enable persistent caching; the bundled Tesseract recognizer sets this automatically.

Industry audits can opt in with --cninfo-ocr; use a dedicated data directory when comparing OCR and text-only runs:

pnpm audit:industry -- \
  --cninfo-ocr \
  --data-dir /tmp/verified-financial-ocr-audit \
  --output work/industry-coverage-audit-ocr.json \
  --industry "航空机场=/absolute/path/to/aviation-primary.json"

OCR audits default to a ten-minute Provider budget instead of the normal 30-second budget and persist reusable OCR results under <data-dir>/ocr-cache. Override the budget explicitly with --provider-timeout-ms when running on slower or faster hardware. The audit gate evaluates baseline revenue and profit using independently corroborated amount coverage, not merely usable single-source coverage. Reports include separate usable and independently corroborated company counts.

Audit requests default to --max-age-seconds 0 for a fresh upstream run. Set --max-age-seconds to reuse matching successful FactSets when recalculating the report or retrying only the companies that previously failed. A later --baseline-financial-as-of combined with an earlier --baseline-market-as-of produces a post-disclosure reconstruction while keeping historical prices and share counts at the original valuation date.

Dexter and other LLM clients convert the complete FactSet through the shared fail-closed adapter:

import {
  buildClientFinancialContext,
} from "@verified-financial/client-context";

const context = buildClientFinancialContext(factSet, {
  minimumStatus: "verified",
});

Facts below the declared threshold are moved to blockedFacts without their numeric value. Consumers must honor gate.passed before publishing or making an investment claim. See the Client Financial Context 1.1.0 contract.

Request facts:

pnpm --silent ah-context facts 600519.SH \
  --concept income.revenue \
  --period 2025FY \
  --as-of 2026-07-27 \
  --format json

--as-of is the effective observation or valuation time. By default it is also the information cutoff, so the request is strict point-in-time. For a post-disclosure reconstruction, keep --as-of fixed and set an explicit later --knowledge-as-of:

pnpm --silent ah-context facts 600519.SH \
  --concept income.revenue \
  --period 2024Q2TTM \
  --as-of 2024-08-30 \
  --knowledge-as-of 2024-09-30 \
  --format json

The resulting temporalContext.mode is post-disclosure. Each returned Fact records its latest evidence time, whether all evidence was known at the effective date, and the Observation IDs published afterward. Omitting --knowledge-as-of preserves the original fail-closed behavior and emits point-in-time.

Request the last unadjusted daily close available on a historical date:

pnpm --silent ah-context facts 600519.SH \
  --concept market.price.close \
  --as-of 2025-07-27 \
  --format json

Historical daily closes use the latest trading day at or before asOf. The Fact period remains the requested valuation date, while availability.effectiveDate records the actual trading date (for example, the preceding Friday for a weekend or the last close before a suspension). Mainland daily closes are conservatively available from 15:30 +08:00 and Hong Kong closes from 16:30 +08:00. Same-calendar-day requests continue to use the current quote path. Historical market cap is unavailable unless the official CNINFO share ledger contains a share count effective by asOf and disclosed by knowledgeAsOf (which defaults to asOf). The Gateway will not multiply a historical close by the latest share count.

Request the implemented cash dividend per share assigned to a fiscal year:

pnpm --silent ah-context facts 600519.SH \
  --concept distribution.dividendPerShare \
  --period 2024FY \
  --as-of 2025-06-21 \
  --format json

For A shares, multiple implemented distributions in the same fiscal year are summed and source amounts reported per 10 shares retain scale 0.1. Hong Kong cash distributions preserve the currency stated in the source. Proposals without an amount and non-cash special distributions are excluded. CNINFO official implementation announcements and HKEX official cash-dividend forms cross-check the aggregator result; HKEX final dividends remain unavailable until shareholder approval when that date is stated.

Period syntax includes 2025FY, 2025Q3, 2025Q3YTD, 2025TTM, and the explicit-quarter TTM form 2026Q2TTM. Automatic TTM derivation requires the explicit-quarter form.

Use VERIFIED_FINANCIAL_DATA_DIR to select the local snapshot and SQLite directory. JSON results are written only to stdout; diagnostics are written only to stderr. Without --offline, facts may call the registered public endpoints and stores every upstream response as an immutable raw snapshot.

The facts command accepts --offline, --max-age-seconds N, and --require-status verified|warning|failed. Its exit codes are:

• 0: completed and met the required status;
• 2: produced a FactSet below the required status;
• 3: invalid input or configuration;
• 4: storage or unrecoverable system failure.

Default cache ages are 60 seconds for market/valuation requests and 24 hours for financial/dividend requests. --offline never invokes Providers: it replays a matching frozen FactSet when available and marks the result with OFFLINE_SNAPSHOT and, when expired, STALE_CACHE. On live upstream failure, stale fallback is used only when the current request cannot otherwise satisfy its required facts.

The Gateway expands derivation dependencies internally without changing the request or cache identity. It currently derives:

• free cash flow from operating cash flow minus capex;
• TTM additive income/cash-flow facts when the fiscal quarter is explicit;
• annual ROE from profit and average opening/closing equity;
• market cap from same-period close price and shares outstanding.

Every derived fact records its formula and input Fact/Observation lineage. All input Facts are persisted with the FactSet, and explain recursively expands the derivation tree down to source Observations and raw snapshots. Direct usable facts always take precedence. Missing or unusable inputs fail closed with both the summary DERIVATION_UNAVAILABLE:<concept> and an exact input reason such as DERIVATION_INPUT_MISSING:income.revenue:2023-06-30:ytd. Provider causes add the provider, concept, period, and cause, for example PROVIDER_INPUT_MISSING:cninfo-direct:income.revenue:2024-06-30:ytd:REPORT_NOT_AVAILABLE_AS_OF. An observation published after the request cutoff is distinguished from an empty response with DERIVATION_INPUT_UNAVAILABLE_AS_OF and PROVIDER_INPUT_UNAVAILABLE_AS_OF. Expected filing gaps use REPORT_NOT_PUBLISHED_AS_OF instead of PROVIDER_FAILURE. CNINFO mapping failures also retain a typed detail such as STATEMENT_NOT_FOUND, STATEMENT_IMAGE_ONLY, LABEL_NOT_FOUND, or COLUMN_LAYOUT_AMBIGUOUS. Image-only primary statements do not fall back to annual-report summaries or notes. TTM ROE, EPS-based P/E, and other unsupported non-additive ratios remain fail-closed.

Financial observations distinguish the original filing, a later filing's comparative column, and an explicitly revised filing through reportingVersion. CNINFO also fetches the next comparable filing when it was available by knowledgeAsOf; Eastmoney historical rows are classified from their REPORT_DATE and later NOTICE_DATE. Verification compares only the same reporting version, while the Gateway selects the newest known version for each TTM input and retains older versions in lineage. A failed newest version does not fall back to an older value. Any discrepancy above 5% between independent sources still fails closed, including when one source is official.

The default Gateway also uses THS as an A-share structured financial cross-check and Baidu Stock Connect V2 as an H-share structured financial cross-check. These current-view endpoints do not expose a trustworthy filing date or revision sequence, so their observations are available only from the actual fetch time and do not assert a reportingVersion. The Gateway aligns a current-view value to a compatible known disclosure version; if no close match exists, it is checked against the newest known version and the normal discrepancy rules still fail closed. This prevents today's comparative value from leaking into a strict historical request.

Packages

• @verified-financial/schema
• @verified-financial/core
• @verified-financial/provider-contract
• @verified-financial/provider-cninfo
• @verified-financial/provider-hkex
• @verified-financial/provider-eastmoney
• @verified-financial/provider-tencent
• @verified-financial/provider-baidu
• @verified-financial/provider-ths
• @verified-financial/storage
• @verified-financial/sdk
• @verified-financial/ah-gateway-cli

See the approved architecture and the implementation plans for storage/Gateway, routing/cache, derivation orchestration, CNINFO official filings, HKEX official filings, historical daily close, annual dividend per share, and public A/H Providers.