@dshtrading/connector-polymarket 0.6.2 → 0.7.0

package/lib/gamma.js

@@ -1,4 +1,4 @@
-import { PolymarketError, bodySnippet } from "./errors.js";
+import { PolymarketError, bodySnippet, networkError } from "./errors.js";
 //#region src/gamma.ts
 /**
 * Polymarket gamma 公开只读 API 的传输层。
@@ -27,6 +27,20 @@ const DEFAULT_TIMEOUT_MS = 1e4;
 * 且仍落在 200 的集合内。
 */
 const USER_AGENT = "dsh-trading-connector-polymarket/0.6.1";
+/**
+* 本次响应是否由 Cloudflare **共享缓存直接命中**（`cf-cache-status: HIT`）。
+*
+* 用途：工具面 `stale` 字段的**唯一判据**。`/events` 回
+* `cache-control: public, max-age=300`，HIT 意味着拿到的是副本（实测 `age: 224`
+* 的副本，见 spikes/impl-polymarket/agent-tools-ACCEPTANCE.md），最多可能比源站旧
+* 5 分钟；MISS/DYNAMIC = 源站当次现算。
+*
+* 头缺失（本地夹具、非 Cloudflare 部署）返回 false——false 的语义是「没有观察到
+* 共享缓存命中」，不是「已证明为源站实时值」，两者不可混为一谈（不猜）。
+*/
+function isCdnCached(response) {
+	return response.headers.get("cf-cache-status")?.trim().toUpperCase() === "HIT";
+}
 var GammaClient = class {
 	timeoutMs;
 	fetchImpl;
@@ -65,7 +79,7 @@ var GammaClient = class {
 				signal: controller.signal
 			});
 		} catch (cause) {
-			throw networkError(url.pathname, cause);
+			throw networkError(`polymarket gamma ${url.pathname}`, cause);
 		} finally {
 			clearTimeout(timer);
 		}
@@ -80,14 +94,10 @@ var GammaClient = class {
 		return {
 			status: response.status,
 			body,
-			text
+			text,
+			headers: response.headers
 		};
 	}
 };
-function networkError(path, cause) {
-	const reason = cause instanceof Error ? cause.message : String(cause);
-	const timedOut = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
-	return new PolymarketError("TRADING_NETWORK", `polymarket gamma ${path}: ${timedOut ? "request timed out" : "network failure"} — ${reason}`, cause);
-}
 //#endregion
-export { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, USER_AGENT };
+export { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, USER_AGENT, isCdnCached };

package/lib/index.d.ts

@@ -1,7 +1,10 @@
+import { CLOB_BASE_URL, ClobClient, ClobPriceHistory, ClobPriceHistoryRequest, ClobTransportOptions, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, PRICE_HISTORY_MAX_WINDOW_MS, assertPriceHistoryRange } from "./clob.js";
 import { DiscoveryResult, DiscoveryTrace, FOMC_SERIES_ID, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, canonicalBucket, discoverFomcMeetings, parseMeeting } from "./discovery.js";
-import { PolymarketError, bodySnippet } from "./errors.js";
-import { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, USER_AGENT } from "./gamma.js";
+import { PolymarketError, bodySnippet, networkError } from "./errors.js";
+import { EventBucketQuote, EventDetail, EventMarketQuote, EventSearchPage, EventSummary, matchesKeyword, parseEventDetail, parseEventSummary, searchEventsInPage } from "./events.js";
+import { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, USER_AGENT, isCdnCached } from "./gamma.js";
 import { SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotEntry, SnapshotStore, SnapshotStoreOptions, SnapshotTable, applySnapshot, defaultSnapshotPath, emptySnapshotTable, parseSnapshotTable } from "./snapshot.js";
