@dshtrading/connector-polymarket 0.0.0-stage → 0.6.2

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @dshtrading/connector-polymarket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Polymarket 预测市场连接器（**只读**公开 API，无密钥）。v1 只覆盖 **FOMC 决议路径**：
+给出一场会议的各档位标签与隐含概率，供右侧栏预测市场面板使用。
+
+判据与口径的唯一来源是 [spikes/impl-polymarket/EVIDENCE.md](../../spikes/impl-polymarket/EVIDENCE.md)
+（P0 spike 裁决）。**不要另起一套猜法**——发现规则与概率口径都在那份证据里钉死了。
+
+## 结构
+
+- `src/gamma.ts` —— gamma HTTP 传输层。固定自有 UA（实测 200；`Python-urllib` 会触发
+  Cloudflare 1010 → 403 且响应体是 text/plain）、显式超时、三层失败语义
+  （传输 → `TRADING_NETWORK`；4xx/5xx → `TRADING_UPSTREAM_ERROR`；200 非 JSON → 契约破损）。
+- `src/discovery.ts` —— 发现规则 L0..L5（`series_id=35` → `series[].id` 校验 → 标题正则
+  → `negRisk` + 档位数 4..6 → 噪声排除 → 按 id 去重/`endDate` 升序）与档位归一化。
+  纯函数，可离线复核历史证据。
+- `src/snapshot.ts` —— 本地快照（存 trading home）。只回答「自上次观察变了多少」，
+  缺失时 `changeSincePrevious` **缺省而不是 0**。
+- `src/service.ts` —— 取数服务 + host 面服务对象（`tradingPredictionFeed`）。
+- `src/plugin.ts` —— 插件入口。
+
+## 只读边界（硬约束）
+
+只访问 `gamma-api.polymarket.com/events` 读取面。**不触达任何下单/交易端点**，
+不引入任何密钥。
+
+## 数据落盘
+
+快照写 trading home（经 `@dshtrading/dsh-home` 解析，
+缺省 `$DSH_HOME/polymarket/snapshots.json`），绝不写进包内或仓库数据。
+
+## 接线
+
+跨市场信息源（FOMC 路径影响全部市场会话），故按 connector-jin10 先例由
+`@dshtrading/base` bundle 认领：`packages/base/cordis.patch.yml` 的 insert 行 +
+`packages/base/package.json` 的 dependencies。

package/lib/discovery.d.ts

@@ -0,0 +1,56 @@
+import { PredictionMeeting } from "@dshtrading/api";
+//#region src/discovery.d.ts
+/** 判据来源系列：FOMC 决议（证据 Q1.2，39/39 命中、噪声 0）。 */
+declare const FOMC_SERIES_ID = "35";
+/**
+ * `tag_slug=fomc` 上的已知噪声（L1 已全部排除，本表是纵深防御并记录失效模式）。
+ * 来源：证据 Q1.1 的 6 条噪声 + probe-discovery.mjs 的全历史复核清单。
+ */
+declare const NOISE_SLUGS: readonly string[];
+/** 档位形状边界（证据 Q1.6：历史上有 4/5/6 三档形态，超出即非决议档位集合）。 */
+declare const MIN_BUCKETS = 4;
+declare const MAX_BUCKETS = 6;
+/**
+ * 各档概率之和的正常区间（证据 Q4.2：实测偏离 −0.0015 ~ +0.0155）。
+ * **不假设严格等于 1**——2026-12 的 `sum(bid)` 实测为 1.0040 > 1，硬约束会假红。
+ */
+declare const PROBABILITY_SUM_MIN = 0.98;
+declare const PROBABILITY_SUM_MAX = 1.03;
+/** 档位标签 → 稳定键与利率变动（证据 Q1.7：标签在大小写与 `+` 上会漂移）。 */
+declare function canonicalBucket(label: string): {
+  key: string;
+  changeBps: number | undefined;
+};
+/**
+ * 单场会议 → 契约形状（含健康标记）。
+ *
+ * 返回 undefined = 该事件形状不足以构成一次决议（L3 之外的残形），由调用方丢弃。
+ */
+declare function parseMeeting(event: Record<string, unknown>): PredictionMeeting | undefined;
+interface DiscoveryTrace {
+  /** 上游返回的候选事件数。 */
+  readonly candidates: number;
+  /** 各层后剩余条数（L1..L4）。 */
+  readonly layers: {
+    readonly series: number;
+    readonly title: number;
+    readonly shape: number;
+    readonly noise: number;
+  };
+  /** 各层丢弃的标题（诊断用，不参与业务）。 */
+  readonly dropped: readonly string[];
+}
+interface DiscoveryResult {
+  readonly meetings: readonly PredictionMeeting[];
+  readonly trace: DiscoveryTrace;
+}
+/**
+ * 应用 L1..L5。输入为**已解析的 JSON 体**（不是 HTTP 层），便于离线复核历史证据。
+ *
+ * 形状错误一律抛错而**不返回空数组**：上游把「参数/路径错」和「真的没有数据」
+ * 都表现成 200（`tag_slug` 不存在 → 200 `[]`，证据 Q5.2），这里只能在体形状上守住
+ * 边界——非数组体 = 契约破损，必须响亮。
+ */
+declare function discoverFomcMeetings(payload: unknown): DiscoveryResult;
+//#endregion
+export { DiscoveryResult, DiscoveryTrace, FOMC_SERIES_ID, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, canonicalBucket, discoverFomcMeetings, parseMeeting };

package/lib/discovery.js

@@ -0,0 +1,238 @@
+//#region src/discovery.ts
+/** 判据来源系列：FOMC 决议（证据 Q1.2，39/39 命中、噪声 0）。 */
+const FOMC_SERIES_ID = "35";
+/**
+* `tag_slug=fomc` 上的已知噪声（L1 已全部排除，本表是纵深防御并记录失效模式）。
+* 来源：证据 Q1.1 的 6 条噪声 + probe-discovery.mjs 的全历史复核清单。
+*/
+const NOISE_SLUGS = [
+	"how-many-fed-rate-hikes-in-2026",
+	"warsh-out-as-fed-chair-by",
+	"trump-tries-to-fire-warsh-in-2026",
+	"fed-decisions-",
+	"no-change-or-hike-25-bps-favored-on-october-27",
+	"fed-rate-hike-by",
+	"what-will-be-the-next-fed-rate-change",
+	"dissent-at-fed-meeting",
+	"powell-bingo",
+	"what-will-powell-say",
+	"what-will-kevin-warsh-say",
+	"powell-says-"
+];
+const MONTHS = [
+	"January",
+	"February",
+	"March",
+	"April",
+	"May",
+	"June",
+	"July",
+	"August",
+	"September",
+	"October",
+	"November",
+	"December"
+];
+/** 现代标题形态（2024-12 起）：`Fed decision in October?`。 */
+const TITLE_MODERN = new RegExp(`^Fed decision in (${MONTHS.join("|")})\\?$`, "i");
+/** 历史标题形态（2022-03 起）：`Fed Interest Rates: June 2024`。 */
+const TITLE_LEGACY = new RegExp(`^Fed Interest Rates:? (${MONTHS.join("|")}) \\d{4}$`, "i");
+/** 档位形状边界（证据 Q1.6：历史上有 4/5/6 三档形态，超出即非决议档位集合）。 */
+const MIN_BUCKETS = 4;
+const MAX_BUCKETS = 6;
+/**
+* 各档概率之和的正常区间（证据 Q4.2：实测偏离 −0.0015 ~ +0.0155）。
+* **不假设严格等于 1**——2026-12 的 `sum(bid)` 实测为 1.0040 > 1，硬约束会假红。
+*/
+const PROBABILITY_SUM_MIN = .98;
+const PROBABILITY_SUM_MAX = 1.03;
+/** 会议日程解析（上游 description 原文：`its meeting scheduled for October 27-28, 2026`）。 */
+const MEETING_WINDOW_RE = /meeting scheduled for ([A-Z][a-z]+ \d+(?:-\d+)?, \d{4})/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+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;
+	}
+}
+function text(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/** 档位标签 → 稳定键与利率变动（证据 Q1.7：标签在大小写与 `+` 上会漂移）。 */
+function canonicalBucket(label) {
+	const value = label.trim();
+	if (/^no change$/i.test(value)) return {
+		key: "no_change",
+		changeBps: 0
+	};
+	const match = /^(\d+)\+? bps (decrease|increase)$/i.exec(value);
+	if (match) {
+		const magnitude = Number(match[1]);
+		const up = /increase/i.test(match[2] ?? "");
+		return {
+			key: `${up ? "inc" : "dec"}_${match[1]}${value.includes("+") ? "plus" : ""}`,
+			changeBps: up ? magnitude : -magnitude
+		};
+	}
+	return {
+		key: `raw:${value}`,
+		changeBps: void 0
+	};
+}
+function titleMatches(title) {
+	return TITLE_MODERN.test(title) || TITLE_LEGACY.test(title);
+}
+function hasSeries(event) {
+	if (!Array.isArray(event.series)) return false;
+	return event.series.some((entry) => isRecord(entry) && String(entry.id) === "35");
+}
+/** `outcomePrices` 是**字符串化的 JSON 数组**（如 `"[\"0.0035\",\"0.9965\"]"`）。 */
+function parseOutcomePrices(value) {
+	if (typeof value !== "string") return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		return;
+	}
+	if (!Array.isArray(parsed) || parsed.length === 0) return void 0;
+	return num(parsed[0]);
+}
+function parseBucket(market) {
+	const label = text(market.groupItemTitle);
+	const probability = parseOutcomePrices(market.outcomePrices);
+	if (label === void 0 || probability === void 0) return void 0;
+	const { key, changeBps } = canonicalBucket(label);
+	const bestBid = num(market.bestBid);
+	const bestAsk = num(market.bestAsk);
+	const liquidity = num(market.liquidityNum);
+	const volume = num(market.volumeNum);
+	const volume24h = num(market.volume24hr);
+	const tickSize = num(market.orderPriceMinTickSize);
+	return {
+		key,
+		label,
+		...changeBps !== void 0 ? { changeBps } : {},
+		probability,
+		...bestBid !== void 0 ? { bestBid } : {},
+		...bestAsk !== void 0 ? { bestAsk } : {},
+		...bestBid !== void 0 && bestAsk !== void 0 ? { spread: Number((bestAsk - bestBid).toFixed(6)) } : {},
+		...liquidity !== void 0 ? { liquidity } : {},
+		...volume !== void 0 ? { volume } : {},
+		...volume24h !== void 0 ? { volume24h } : {},
+		...tickSize !== void 0 ? { tickSize } : {},
+		acceptingOrders: market.acceptingOrders === true,
+		closed: market.closed === true
+	};
+}
+/** 档位排序：按利率变动从低到高，未识别形态排末位（用 key 兜底保证确定性）。 */
+function compareBuckets(a, b) {
+	const left = a.changeBps;
+	const right = b.changeBps;
+	if (left === void 0 && right === void 0) return a.key.localeCompare(b.key);
+	if (left === void 0) return 1;
+	if (right === void 0) return -1;
+	return left - right;
+}
+/**
+* 单场会议 → 契约形状（含健康标记）。
+*
+* 返回 undefined = 该事件形状不足以构成一次决议（L3 之外的残形），由调用方丢弃。
+*/
+function parseMeeting(event) {
+	const id = text(String(event.id ?? ""));
+	const slug = text(event.slug);
+	const title = text(event.title);
+	const endDate = text(event.endDate);
+	if (id === void 0 || slug === void 0 || title === void 0 || endDate === void 0) return void 0;
+	if (!Array.isArray(event.markets)) return void 0;
+	const buckets = [];
+	for (const raw of event.markets) {
+		if (!isRecord(raw)) continue;
+		const bucket = parseBucket(raw);
+		if (bucket !== void 0) buckets.push(bucket);
+	}
+	if (buckets.length === 0) return void 0;
+	buckets.sort(compareBuckets);
+	const sum = Number(buckets.reduce((acc, bucket) => acc + bucket.probability, 0).toFixed(6));
+	const degraded = [];
+	if (sum < .98 || sum > 1.03) degraded.push("probability-sum-out-of-band");
+	if (buckets.some((bucket) => bucket.probability < 0 || bucket.probability > 1)) degraded.push("probability-out-of-range");
+	if (buckets.some((bucket) => !bucket.closed && (bucket.bestBid === void 0 || bucket.bestAsk === void 0))) degraded.push("bucket-quote-missing");
+	if (buckets.some((bucket) => bucket.key.startsWith("raw:"))) degraded.push("bucket-unrecognized-label");
+	const description = text(event.description);
+	const window = description === void 0 ? void 0 : MEETING_WINDOW_RE.exec(description);
+	return {
+		id,
+		slug,
+		title,
+		endDate,
+		...window?.[1] !== void 0 ? { meetingWindow: window[1] } : {},
+		closed: event.closed === true,
+		buckets,
+		probabilitySum: sum,
+		degraded
+	};
+}
+/**
+* 应用 L1..L5。输入为**已解析的 JSON 体**（不是 HTTP 层），便于离线复核历史证据。
+*
+* 形状错误一律抛错而**不返回空数组**：上游把「参数/路径错」和「真的没有数据」
+* 都表现成 200（`tag_slug` 不存在 → 200 `[]`，证据 Q5.2），这里只能在体形状上守住
+* 边界——非数组体 = 契约破损，必须响亮。
+*/
+function discoverFomcMeetings(payload) {
+	if (!Array.isArray(payload)) throw new TypeError("polymarket gamma /events: expected a JSON array of events");
+	const candidates = payload.filter(isRecord);
+	const dropped = [];
+	const bySeries = candidates.filter((event) => {
+		const ok = hasSeries(event);
+		if (!ok) dropped.push(`L1:${String(event.title ?? event.slug ?? "(untitled)")}`);
+		return ok;
+	});
+	const byTitle = bySeries.filter((event) => {
+		const ok = titleMatches(String(event.title ?? ""));
+		if (!ok) dropped.push(`L2:${String(event.title ?? "(untitled)")}`);
+		return ok;
+	});
+	const byShape = byTitle.filter((event) => {
+		const count = Array.isArray(event.markets) ? event.markets.length : 0;
+		const ok = event.negRisk === true && count >= 4 && count <= 6;
+		if (!ok) dropped.push(`L3:${String(event.title ?? "(untitled)")}`);
+		return ok;
+	});
+	const byNoise = byShape.filter((event) => {
+		const haystack = `${String(event.slug ?? "")} ${String(event.ticker ?? "")}`;
+		const hit = NOISE_SLUGS.find((noise) => haystack.includes(noise));
+		if (hit !== void 0) dropped.push(`L4:${String(event.title ?? "(untitled)")}<-${hit}`);
+		return hit === void 0;
+	});
+	const deduped = /* @__PURE__ */ new Map();
+	for (const event of byNoise) {
+		const meeting = parseMeeting(event);
+		if (meeting !== void 0) deduped.set(meeting.id, meeting);
+	}
+	return {
+		meetings: [...deduped.values()].sort((a, b) => {
+			const diff = Date.parse(a.endDate) - Date.parse(b.endDate);
+			return diff !== 0 ? diff : a.id.localeCompare(b.id);
+		}),
+		trace: {
+			candidates: candidates.length,
+			layers: {
+				series: bySeries.length,
+				title: byTitle.length,
+				shape: byShape.length,
+				noise: byNoise.length
+			},
+			dropped
+		}
+	};
+}
+//#endregion
+export { FOMC_SERIES_ID, MAX_BUCKETS, MIN_BUCKETS, NOISE_SLUGS, PROBABILITY_SUM_MAX, PROBABILITY_SUM_MIN, canonicalBucket, discoverFomcMeetings, parseMeeting };

package/lib/errors.d.ts

@@ -0,0 +1,22 @@
+import { TradingErrorCode } from "@dshtrading/api";
+//#region src/errors.d.ts
+/**
+ * 错误词汇对齐 @dshtrading/api（本包不做跨包 Error 类基座，与 connector-jin10 同款）。
+ *
+ * 本连接器**无凭证**（Polymarket gamma 为公开只读 API），故不存在
+ * TRADING_CREDENTIALS_MISSING 路径；失败一律落在网络层、准入层或上游契约层。
+ */
+declare class PolymarketError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+/**
+ * 上游响应体 → 可读片段（截断到 200 字符，绝不落盘整包）。
+ *
+ * 403 的响应体是 **text/plain 的 `error code: 1010`**（Cloudflare 准入拦截），
+ * 不是 JSON——解析层必须把它读成准入失败而不是「没有数据」，这是验收要求
+ * 「失败路径不产生空数据假象」的第一道闸门。
+ */
+declare function bodySnippet(text: string): string;
+//#endregion
+export { PolymarketError, bodySnippet };

package/lib/errors.js

@@ -0,0 +1,29 @@
+//#region src/errors.ts
+/**
+* 错误词汇对齐 @dshtrading/api（本包不做跨包 Error 类基座，与 connector-jin10 同款）。
+*
+* 本连接器**无凭证**（Polymarket gamma 为公开只读 API），故不存在
+* TRADING_CREDENTIALS_MISSING 路径；失败一律落在网络层、准入层或上游契约层。
+*/
+var PolymarketError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "PolymarketError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+/**
+* 上游响应体 → 可读片段（截断到 200 字符，绝不落盘整包）。
+*
+* 403 的响应体是 **text/plain 的 `error code: 1010`**（Cloudflare 准入拦截），
+* 不是 JSON——解析层必须把它读成准入失败而不是「没有数据」，这是验收要求
+* 「失败路径不产生空数据假象」的第一道闸门。
+*/
+function bodySnippet(text) {
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	return collapsed.length > 200 ? `${collapsed.slice(0, 200)}…` : collapsed;
+}
+//#endregion
+export { PolymarketError, bodySnippet };

package/lib/gamma.d.ts

@@ -0,0 +1,45 @@
+//#region src/gamma.d.ts
+declare const GAMMA_BASE_URL = "https://gamma-api.polymarket.com";
+declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * 自有 UA。实测矩阵（raw/connector-live-ua-matrix.txt，2026-10-11T02:00Z）：
+ * `Mozilla/5.0` 200、`Mozilla/5.0 (compatible; <name>)` 200、`<name>/<ver>` 200、
+ * `Python-urllib/3.11` 403。取自有标识而非伪造浏览器 UA——请求语义诚实，
+ * 且仍落在 200 的集合内。
+ */
+declare const USER_AGENT = "dsh-trading-connector-polymarket/0.6.1";
+interface GammaTransportOptions {
+  /** 单次请求超时（ms），缺省 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入的 fetch（测试用契约化替身；缺省 globalThis.fetch）。 */
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** 基址覆盖（测试指向本地夹具服务用）。 */
+  readonly baseUrl?: string;
+  /** UA 覆盖。 */
+  readonly userAgent?: string;
+}
+/** 一次 GET 的结果：状态码 + 解析后的 JSON 体 + 原始文本（证据用）。 */
+interface GammaResponse {
+  readonly status: number;
+  readonly body: unknown;
+  readonly text: string;
+}
+declare class GammaClient {
+  private readonly timeoutMs;
+  private readonly fetchImpl;
+  private readonly baseUrl;
+  private readonly userAgent;
+  constructor(options?: GammaTransportOptions);
+  /**
+   * GET `path?query`。
+   *
+   * 失败语义（三层，全部抛结构化错误，**不返回空数组冒充无数据**）：
+   * - 传输层（DNS/TLS/超时）→ `TRADING_NETWORK`；
+   * - HTTP 403/4xx/5xx → `TRADING_UPSTREAM_ERROR`，消息带状态码与响应片段
+   *   （403 的 text/plain 体就是 Cloudflare 1010，直接可读）；
+   * - 200 但体不是 JSON → `TRADING_UPSTREAM_ERROR`（契约破损，不静默吞）。
+   */
+  get(path: string, query?: Readonly<Record<string, string>>): Promise<GammaResponse>;
+}
+//#endregion
+export { DEFAULT_TIMEOUT_MS, GAMMA_BASE_URL, GammaClient, GammaResponse, GammaTransportOptions, USER_AGENT };

package/lib/gamma.js

@@ -0,0 +1,93 @@
+import { PolymarketError, bodySnippet } from "./errors.js";
+//#region src/gamma.ts
+/**
+* Polymarket gamma 公开只读 API 的传输层。
+*
+* 只读边界（硬约束）：本模块只访问 `gamma-api.polymarket.com` 的 `/events`
+* 读取面；**不触达任何下单/交易端点**（无 CLOB 鉴权头、无 /order、无 API key）。
+*
+* 三条实测约束（全部来自 spikes/impl-polymarket/EVIDENCE.md，不另起猜法）：
+*
+* 1. **必须带 UA**：`curl` 默认 UA 与 `Mozilla/5.0` 均 200；`Python-urllib/3.11`
+*    触发 Cloudflare 1010 → 403，响应体是 **text/plain**（不是 JSON）。本模块固定
+*    发送可识别的自有 UA（实测 200），并在 403/非 JSON 响应上抛结构化错误——
+*    绝不把准入失败读成「没有数据」。
+* 2. **CDN 5 分钟缓存**：`/events` 回 `cache-control: public, max-age=300`，
+*    快照轮询快于 5 分钟只会拿到同一份副本。需要实时值时由调用方传
+*    `cacheBust: true`（任意 query 变化即 `cf-cache-status: MISS`）。
+* 3. **超时要显式**：上游无 429 证据，但存在 TLS `SSL_ERROR_SYSCALL`（curl 35）
+*    与 DNS/连接超时；用 AbortSignal 超时把它变成 TRADING_NETWORK 而不是悬挂。
+*/
+const GAMMA_BASE_URL = "https://gamma-api.polymarket.com";
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* 自有 UA。实测矩阵（raw/connector-live-ua-matrix.txt，2026-10-11T02:00Z）：
+* `Mozilla/5.0` 200、`Mozilla/5.0 (compatible; <name>)` 200、`<name>/<ver>` 200、
+* `Python-urllib/3.11` 403。取自有标识而非伪造浏览器 UA——请求语义诚实，
+* 且仍落在 200 的集合内。
+*/
+const USER_AGENT = "dsh-trading-connector-polymarket/0.6.1";
+var GammaClient = class {
+	timeoutMs;
+	fetchImpl;
+	baseUrl;
+	userAgent;
+	constructor(options = {}) {
+		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+		this.baseUrl = options.baseUrl ?? "https://gamma-api.polymarket.com";
+		this.userAgent = options.userAgent ?? "dsh-trading-connector-polymarket/0.6.1";
+	}
+	/**
+	* GET `path?query`。
+	*
+	* 失败语义（三层，全部抛结构化错误，**不返回空数组冒充无数据**）：
+	* - 传输层（DNS/TLS/超时）→ `TRADING_NETWORK`；
+	* - HTTP 403/4xx/5xx → `TRADING_UPSTREAM_ERROR`，消息带状态码与响应片段
+	*   （403 的 text/plain 体就是 Cloudflare 1010，直接可读）；
+	* - 200 但体不是 JSON → `TRADING_UPSTREAM_ERROR`（契约破损，不静默吞）。
+	*/
+	async get(path, query = {}) {
+		const url = new URL(path, this.baseUrl);
+		for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value);
+		const controller = new AbortController();
+		const timer = setTimeout(() => {
+			controller.abort();
+		}, this.timeoutMs);
+		let response;
+		try {
+			response = await this.fetchImpl(url, {
+				method: "GET",
+				headers: {
+					"user-agent": this.userAgent,
+					accept: "application/json"
+				},
+				signal: controller.signal
+			});
+		} catch (cause) {
+			throw networkError(url.pathname, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		const text = await response.text();
+		if (!response.ok) throw new PolymarketError("TRADING_UPSTREAM_ERROR", `polymarket gamma ${url.pathname}: HTTP ${response.status} — ${bodySnippet(text)}`);
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			throw new PolymarketError("TRADING_UPSTREAM_ERROR", `polymarket gamma ${url.pathname}: HTTP ${response.status} but the body is not JSON — ${bodySnippet(text)}`);
+		}
+		return {
+			status: response.status,
+			body,
+			text
+		};
+	}
+};
+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 };

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+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 { 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 { 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 };

package/lib/index.js

@@ -0,0 +1,7 @@
+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 { SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotStore, applySnapshot, defaultSnapshotPath, emptySnapshotTable, parseSnapshotTable } from "./snapshot.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 };

package/lib/plugin.d.ts

@@ -0,0 +1,37 @@
+import { PolymarketService } from "./service.js";
+import Schema from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/plugin.d.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
+declare const name = "dsh-trading-connector-polymarket";
+/** 本插件不注册工具、不依赖任何宿主服务（纯 provide）。 */
+declare const inject: string[];
+interface Config {
+  enabled: boolean;
+  /** 单次 gamma 请求超时（ms）。 */
+  timeoutMs: number;
+  /** 是否启用本地快照（Δ 标注）。关闭后 `changeSincePrevious` 一律缺省。 */
+  snapshots: boolean;
+  /** 快照文件覆盖（绝对路径；缺省 `$DSH_HOME/polymarket/snapshots.json`）。 */
+  snapshotPath: string;
+}
+declare const Config: Schema<Config>;
+interface ApplyOverrides {
+  /** 注入的 fetch（单测用契约化替身）。 */
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** 基址覆盖（单测指向本地夹具服务）。 */
+  readonly baseUrl?: string;
+  /** 时钟注入（单测固定 fetchedAt）。 */
+  readonly now?: (() => number) | undefined;
+}
+/** 组装取数服务（测试可直接注入 fetchImpl，无需 mock 全局）。 */
+declare function createPolymarketService(config: Config, overrides?: ApplyOverrides): PolymarketService;
+/**
+ * 插件钩子（宿主签名 `apply(ctx, config)`）。
+ *
+ * 不接收注入参数：测试用的 fetch/时钟替身走 {@link createPolymarketService}，不往
+ * 生产钩子的签名里加测试专用面（connector-jin10 同款纪律）。
+ */
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { ApplyOverrides, Config, apply, createPolymarketService, inject, name };

package/lib/plugin.js

@@ -0,0 +1,41 @@
+import { DEFAULT_TIMEOUT_MS, GammaClient } from "./gamma.js";
+import { PolymarketService, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed } from "./service.js";
+import { SnapshotStore } from "./snapshot.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 = [];
+const Config = Schema.object({
+	enabled: Schema.boolean().default(true).description("是否启用 Polymarket 预测市场数据面"),
+	timeoutMs: Schema.number().default(DEFAULT_TIMEOUT_MS).description("单次 gamma-api 请求超时（ms）"),
+	snapshots: Schema.boolean().default(true).description("是否用本地快照标注概率变动（存 trading home）"),
+	snapshotPath: Schema.string().default("").description("快照文件绝对路径（留空 = $DSH_HOME/polymarket/snapshots.json）")
+});
+/** 组装取数服务（测试可直接注入 fetchImpl，无需 mock 全局）。 */
+function createPolymarketService(config, overrides = {}) {
+	const gamma = new GammaClient({
+		timeoutMs: config.timeoutMs,
+		...overrides.fetchImpl !== void 0 ? { fetchImpl: overrides.fetchImpl } : {},
+		...overrides.baseUrl !== void 0 ? { baseUrl: overrides.baseUrl } : {}
+	});
+	const snapshots = config.snapshots ? new SnapshotStore(config.snapshotPath === "" ? {} : { filePath: config.snapshotPath }) : void 0;
+	return new PolymarketService({
+		gamma,
+		...snapshots !== void 0 ? { snapshots } : {},
+		...overrides.now !== void 0 ? { now: overrides.now } : {}
+	});
+}
+/**
+* 插件钩子（宿主签名 `apply(ctx, config)`）。
+*
+* 不接收注入参数：测试用的 fetch/时钟替身走 {@link createPolymarketService}，不往
+* 生产钩子的签名里加测试专用面（connector-jin10 同款纪律）。
+*/
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	ctx.reflect.provide(TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed(createPolymarketService(config)));
+}
+//#endregion
+export { Config, apply, createPolymarketService, inject, name };

package/lib/service.d.ts

@@ -0,0 +1,52 @@
+import { GammaClient } from "./gamma.js";
+import { SnapshotStore } from "./snapshot.js";
+import { PredictionFeed, PredictionFeedService } from "@dshtrading/api";
+//#region src/service.d.ts
+declare const TRADING_PREDICTION_FEED_KEY = "tradingPredictionFeed";
+/** 单次取数的候选上限（上游 limit 上限 100，证据 Q1.4）。 */
+declare const PREDICTION_EVENTS_LIMIT = 100;
+interface PolymarketServiceOptions {
+  readonly gamma: GammaClient;
+  /** 快照存储；缺省 = 不做 Δ 标注（服务仍可用）。 */
+  readonly snapshots?: SnapshotStore | undefined;
+  /** 时钟注入（测试固定 fetchedAt 用；缺省 Date.now）。 */
+  readonly now?: (() => number) | undefined;
+}
+/**
+ * 取数实现：**一次 GET 拿全量**（证据 Q2.3 的 v1 裁决理由）。
+ *
+ * `cacheBust` 的用途（证据 Q3.4）：`/events` 有 `max-age=300` CDN 缓存，同一请求
+ * 5 分钟内只会拿到同一份副本。默认**不加**（面板轮询间隔离不开 5 分钟时缓存是
+ * 有益的去重）；需要真实时值时可显式打开。
+ */
+declare class PolymarketService {
+  private readonly gamma;
+  private readonly snapshots;
+  private readonly now;
+  constructor(options: PolymarketServiceOptions);
+  /**
+   * FOMC 决议路径全量会议（含已结算；按 endDate 升序）。
+   *
+   * **失败必须响亮**：传输失败、HTTP 403（Cloudflare 1010 的 text/plain 体）、
+   * 非 JSON 体、非数组体一律抛结构化错误——绝不返回 `{meetings: []}`。空数组
+   * 只代表「上游确实返回了空集合」这一种真实语义。
+   */
+  listFomcMeetings(options?: {
+    cacheBust?: boolean | undefined;
+  }): Promise<PredictionFeed>;
+  /**
+   * Δ 标注：**快照失败不阻断取数**。
+   *
+   * 为什么与上游失败区别对待：上游失败时我们没有任何可信数据，必须响亮抛错；
+   * 快照失败时概率本身依然完整正确，缺的只是「与上次差多少」这一项增益标注。
+   * 此时若整块失败，会把一次磁盘/权限问题放大成整个面板黑屏。
+   *
+   * 但降级必须**可见**：log 到 stderr，并且返回的档位**不带** `changeSincePrevious`
+   * （缺省 = 不知道），绝不填 0——0 表示「确知没变」，那是编造。
+   */
+  private annotate;
+}
+/** host 平面服务面：桥与工具面共用的最小接口（@dshtrading/api 的 PredictionFeedService）。 */
+declare function createPolymarketPredictionFeed(service: PolymarketService): PredictionFeedService;
+//#endregion
+export { PREDICTION_EVENTS_LIMIT, PolymarketService, PolymarketServiceOptions, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed };

package/lib/service.js

@@ -0,0 +1,73 @@
+import { discoverFomcMeetings } from "./discovery.js";
+//#region src/service.ts
+const TRADING_PREDICTION_FEED_KEY = "tradingPredictionFeed";
+/** 单次取数的候选上限（上游 limit 上限 100，证据 Q1.4）。 */
+const PREDICTION_EVENTS_LIMIT = 100;
+/**
+* 取数实现：**一次 GET 拿全量**（证据 Q2.3 的 v1 裁决理由）。
+*
+* `cacheBust` 的用途（证据 Q3.4）：`/events` 有 `max-age=300` CDN 缓存，同一请求
+* 5 分钟内只会拿到同一份副本。默认**不加**（面板轮询间隔离不开 5 分钟时缓存是
+* 有益的去重）；需要真实时值时可显式打开。
+*/
+var PolymarketService = class {
+	gamma;
+	snapshots;
+	now;
+	constructor(options) {
+		this.gamma = options.gamma;
+		this.snapshots = options.snapshots;
+		this.now = options.now ?? Date.now;
+	}
+	/**
+	* FOMC 决议路径全量会议（含已结算；按 endDate 升序）。
+	*
+	* **失败必须响亮**：传输失败、HTTP 403（Cloudflare 1010 的 text/plain 体）、
+	* 非 JSON 体、非数组体一律抛结构化错误——绝不返回 `{meetings: []}`。空数组
+	* 只代表「上游确实返回了空集合」这一种真实语义。
+	*/
+	async listFomcMeetings(options = {}) {
+		const query = {
+			series_id: "35",
+			limit: String(100),
+			closed: "false"
+		};
+		if (options.cacheBust === true) query._cb = String(this.now());
+		const response = await this.gamma.get("/events", query);
+		const { meetings } = discoverFomcMeetings(response.body);
+		const fetchedAt = new Date(this.now()).toISOString();
+		return {
+			fetchedAt,
+			meetings: await this.annotate(meetings, fetchedAt)
+		};
+	}
+	/**
+	* Δ 标注：**快照失败不阻断取数**。
+	*
+	* 为什么与上游失败区别对待：上游失败时我们没有任何可信数据，必须响亮抛错；
+	* 快照失败时概率本身依然完整正确，缺的只是「与上次差多少」这一项增益标注。
+	* 此时若整块失败，会把一次磁盘/权限问题放大成整个面板黑屏。
+	*
+	* 但降级必须**可见**：log 到 stderr，并且返回的档位**不带** `changeSincePrevious`
+	* （缺省 = 不知道），绝不填 0——0 表示「确知没变」，那是编造。
+	*/
+	async annotate(meetings, observedAt) {
+		if (this.snapshots === void 0) return meetings;
+		try {
+			return await this.snapshots.annotate(meetings, observedAt);
+		} catch (error) {
+			console.error("[dsh-trading/connector-polymarket] snapshot annotation unavailable, continuing without Δ:", error);
+			return meetings;
+		}
+	}
+};
+/** host 平面服务面：桥与工具面共用的最小接口（@dshtrading/api 的 PredictionFeedService）。 */
+function createPolymarketPredictionFeed(service) {
+	return { 
+	/** 当前 FOMC 决议路径全部会议（含已结算）。 */
+async listFomcMeetings() {
+		return service.listFomcMeetings();
+	} };
+}
+//#endregion
+export { PREDICTION_EVENTS_LIMIT, PolymarketService, TRADING_PREDICTION_FEED_KEY, createPolymarketPredictionFeed };

package/lib/snapshot.d.ts

@@ -0,0 +1,72 @@
+import { PredictionMeeting } from "@dshtrading/api";
+//#region src/snapshot.d.ts
+/** 快照文件相对 trading home 的路径（POSIX 分隔符，join 时再拆）。 */
+declare const SNAPSHOT_DIR = "polymarket";
+declare const SNAPSHOT_FILE = "snapshots.json";
+/** 快照表版本（结构变更时递增，旧版按空表处理而不是崩）。 */
+declare const SNAPSHOT_VERSION = 1;
+/** 一条档位读数。 */
+interface SnapshotEntry {
+  /** 该档最近一次观察到的隐含概率。 */
+  readonly probability: number;
+  /** 观察时刻（ISO 8601 UTC）。 */
+  readonly observedAt: string;
+}
+/** 整张快照表：`eventId -> bucketKey -> entry`。 */
+interface SnapshotTable {
+  readonly version: number;
+  readonly meetings: Record<string, Record<string, SnapshotEntry>>;
+}
+interface SnapshotStoreOptions {
+  /** 文件绝对路径覆盖（测试注入临时目录用）。 */
+  readonly filePath?: string;
+  /** 环境变量映射（缺省 process.env；测试固定 home 用）。 */
+  readonly env?: Record<string, string | undefined>;
+}
+/** 默认快照文件路径：`$DSH_HOME/polymarket/snapshots.json`。 */
+declare function defaultSnapshotPath(env?: Record<string, string | undefined>): string;
+/** 空表（首次运行 / 结构版本不符 / 坏 JSON 的降级值——快照缺失不是错误）。 */
+declare function emptySnapshotTable(): SnapshotTable;
+/**
+ * 解析磁盘上的快照表。
+ *
+ * **降级语义**：快照是纯增益信息（有没有它都不影响概率正确性），所以坏形状一律
+ * 降级为空表**不抛错**——与「上游取数失败必须响亮」刻意相反。取数失败会掩盖成
+ * 「没有数据」，快照失败则只是少一个 Δ 标注，两者不可混为一谈。
+ */
+declare function parseSnapshotTable(raw: unknown): SnapshotTable;
+/**
+ * 给每档补 `changeSincePrevious`（与**上一次**读数的差），然后写入本次读数。
+ *
+ * 关键纪律（对应验收「失败路径不产生空数据假象」）：
+ * - 首次采样 = 无历史 → `changeSincePrevious` **缺省**，绝不填 0（0 是「确知没变」，
+ *   与「不知道」是两件事）；
+ * - 已结算档位同样写入（它们在页面上显示最终 0/1），但不再参与后续比较；
+ * - 写盘失败**不阻断取数**（调用方拿到的是已经算好的 Δ）。
+ */
+declare function applySnapshot(table: SnapshotTable, meetings: readonly PredictionMeeting[], observedAt: string): {
+  readonly meetings: readonly PredictionMeeting[];
+  readonly next: SnapshotTable;
+};
+/**
+ * 快照表的持久化句柄。
+ *
+ * `annotate()` 是唯一业务入口：**在锁内**读旧表、算 Δ、写新表——三个动作在同一
+ * 临界区里，两个宿主进程并发取数不会出现「A 读旧表、B 也读旧表、B 后写覆盖 A」。
+ * 锁超时抛 HomeFileLockTimeoutError（响亮），不静默按陈旧值覆盖。
+ */
+declare class SnapshotStore {
+  private readonly filePath;
+  constructor(options?: SnapshotStoreOptions);
+  path(): string;
+  /** 读当前表（只读；不改盘，锁内新鲜读）。 */
+  read(): Promise<SnapshotTable>;
+  /**
+   * 在锁内给本次会议补 Δ 并落盘下一次读数。
+   *
+   * 返回标注后的会议（调用方直接用它构造响应，Δ 一定与本次落盘同源）。
+   */
+  annotate(meetings: readonly PredictionMeeting[], observedAt: string): Promise<readonly PredictionMeeting[]>;
+}
+//#endregion
+export { SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotEntry, SnapshotStore, SnapshotStoreOptions, SnapshotTable, applySnapshot, defaultSnapshotPath, emptySnapshotTable, parseSnapshotTable };

package/lib/snapshot.js

@@ -0,0 +1,165 @@
+import { SKIP_WRITE, dshHomeDir, transactStore } from "@dshtrading/dsh-home";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/snapshot.ts
+/**
+* 本地价格快照（证据 Q3 的裁决产物）：只为回答「这条概率自上次观察变了多少」。
+*
+* 为什么仍要本地快照（证据 Q3.1/Q3.2）：上游 `clob.polymarket.com/prices-history`
+* 虽然有服务端历史，但**只保留约 30 天**（显式 startTs/endTs 窗口 336h 可用、
+* 720h 报 `interval is too long`），且需要按 token 扇出。本地快照是「近期 tick」，
+* 与上游历史互补，不是替代。
+*
+* 存储位置（硬约束）：trading home 下，经 `@dshtrading/dsh-home` 的 `dshHomeDir()`
+* 解析——绝不写进包内或仓库数据。默认 `$DSH_HOME/polymarket/snapshots.json`。
+*
+* 体积（证据 Q3.5 实测 237.6 bytes/row）：本实现只存**每档的最新一次读数**
+* （不是 append-only 流水），所以文件大小与「会议数 × 档位数」成正比（约 10 条
+* 会议 × 5 档 × ~200B ≈ 10 KiB），与采样频率无关。这避开了 append-only 在
+* 1/分钟频率下 119 MiB/年/会议的量级。
+*
+* 跨进程：走 `transactStore`（全仓唯一临界区实现），两个宿主共用同一 home 时
+* 不会 last-writer-wins 静默丢数据。
+*/
+/** 快照文件相对 trading home 的路径（POSIX 分隔符，join 时再拆）。 */
+const SNAPSHOT_DIR = "polymarket";
+const SNAPSHOT_FILE = "snapshots.json";
+/** 快照表版本（结构变更时递增，旧版按空表处理而不是崩）。 */
+const SNAPSHOT_VERSION = 1;
+/** 默认快照文件路径：`$DSH_HOME/polymarket/snapshots.json`。 */
+function defaultSnapshotPath(env = process.env) {
+	return join(dshHomeDir(env), SNAPSHOT_DIR, SNAPSHOT_FILE);
+}
+/** 空表（首次运行 / 结构版本不符 / 坏 JSON 的降级值——快照缺失不是错误）。 */
+function emptySnapshotTable() {
+	return {
+		version: 1,
+		meetings: {}
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 解析磁盘上的快照表。
+*
+* **降级语义**：快照是纯增益信息（有没有它都不影响概率正确性），所以坏形状一律
+* 降级为空表**不抛错**——与「上游取数失败必须响亮」刻意相反。取数失败会掩盖成
+* 「没有数据」，快照失败则只是少一个 Δ 标注，两者不可混为一谈。
+*/
+function parseSnapshotTable(raw) {
+	if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.meetings)) return emptySnapshotTable();
+	const meetings = {};
+	for (const [eventId, buckets] of Object.entries(raw.meetings)) {
+		if (!isRecord(buckets)) continue;
+		const parsed = {};
+		for (const [key, entry] of Object.entries(buckets)) {
+			if (!isRecord(entry)) continue;
+			const probability = entry.probability;
+			const observedAt = entry.observedAt;
+			if (typeof probability !== "number" || !Number.isFinite(probability)) continue;
+			if (typeof observedAt !== "string" || observedAt.trim() === "") continue;
+			parsed[key] = {
+				probability,
+				observedAt
+			};
+		}
+		meetings[eventId] = parsed;
+	}
+	return {
+		version: 1,
+		meetings
+	};
+}
+/**
+* 给每档补 `changeSincePrevious`（与**上一次**读数的差），然后写入本次读数。
+*
+* 关键纪律（对应验收「失败路径不产生空数据假象」）：
+* - 首次采样 = 无历史 → `changeSincePrevious` **缺省**，绝不填 0（0 是「确知没变」，
+*   与「不知道」是两件事）；
+* - 已结算档位同样写入（它们在页面上显示最终 0/1），但不再参与后续比较；
+* - 写盘失败**不阻断取数**（调用方拿到的是已经算好的 Δ）。
+*/
+function applySnapshot(table, meetings, observedAt) {
+	const nextMeetings = { ...table.meetings };
+	return {
+		meetings: meetings.map((meeting) => {
+			const previous = table.meetings[meeting.id];
+			const buckets = meeting.buckets.map((bucket) => {
+				const before = previous?.[bucket.key];
+				return before === void 0 ? bucket : {
+					...bucket,
+					changeSincePrevious: Number((bucket.probability - before.probability).toFixed(6))
+				};
+			});
+			nextMeetings[meeting.id] = Object.fromEntries(buckets.map((bucket) => [bucket.key, {
+				probability: bucket.probability,
+				observedAt
+			}]));
+			return {
+				...meeting,
+				buckets
+			};
+		}),
+		next: {
+			version: 1,
+			meetings: nextMeetings
+		}
+	};
+}
+const LOG_PREFIX = "[dsh-trading/connector-polymarket] failed to atomic flush snapshots to";
+/** 新鲜读盘（锁内调用；坏内容降级为空表，见 {@link parseSnapshotTable}）。 */
+async function readTableFromDisk(filePath) {
+	let text;
+	try {
+		text = await readFile(filePath, "utf8");
+	} catch {
+		return emptySnapshotTable();
+	}
+	try {
+		return parseSnapshotTable(JSON.parse(text));
+	} catch {
+		return emptySnapshotTable();
+	}
+}
+/**
+* 快照表的持久化句柄。
+*
+* `annotate()` 是唯一业务入口：**在锁内**读旧表、算 Δ、写新表——三个动作在同一
+* 临界区里，两个宿主进程并发取数不会出现「A 读旧表、B 也读旧表、B 后写覆盖 A」。
+* 锁超时抛 HomeFileLockTimeoutError（响亮），不静默按陈旧值覆盖。
+*/
+var SnapshotStore = class {
+	filePath;
+	constructor(options = {}) {
+		this.filePath = options.filePath ?? defaultSnapshotPath(options.env ?? process.env);
+	}
+	path() {
+		return this.filePath;
+	}
+	/** 读当前表（只读；不改盘，锁内新鲜读）。 */
+	async read() {
+		let table = emptySnapshotTable();
+		await transactStore(this.filePath, () => readTableFromDisk(this.filePath), (onDisk) => {
+			table = onDisk;
+			return SKIP_WRITE;
+		}, (value) => value, LOG_PREFIX);
+		return table;
+	}
+	/**
+	* 在锁内给本次会议补 Δ 并落盘下一次读数。
+	*
+	* 返回标注后的会议（调用方直接用它构造响应，Δ 一定与本次落盘同源）。
+	*/
+	async annotate(meetings, observedAt) {
+		let annotated = meetings;
+		await transactStore(this.filePath, () => readTableFromDisk(this.filePath), (onDisk) => {
+			const applied = applySnapshot(onDisk, meetings, observedAt);
+			annotated = applied.meetings;
+			return applied.next;
+		}, (value) => value, LOG_PREFIX);
+		return annotated;
+	}
+};
+//#endregion
+export { SNAPSHOT_DIR, SNAPSHOT_FILE, SNAPSHOT_VERSION, SnapshotStore, applySnapshot, defaultSnapshotPath, emptySnapshotTable, parseSnapshotTable };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@dshtrading/connector-polymarket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Polymarket 预测市场连接器（只读公开 API，无密钥）：FOMC 决议档位与隐含概率，host 面 provide tradingPredictionFeed（跨市场信息源，归 base bundle）",
+  "version": "0.6.2",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^0.6.2",
+    "@dshtrading/dsh-home": "^0.6.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
 }