-import { PREDICTION_EVENTS_LIMIT, PolymarketService, PolymarketServiceOptions, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
+import { Freshness, MEETING_LOOKUP_TTL_MS, POLYMARKET_SOURCE, PREDICTION_EVENTS_LIMIT, PREDICTION_SEARCH_DEFAULT_LIMIT, PREDICTION_SEARCH_MAX_LIMIT, PolymarketService, PolymarketServiceOptions, PredictionEventDetailResult, PredictionEventSearchResult, PredictionFomcResult, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
+import { createPolymarketTools } from "./tools.js";
 import { ApplyOverrides, Config, apply, createPolymarketService, inject, name } from "./plugin.js";
-export { type ApplyOverrides, Config, DEFAULT_TIMEOUT_MS, DiscoveryResult, DiscoveryTrace, FOMC_SERIES_ID, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PREDICTION_EVENTS_LIMIT, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, PolymarketError, PolymarketService, PolymarketServiceOptions, SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotEntry, SnapshotStore, SnapshotStoreOptions, SnapshotTable, TRADING_PREDICTION_FEED_KEY, USER_AGENT, apply, applySnapshot, bodySnippet, canonicalBucket, createPolymarketPredictionFeed, createPolymarketService, defaultSnapshotPath, discoverFomcMeetings, emptySnapshotTable, inject, name, parseMeeting, parseSnapshotTable };
+export { type ApplyOverrides, CLOB_BASE_URL, ClobClient, ClobPriceHistory, ClobPriceHistoryRequest, ClobTransportOptions, Config, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, DEFAULT_TIMEOUT_MS, DiscoveryResult, DiscoveryTrace, EventBucketQuote, EventDetail, EventMarketQuote, EventSearchPage, EventSummary, FOMC_SERIES_ID, Freshness, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, MAX_BUCKETS, MEETING_LOOKUP_TTL_MS, MIN_BUCKETS, NOISE_SLUGS, POLYMARKET_SOURCE, PREDICTION_EVENTS_LIMIT, PREDICTION_SEARCH_DEFAULT_LIMIT, PREDICTION_SEARCH_MAX_LIMIT, PRICE_HISTORY_MAX_WINDOW_MS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, PolymarketError, PolymarketService, PolymarketServiceOptions, PredictionEventDetailResult, PredictionEventSearchResult, PredictionFomcResult, SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotEntry, SnapshotStore, SnapshotStoreOptions, SnapshotTable, TRADING_PREDICTION_FEED_KEY, USER_AGENT, apply, applySnapshot, assertPriceHistoryRange, bodySnippet, canonicalBucket, createPolymarketPredictionFeed, createPolymarketService, createPolymarketTools, defaultSnapshotPath, discoverFomcMeetings, emptySnapshotTable, inject, isCdnCached, matchesKeyword, name, networkError, parseEventDetail, parseEventSummary, parseMeeting, parseSnapshotTable, searchEventsInPage };

package/lib/index.js

@@ -1,7 +1,10 @@
+import { PolymarketError, bodySnippet, networkError } from "./errors.js";
+import { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, USER_AGENT, isCdnCached } from "./gamma.js";
+import { CLOB_BASE_URL, ClobClient, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, PRICE_HISTORY_MAX_WINDOW_MS, assertPriceHistoryRange } from "./clob.js";
 import { FOMC_SERIES_ID, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, canonicalBucket, discoverFomcMeetings, parseMeeting } from "./discovery.js";
-import { PolymarketError, bodySnippet } from "./errors.js";
-import { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, USER_AGENT } from "./gamma.js";
-import { PREDICTION_EVENTS_LIMIT, PolymarketService, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
+import { matchesKeyword, parseEventDetail, parseEventSummary, searchEventsInPage } from "./events.js";
+import { MEETING_LOOKUP_TTL_MS, POLYMARKET_SOURCE, PREDICTION_EVENTS_LIMIT, PREDICTION_SEARCH_DEFAULT_LIMIT, PREDICTION_SEARCH_MAX_LIMIT, PolymarketService, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
 import { SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotStore, applySnapshot, defaultSnapshotPath, emptySnapshotTable, parseSnapshotTable } from "./snapshot.js";
+import { createPolymarketTools } from "./tools.js";
 import { Config, apply, createPolymarketService, inject, name } from "./plugin.js";
-export { Config, DEFAULT_TIMEOUT_MS, FOMC_SERIES_ID, GAMMA_BASE_URL, GammaClient, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PREDICTION_EVENTS_LIMIT, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, PolymarketError, PolymarketService, SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotStore, TRADING_PREDICTION_FEED_KEY, USER_AGENT, apply, applySnapshot, bodySnippet, canonicalBucket, createPolymarketPredictionFeed, createPolymarketService, defaultSnapshotPath, discoverFomcMeetings, emptySnapshotTable, inject, name, parseMeeting, parseSnapshotTable };
+export { CLOB_BASE_URL, ClobClient, Config, DEFAULT_PRICE_HISTORY_FIDELITY_MINUTES, DEFAULT_TIMEOUT_MS, FOMC_SERIES_ID, GAMMA_BASE_URL, GammaClient, MAX_BUCKETS, MEETING_LOOKUP_TTL_MS, MIN_BUCKETS, NOISE_SLUGS, POLYMARKET_SOURCE, PREDICTION_EVENTS_LIMIT, PREDICTION_SEARCH_DEFAULT_LIMIT, PREDICTION_SEARCH_MAX_LIMIT, PRICE_HISTORY_MAX_WINDOW_MS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, PolymarketError, PolymarketService, SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotStore, TRADING_PREDICTION_FEED_KEY, USER_AGENT, apply, applySnapshot, assertPriceHistoryRange, bodySnippet, canonicalBucket, createPolymarketPredictionFeed, createPolymarketService, createPolymarketTools, defaultSnapshotPath, discoverFomcMeetings, emptySnapshotTable, inject, isCdnCached, matchesKeyword, name, networkError, parseEventDetail, parseEventSummary, parseMeeting, parseSnapshotTable, searchEventsInPage };

package/lib/json.js

@@ -0,0 +1,63 @@
+//#region src/json.ts
+/**
+* 上游 JSON 体的取值原语（discovery.ts 与 events.ts 共用，只此一份）。
+*
+* 为什么单独成模块：FOMC 发现面与事件检索面从同一份 gamma 半结构化体里取值，
+* 「字符串数字算不算数字」「空串算不算文本」「字符串化数组怎么拆」这三个口径一旦
+* 分叉，同一份上游数据会在两个工具面上给出不同答案。
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 上游把数字既发成 number 也发成 string（`"0.835"`），两种都读；其余一律 undefined。 */
+function num(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+}
+/** 非空字符串；`null` / 空串 / 纯空白一律 undefined（不当成空文本）。 */
+function text(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/**
+* 字符串化的 JSON 数组（gamma 的 `outcomes` / `outcomePrices`，如
+* `"[\"Yes\", \"No\"]"`）。解析失败或不是数组一律 undefined——不猜、不补空数组。
+*/
+function parseStringArray(value) {
+	if (typeof value !== "string") return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		return;
+	}
+	return Array.isArray(parsed) ? parsed : void 0;
+}
+/** 字符串化数组 → 数字数组（解析不出数字的项丢弃；全丢或非数组 = undefined）。 */
+function parseNumberArray(value) {
+	const raw = parseStringArray(value);
+	if (raw === void 0) return void 0;
+	const parsed = [];
+	for (const item of raw) {
+		const value = num(item);
+		if (value !== void 0) parsed.push(value);
+	}
+	return parsed.length > 0 ? parsed : void 0;
+}
+/** 字符串化数组 → 非空字符串数组（同 {@link parseNumberArray} 的丢弃口径）。 */
+function parseTextArray(value) {
+	const raw = parseStringArray(value);
+	if (raw === void 0) return void 0;
+	const parsed = [];
+	for (const item of raw) {
+		const value = text(item);
+		if (value !== void 0) parsed.push(value);
+	}
+	return parsed.length > 0 ? parsed : void 0;
+}
+//#endregion
+export { isRecord, num, parseNumberArray, parseStringArray, parseTextArray, text };

package/lib/plugin.d.ts

@@ -4,7 +4,7 @@ import { Context } from "@deepseek-ai/cordis";
 //#region src/plugin.d.ts
 /** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
 declare const name = "dsh-trading-connector-polymarket";
-/** 本插件不注册工具、不依赖任何宿主服务（纯 provide）。 */
+/** 注册 agent 工具面需要宿主 tools 服务（与 connector-jin10 同款；缺 inject 会让整棵树加载失败）。 */
 declare const inject: string[];
 interface Config {
   enabled: boolean;
@@ -19,9 +19,11 @@ declare const Config: Schema<Config>;
 interface ApplyOverrides {
   /** 注入的 fetch（单测用契约化替身）。 */
   readonly fetchImpl?: typeof globalThis.fetch;
-  /** 基址覆盖（单测指向本地夹具服务）。 */
+  /** gamma 基址覆盖（单测指向本地夹具服务）。 */
   readonly baseUrl?: string;
-  /** 时钟注入（单测固定 fetchedAt）。 */
+  /** CLOB 基址覆盖（同上；历史面与会议面可指向同一个夹具服务）。 */
+  readonly clobBaseUrl?: string;
+  /** 时钟注入（单测固定 fetchedAt / 推进缓存 TTL）。 */
   readonly now?: (() => number) | undefined;
 }
 /** 组装取数服务（测试可直接注入 fetchImpl，无需 mock 全局）。 */
@@ -29,6 +31,10 @@ declare function createPolymarketService(config: Config, overrides?: ApplyOverri
 /**
  * 插件钩子（宿主签名 `apply(ctx, config)`）。
  *
+ * **一个 service 实例供两处消费**：桥/面板面（`tradingPredictionFeed`）与 agent 工具面
+ * 共用下面这个 `service`——两份取数逻辑漂移是这类数据面最容易犯的错（同一场会议在面板
+ * 与工具里给出不同概率）。工具用同名先到先得注册，不覆盖别人的工具。
+ *
  * 不接收注入参数：测试用的 fetch/时钟替身走 {@link createPolymarketService}，不往
  * 生产钩子的签名里加测试专用面（connector-jin10 同款纪律）。
  */

package/lib/plugin.js

@@ -1,12 +1,14 @@
 import { DEFAULT_TIMEOUT_MS, GammaClient } from "./gamma.js";
+import { ClobClient } from "./clob.js";
 import { PolymarketService, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
 import { SnapshotStore } from "./snapshot.js";
+import { createPolymarketTools } from "./tools.js";
 import Schema from "@deepseek-ai/schemastery";
 //#region src/plugin.ts
 /** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
 const name = "dsh-trading-connector-polymarket";
-/** 本插件不注册工具、不依赖任何宿主服务（纯 provide）。 */
-const inject = [];
+/** 注册 agent 工具面需要宿主 tools 服务（与 connector-jin10 同款；缺 inject 会让整棵树加载失败）。 */
+const inject = ["tools"];
 const Config = Schema.object({
 	enabled: Schema.boolean().default(true).description("是否启用 Polymarket 预测市场数据面"),
 	timeoutMs: Schema.number().default(DEFAULT_TIMEOUT_MS).description("单次 gamma-api 请求超时（ms）"),
@@ -20,9 +22,15 @@ function createPolymarketService(config, overrides = {}) {
 		...overrides.fetchImpl !== void 0 ? { fetchImpl: overrides.fetchImpl } : {},
 		...overrides.baseUrl !== void 0 ? { baseUrl: overrides.baseUrl } : {}
 	});
+	const clob = new ClobClient({
+		timeoutMs: config.timeoutMs,
+		...overrides.fetchImpl !== void 0 ? { fetchImpl: overrides.fetchImpl } : {},
+		...overrides.clobBaseUrl !== void 0 ? { baseUrl: overrides.clobBaseUrl } : {}
+	});
 	const snapshots = config.snapshots ? new SnapshotStore(config.snapshotPath === "" ? {} : { filePath: config.snapshotPath }) : void 0;
 	return new PolymarketService({
 		gamma,
+		clob,
 		...snapshots !== void 0 ? { snapshots } : {},
 		...overrides.now !== void 0 ? { now: overrides.now } : {}
 	});
@@ -30,12 +38,19 @@ function createPolymarketService(config, overrides = {}) {
 /**
 * 插件钩子（宿主签名 `apply(ctx, config)`）。
 *
+* **一个 service 实例供两处消费**：桥/面板面（`tradingPredictionFeed`）与 agent 工具面
+* 共用下面这个 `service`——两份取数逻辑漂移是这类数据面最容易犯的错（同一场会议在面板
+* 与工具里给出不同概率）。工具用同名先到先得注册，不覆盖别人的工具。
+*
 * 不接收注入参数：测试用的 fetch/时钟替身走 {@link createPolymarketService}，不往
 * 生产钩子的签名里加测试专用面（connector-jin10 同款纪律）。
 */
 function apply(ctx, config) {
 	if (!config.enabled) return;
-	ctx.reflect.provide(TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed(createPolymarketService(config)));
+	const service = createPolymarketService(config);
+	ctx.reflect.provide(TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed(service));
+	const tools = ctx.tools;
+	for (const tool of createPolymarketTools(service)) if (tools.get(tool.name) === void 0) tools.register(tool);
 }
 //#endregion
 export { Config, apply, createPolymarketService, inject, name };

package/lib/service.d.ts

@@ -1,12 +1,64 @@
+import { ClobClient } from "./clob.js";
+import { EventDetail, EventSummary } from "./events.js";
 import { GammaClient } from "./gamma.js";
 import { SnapshotStore } from "./snapshot.js";
-import { PredictionFeed, PredictionFeedService } from "@dshtrading/api";
+import { PredictionFeed, PredictionFeedService, PredictionMeeting, PredictionPriceHistory, PredictionPriceHistoryRequest } from "@dshtrading/api";
 //#region src/service.d.ts
 declare const TRADING_PREDICTION_FEED_KEY = "tradingPredictionFeed";
-/** 单次取数的候选上限（上游 limit 上限 100，证据 Q1.4）。 */
+/** 单次取数的候选上限（上游 limit 上限 100，证据 Q1.4；`limit=500` 与 `limit=100` 同结果）。 */
 declare const PREDICTION_EVENTS_LIMIT = 100;
+/**
+ * 会议发现结果的缓存窗口（ms）——**短 TTL，只挡同一刷新周期内的重复发现**。
+ *
+ * 历史面必须先按 `meetingId` 找到会议才能拿到各档 token；面板每换一个事件、每重绘
+ * 一次都会要历史，不缓存就是「面板每个事件打一次 gamma」（`/events` 还有
+ * `max-age=300` 的 CDN 缓存，重复打只是白等一份同一副本）。60 秒的依据：会议集合是
+ * 以天为单位变化的（新会议按周出现、结算按会议日翻转），60s 足够短到不掩盖真实变化，
+ * 又足够长到覆盖一次面板交互的全部事件请求。
+ *
+ * **失败不入缓存**：网络抖动不会被记成「没有这场会议」，下一次重试照常打上游。
+ */
+declare const MEETING_LOOKUP_TTL_MS = 60000;
+/** 关键词检索的返回条数默认/上限（取数页恒为 {@link PREDICTION_EVENTS_LIMIT}）。 */
+declare const PREDICTION_SEARCH_DEFAULT_LIMIT = 20;
+declare const PREDICTION_SEARCH_MAX_LIMIT = 50;
+/** 工具面 `source` 字段的唯一取值：数据来自哪个读取面（公开只读，无密钥）。 */
+declare const POLYMARKET_SOURCE = "gamma-api.polymarket.com /events (public read-only upstream)";
+/**
+ * 工具面出参的时间/出处/新鲜度三件套。
+ *
+ * `stale` 的判据只有一个（见 {@link isCdnCached}）：本次响应是否由共享 CDN 直接命中。
+ * 它**不是**「数据旧了」的推测，而是「拿到的是副本」的实证。
+ */
+interface Freshness {
+  /** 本进程的取数时刻（ISO 8601 UTC；上游无响应级时间戳，数据时间戳只能由取数侧记录）。 */
+  readonly observedAt: string;
+  readonly source: string;
+  readonly stale: boolean;
+}
+/** FOMC 工具面结果（可按 meetingId 收窄）。 */
+interface PredictionFomcResult extends Freshness {
+  readonly meetings: readonly PredictionMeeting[];
+}
+/** 关键词检索结果：`filtering` 恒为本地过滤标记（上游无检索参数，见 events.ts 头注）。 */
+interface PredictionEventSearchResult extends Freshness {
+  readonly filtering: 'local-page-filter';
+  /** 本次实际请求的取数页大小（恒为 {@link PREDICTION_EVENTS_LIMIT}）。 */
+  readonly pageLimit: number;
+  /** 本次扫描的上游事件数。 */
+  readonly scanned: number;
+  /** 关键词命中数（截断到返回条数**之前**）。 */
+  readonly matched: number;
+  readonly events: readonly EventSummary[];
+}
+/** 单事件详情结果。 */
+interface PredictionEventDetailResult extends Freshness {
+  readonly event: EventDetail;
+}
 interface PolymarketServiceOptions {
   readonly gamma: GammaClient;
+  /** CLOB 历史传输层（`/prices-history`）。 */
+  readonly clob: ClobClient;
   /** 快照存储；缺省 = 不做 Δ 标注（服务仍可用）。 */
   readonly snapshots?: SnapshotStore | undefined;
   /** 时钟注入（测试固定 fetchedAt 用；缺省 Date.now）。 */
@@ -21,19 +73,85 @@ interface PolymarketServiceOptions {
  */
 declare class PolymarketService {
   private readonly gamma;
+  private readonly clob;
   private readonly snapshots;
   private readonly now;
+  private meetingLookup;
   constructor(options: PolymarketServiceOptions);
   /**
-   * FOMC 决议路径全量会议（含已结算；按 endDate 升序）。
+   * `@dshtrading/api` 形状的取数面（桥/面板消费）。只是把 {@link fomcMeetings} 的结果
+   * 投影成 `PredictionFeed`——`fetchedAt` 与工具面的 `observedAt` 是同一个取数时刻，
+   * 两个字段名各归各自的契约，不是两次取数。
+   */
+  listFomcMeetings(options?: {
+    cacheBust?: boolean | undefined;
+  }): Promise<PredictionFeed>;
+  /**
+   * FOMC 决议路径全量会议（含已结算；按 endDate 升序）——**取数逻辑的唯一实现**。
    *
    * **失败必须响亮**：传输失败、HTTP 403（Cloudflare 1010 的 text/plain 体）、
    * 非 JSON 体、非数组体一律抛结构化错误——绝不返回 `{meetings: []}`。空数组
    * 只代表「上游确实返回了空集合」这一种真实语义。
+   *
+   * `meetingId` 命中 event id 或 slug（精确匹配）；给了但一场都没匹配到时抛
+   * TRADING_SYMBOL_NOT_FOUND——「上游说查不到」与「上游故障」是两件事，消费方不该把
+   * 前者当基础设施抖动去重试。
    */
-  listFomcMeetings(options?: {
+  fomcMeetings(options?: {
     cacheBust?: boolean | undefined;
-  }): Promise<PredictionFeed>;
+    meetingId?: string | undefined;
+  }): Promise<PredictionFomcResult>;
+  /**
+   * 关键词检索（中文或英文，大小写不敏感子串，命中事件标题或 slug——**不搜档位标签**，
+   * 理由见 events.ts 的 `matchesKeyword`）。
+   *
+   * 上游 `/events` **没有关键词参数**（实测 `q=`/`title=` 与无参数逐条同结果），所以
+   * 这里是单次拉「开盘中、24h 成交额降序」的一页再本地过滤，输出带
+   * `filtering: 'local-page-filter'` 与 `scanned`，让消费方一眼看出这是「一页 ∩ 关键词」，
+   * 不是上游检索。
+   *
+   * 空关键词**先抛错、零请求**：空串会匹配一切，静默回「最热 N 条」冒充检索命中就是编造。
+   */
+  searchEvents(options: {
+    keyword: string;
+    limit?: number | undefined;
+  }): Promise<PredictionEventSearchResult>;
+  /**
+   * 单事件详情（eventId 接受 event id 或 slug，精确匹配，**单次请求**）。
+   *
+   * 上游 200 空集 = 没有这个事件 → TRADING_SYMBOL_NOT_FOUND；传输/准入/契约失败照旧由
+   * 传输层结构化抛出，两者不互相冒充。
+   */
+  eventDetail(options: {
+    eventId: string;
+  }): Promise<PredictionEventDetailResult>;
+  /**
+   * 单场会议在请求窗口内的逐档历史读数（面板「事件对照」的回填来源）。
+   *
+   * 三段语义（每一段都对应一条验收要求，改这里前先读它们）：
+   *
+   * 1. **空 ≠ 失败**。上游 token 不存在时回 `200 {"history":[]}`（Q5.2），与本窗口确实
+   *    没有读数**无法在响应上区分**。所以空 history 只产生 `points: []`、不抛错——
+   *    但也只是「这一档在这个窗口没有可用读数」，不等于「概率为 0」「没有变动」：
+   *    面板照实留白，不许画一条 0 的线。
+   * 2. **任一档失败必须响亮抛出**（`Promise.all` 全否）。少一档就是**把失败画成没有
+   *    变动**——用户看到的是一条平的线，而真实情况是「这一档我们没取到」。宁可整块
+   *    报错让面板显示失败，也不给一份看起来完整、实则缺档的图。
+   * 3. **拿不到 token 的档位不扇出**：`clobTokenId` 缺省 = 上游没给定位键（或解析失败），
+   *    没有 token 就没有任何可请求的对象，**不猜**、也不给这一档造一条空序列；它就
+   *    不出现在 `series` 里（调用方按 bucketKey 找不到 = 这一档没有历史可对照）。
+   *
+   * 请求参数在**打 gamma 之前**校验（{@link assertPriceHistoryRange}：`fromMs < toMs`、
+   * 窗口 ≤ 336h、fidelity > 0）：桥侧已有同值闸门，这里是纵深防御——让非法请求
+   * 一次上游请求都不产生，而不是拿一个必然失败的窗口去打两次网络。
+   * `fidelityMinutes` 缺省 5 分钟（面板口径，依据见 clob.ts 的同名常量）。
+   */
+  listPriceHistory(request: PredictionPriceHistoryRequest): Promise<PredictionPriceHistory>;
+  /** 一次 gamma `/events` + 发现规则（不做 Δ 标注：历史面不需要快照）。 */
+  private fetchMeetings;
+  /** 历史面的会议定位：短 TTL 缓存（见 {@link MEETING_LOOKUP_TTL_MS}；失败不缓存）。 */
+  private meetingsForLookup;
+  private withFreshness;
   /**
    * Δ 标注：**快照失败不阻断取数**。
    *
@@ -49,4 +167,4 @@ declare class PolymarketService {
 /** host 平面服务面：桥与工具面共用的最小接口（@dshtrading/api 的 PredictionFeedService）。 */
 declare function createPolymarketPredictionFeed(service: PolymarketService): PredictionFeedService;
 //#endregion
-export { PREDICTION_EVENTS_LIMIT, PolymarketService, PolymarketServiceOptions, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed };
+export { Freshness, MEETING_LOOKUP_TTL_MS, POLYMARKET_SOURCE, PREDICTION_EVENTS_LIMIT, PREDICTION_SEARCH_DEFAULT_LIMIT, PREDICTION_SEARCH_MAX_LIMIT, PolymarketService, PolymarketServiceOptions, PredictionEventDetailResult, PredictionEventSearchResult, PredictionFomcResult, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed };