@dshtrading/strategies 0.5.0 → 0.6.1

package/lib/api/lib/index.d.ts

@@ -1,14 +1,7 @@
+import "./instrument-form.js";
+import "@deepseek-ai/cordis";
 //#region ../api/lib/index.d.ts
 //#region src/index.d.ts
-/**
- * @dshtrading/api — 纯类型契约包（crypto-slice-plan §关键接口草案）。
- *
- * 零运行时、零依赖：服务契约由连接器实现（ctx 键按市场命名空间，如 ctx.tradingCrypto），
- * 消费方只依赖这里的类型。交易安全闸门（铁律 #3）在类型层面体现为
- * OrderRequest.dryRun 默认 true、错误词汇含 LIVE_TRADING_DISABLED / APPROVAL_DENIED。
- *
- * @module @dshtrading/api
- */
 /** K线周期（Binance 现货/合约 interval 词汇）。 */
 type Interval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
 /** 最新行情快照（公共数据，无需凭证）。 */
@@ -164,16 +157,32 @@ interface TradeTick {
   readonly timestamp: number;
 }
 type PositionSide = 'long' | 'short';
+/**
+ * 保证金模式（合约交易语义，P7）：`cross` = 全仓、`isolated` = 逐仓。
+ * 现货（cash）不使用该字段——缺席即「非保证金/未设置」。
+ */
+type MarginMode = 'cross' | 'isolated';
 /** 持仓快照。 */
 interface Position {
   readonly symbol: string;
   readonly side: PositionSide;
-  /** 仓位数量（正数；方向由 side 表达）。 */
+  /** 仓位数量（正数；方向由 side 表达）。合约仓位是 **base 币数**（连接器已按合约乘数 ctVal 由张换算）。 */
   readonly size: number;
   readonly entryPrice: number;
   readonly markPrice?: number;
   readonly unrealizedPnl?: number;
   readonly leverage?: number;
+  /**
+   * 强平价（交易所回传原样透传；交易所未提供或不适用时缺席，绝不本地推算强平价——
+   * 强平口径与保证金模式、账户级保证金、维持保证金率有关，本地公式会给出错误的安全感）。
+   */
+  readonly liquidationPrice?: number;
+  /** 维持保证金率（OKX `mgnRatio`；口径由交易所定义，原样透传，不在本地换算或反推）。 */
+  readonly marginRatio?: number;
+  /** 该仓位的保证金模式；现货持仓与交易所未提供时缺席。 */
+  readonly marginMode?: MarginMode;
+  /** 名义价值（USD，交易所口径；用于敞口核对，不参与本地风控公式）。 */
+  readonly notionalUsd?: number;
   readonly timestamp: number;
 }
 type OrderSide = 'buy' | 'sell';
@@ -184,10 +193,18 @@ interface OrderRequest {
   readonly symbol: string;
   readonly side: OrderSide;
   readonly type: OrderType;
+  /** **base 币数量**：合约（永续）由连接器按合约乘数换算成张，消费方恒用币数语义。 */
   readonly quantity: number;
   /** limit 单必填。 */
   readonly price?: number;
-  /** 缺省/true 时仅模拟，不触碰交易所。实盘还受插件 liveTrading 闸门与 approval 约束 [S4]。 */
+  /**
+   * 合约订单的保证金模式（缺省 `cross`）。仅对永续（`-SWAP`）有效：
+   * 现货订单只允许 cash 语义，传该字段由连接器结构化拒绝
+   * （现货逐仓/杠杆是另一个产品面，本仓未接线）。
+   * `isolated` 需先在交易所侧设好该标的的逐仓杠杆（OKX `setLeverage`）。
+   */
+  readonly marginMode?: MarginMode;
+  /** 缺省/true 时仅模拟，不触碰交易所。实盘还受 @dshtrading/authority 的人工签署授权与 approval 约束 [S4]。 */
   readonly dryRun?: boolean;
 }
 /** 订单回执/状态。 */
@@ -227,9 +244,49 @@ interface TradeFill {
 interface Disposable {
   dispose(): void;
 }
+/**
+ * 标的形态轴（2026-10-08 加密永续与 TradFi 永续落地）：与 `market` 正交，**不新增市场键**。
+ * 缺省 = `spot`——已存自选、localStorage 与 iOS 冻结契约因此零迁移。
+ *
+ * 形态由规范符号后缀承载（`-SWAP` = 永续），见 docs/guides/symbol-vocabulary.md；
+ * `form` 只出现在名册/检索/wire 元数据里，行情方法不新增 form 形参。
+ */
+type InstrumentForm = 'spot' | 'perp';
+/**
+ * 标的资产类别标签（仅展示与检索排序用，不承载交易语义）。
+ * **只信交易所元数据**（OKX `instCategory`、Binance `underlyingType`+`underlyingSubType`）；
+ * 取不到时留空，禁止按符号字面猜（`SPX` 在 OKX 是迷因币 SPX6900，标普 500 是 `US500`）。
+ */
+type InstrumentAssetClass = 'crypto' | 'equity' | 'commodity' | 'index';
+/** 合约专有元数据（仅 `form=perp` 有值）：交易所元数据原样透传，不本地推断。 */
+interface InstrumentContract {
+  /** 合约乘数（OKX ctVal / Binance contractSize）。 */
+  readonly multiplier?: number;
+  /** 最小价格变动。 */
+  readonly tickSize?: number;
+  /** 最小下单量/张数步长。 */
+  readonly lotSize?: number;
+  /** 交易所允许的最大杠杆。 */
+  readonly maxLeverage?: number;
+  /** 结算币种（如 USDT）。 */
+  readonly settleCcy?: string;
+}
+/**
+ * 标的检索结果的最小元数据（名册/搜索/wire 共用）。
+ * 元素形状对既有 `{ symbol, name? }` 实现向后兼容：`form`/`assetClass`/`contract` 全可选。
+ */
+interface InstrumentRef {
+  /** 市场规范词汇符号（docs/guides/symbol-vocabulary.md）。 */
+  readonly symbol: string;
+  readonly name?: string;
+  /** 缺省 = spot（老数据零迁移）。 */
+  readonly form?: InstrumentForm;
+  readonly assetClass?: InstrumentAssetClass;
+  readonly contract?: InstrumentContract;
+}
 /**
  * 行情服务契约：由市场连接器实现，注册到按市场命名空间的 ctx 键（如 ctx.tradingCrypto）。
- * 符号词汇（2026-08-31 规范，docs/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
+ * 符号词汇（2026-08-31 规范，docs/guides/symbol-vocabulary.md）：入参接受市场规范形与连接器原生形，
  * 输出 `symbol` 一律市场规范形——消费方（GUI/Agent/工作流）与数据源方言解耦。
  */
 interface MarketDataService {
@@ -238,13 +295,12 @@ interface MarketDataService {
   subscribeTicker(symbol: string, cb: (ticker: Ticker) => void): Disposable;
   /**
    * 查询本市场/交易所支持的全部标的名册（动态全集，Issue #15）。
-   * 输出 `symbol` 一律市场规范词汇（docs/symbol-vocabulary.md）。
+   * 输出 `symbol` 一律市场规范词汇（docs/guides/symbol-vocabulary.md），形态由符号后缀承载
+   * （`-SWAP` = 永续，`instrumentFormOf` 是唯一裁决实现）；每行可带
+   * `form`/`assetClass`/`contract` 元数据（InstrumentRef），缺省 = 现货。
    * 可选方法：无公开全集端点的数据源（如 tencent/yahoo/stooq）可缺省或由桥/前端回退。
    */
-  listInstruments?(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
+  listInstruments?(): Promise<InstrumentRef[]>;
   /**
    * 标的基本面与估值快照（GUI「基本面」页签用，2026-09-02）。
    * 可选方法：仅当数据源在同一公共端点里携带基本面字段时实现
@@ -280,11 +336,41 @@ interface MarketDataService {
   getRecentTrades?(symbol: string, limit?: number): Promise<TradeTick[]>;
 }
 /**
- * 交易服务契约：placeOrder 默认 dry-run；实盘前必须过插件 liveTrading 开关与
+ * 杠杆设置请求（合约交易语义，P7；仅 `form=perp` 的标的可传）。
+ * dryRun 缺省视为 true：只回本地模拟回执，不触碰交易所（与 placeOrder 同语义）。
+ */
+interface SetLeverageRequest {
+  readonly symbol: string;
+  /** 目标杠杆倍数（> 0；上限以交易所规格 `InstrumentContract.maxLeverage` 为准，超出即结构化拒绝）。 */
+  readonly leverage: number;
+  readonly marginMode: MarginMode;
+  /** 双向持仓模式下的方向（OKX `posSide`）；净持仓模式下缺席。 */
+  readonly posSide?: 'long' | 'short';
+  /** 全仓模式下按币种设置杠杆时的保证金币（OKX `ccy`）；逐仓与净持仓模式缺席。 */
+  readonly ccy?: string;
+  /** 缺省/true 时仅模拟。实盘还受 @dshtrading/authority 的人工签署授权与 approval 约束 [S4]。 */
+  readonly dryRun?: boolean;
+}
+/** 杠杆设置回执（dryRun=true 时是本地模拟回执，不触网）。 */
+interface LeverageSetting {
+  readonly symbol: string;
+  readonly leverage: number;
+  readonly marginMode: MarginMode;
+  readonly posSide?: 'long' | 'short';
+  readonly ccy?: string;
+  /** 本次是否为模拟回执（回执必须显式回带，防 dry-run 语义丢失）。 */
+  readonly dryRun: boolean;
+  readonly timestamp: number;
+}
+/**
+ * 交易服务契约：placeOrder 默认 dry-run；实盘前必须过 @dshtrading/authority 的人工签署授权与
  * ctx.approval.request（交互形态；headless 下 ask=deny，fail-closed [S4]）。
  *
  * R3（okx 切片 2026-08-29）修订：cancelOrder 增加可选 symbol、新增 getOrder——
  * OKX 按 (instId, ordId) 双键定位订单，单参 id 形态不够；无其他实现方，扩展向后兼容。
+ *
+ * P7（合约交易 Tier 2，2026-10-08）修订：新增可选 `setLeverage`——杠杆/保证金模式变更
+ * 是实盘动作，必须与下单同门槛（服务缝三态闸门 + base 审批闸门 + 人工签署授权）。
  */
 interface TradeService {
   placeOrder(req: OrderRequest): Promise<Order>;
@@ -309,6 +395,13 @@ interface TradeService {
    * 可选方法：时间升序（旧→新），最多 limit 条（缺省 ≤50）。
    */
   listTradeFills?(symbol?: string, limit?: number): Promise<TradeFill[]>;
+  /**
+   * 设置合约杠杆与保证金模式（P7 合约交易 Tier 2；仅支持合约的交易所实现）。
+   * 可选方法：不实现的连接器缺席即可，消费方按 TRADING_NOT_IMPLEMENTED 语义处理。
+   * 这是会改变账户真实风险参数的实盘动作：dryRun 缺省 true（只回本地模拟回执），
+   * dryRun=false 必须同时具备人工签署的实盘授权，并经 base 审批闸门。
+   */
+  setLeverage?(req: SetLeverageRequest): Promise<LeverageSetting>;
 }
 /**
  * Cordis Context 服务键（能力三角色之「声明」）：市场命名空间键由契约包统一声明，
@@ -339,7 +432,7 @@ declare module '@deepseek-ai/cordis' {
      * 交易服务注册表（issue #40 GUI 交易台，@dshtrading/api 类型声明）：
      * 与 tradingMarketDataRegistry 同构的宿主平面注册面——交易连接器 host 面数据行
      * 注册，GUI 桥按路由当前值惰性解析。**注册不改变安全语义**：placeOrder 的
-     * 服务缝闸门（dryRun 缺省 true + liveTrading 显式开关）随服务实例生效；
+     * 服务缝闸门（dryRun 缺省 true + @dshtrading/authority 人工签署授权）随服务实例生效；
      * GUI 桥只放行 dry-run 下单与只读查询，实盘路径仍走 Agent 工具的 base 审批闸门。
      */
     tradingTradeRegistry: TradeRegistry;
@@ -540,4 +633,4 @@ interface TradingNewsRegistry {
   markets(): string[];
 }
 //#endregion
-export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, FlashFeedService, Interval, Kline, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewsAggregator, NewsItem, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, Position, PositionSide, StockFundamentals, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingNewsRegistry };
+export { AccountBalance, AggregateNewsOptions, AggregateNewsResult, DerivativesData, DerivativesHistory, DerivativesPoint, Disposable, FlashFeedService, InstrumentAssetClass, InstrumentContract, InstrumentForm, InstrumentRef, Interval, Kline, LeverageSetting, MacroCalendarEntry, MacroFeedService, MacroRateEntry, MarginMode, MarketDataRegistration, MarketDataRegistry, MarketDataService, MarketRouterService, NewsAggregator, NewsItem, Order, OrderRequest, OrderSide, OrderStatus, OrderType, Orderbook, OrderbookLevel, Position, PositionSide, SetLeverageRequest, StockFundamentals, Ticker, TradeFill, TradeRegistration, TradeRegistry, TradeService, TradeTick, TradingNewsRegistry };

package/lib/api/lib/instrument-form.d.ts

@@ -0,0 +1 @@
+import "./index.js";

package/lib/builtin-tombstones-fs.js

@@ -1,17 +1,20 @@
-import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { SKIP_WRITE, transactStore } from "@dshtrading/dsh-home";
 import { readFile } from "node:fs/promises";
 //#region src/builtin-tombstones-fs.ts
 /**
 * 文件持久化版内置策略/选股器墓碑存储（Node.js 宿主侧使用，
 * 落 ~/.dsh/strategies/builtin-tombstones.json，形状 { deleted: string[] }）。
 *
-* 与 custom-fs.ts 同款 tmp + rename 原子写入模式；旧宿主从未写过该文件，
+* 整表持久化经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 +
+* 锁内新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复）：两进程各自删除的
+* 内置策略都留下来，后到者不会用陈旧墓碑集合覆盖。旧宿主从未写过该文件，
 * 无迁移问题（ENOENT 视为空表）。
 */
+const LOG_PREFIX = "[dsh-trading/strategies] failed to atomic flush builtin tombstones to";
 function createFileBuiltinTombstonesStore(filePath) {
 	let cache = null;
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（坏 JSON 降级空表）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
@@ -19,34 +22,40 @@ function createFileBuiltinTombstonesStore(filePath) {
 			if (Array.isArray(parsed?.deleted)) {
 				for (const id of parsed.deleted) if (typeof id === "string" && id) set.add(id);
 			}
-			cache = set;
 			return set;
 		} catch (err) {
 			if (err?.code !== "ENOENT") console.error(`[dsh-trading/strategies] failed to read builtin tombstones from ${filePath}:`, err);
-			cache = /* @__PURE__ */ new Set();
-			return cache;
+			return /* @__PURE__ */ new Set();
 		}
 	}
-	async function flush(set) {
-		await writeJsonAtomic(filePath, { deleted: [...set] }, "[dsh-trading/strategies] failed to atomic flush builtin tombstones to");
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
+	}
+	async function commit(mutate) {
+		cache = await transactStore(filePath, readFromDisk, mutate, (set) => ({ deleted: [...set] }), LOG_PREFIX);
+		return cache;
 	}
 	return {
 		async list() {
 			return [...await load()];
 		},
 		async add(id) {
-			const set = await load();
-			const fresh = !set.has(id);
-			if (fresh) {
-				set.add(id);
-				await flush(set);
-			}
+			let fresh = false;
+			await commit((onDisk) => {
+				fresh = !onDisk.has(id);
+				if (fresh) onDisk.add(id);
+				return fresh ? onDisk : SKIP_WRITE;
+			});
 			return fresh;
 		},
 		async remove(id) {
-			const set = await load();
-			const existed = set.delete(id);
-			if (existed) await flush(set);
+			let existed = false;
+			await commit((onDisk) => {
+				existed = onDisk.delete(id);
+				return existed ? onDisk : SKIP_WRITE;
+			});
 			return existed;
 		}
 	};

package/lib/custom-fs.js

@@ -1,18 +1,20 @@
 import { dirname } from "node:path";
-import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { SKIP_WRITE, transactStore } from "@dshtrading/dsh-home";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 //#region src/custom-fs.ts
 /**
 * 文件持久化版自定义策略存储（Node.js 宿主侧使用，落 ~/.dsh/strategies/custom.json）。
 *
-* 与 indicators/src/custom-fs.ts 同款 tmp + rename 原子写入模式（issue #31 规格）。
+* 整表持久化经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 +
+* 锁内新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复；issue #31 落盘形状不变）。
 * remove(archive=true) 会先把被删记录归档到 sidecar 文件（<path>.archive.jsonl，
 * JSONL 追加）——策略管理（覆盖 + 墓碑）丢弃用户 override 时可找回（2026-09-07）。
 */
+const LOG_PREFIX = "[dsh-trading/strategies] failed to atomic flush custom strategies to";
 function createFileCustomStrategyStore(filePath) {
 	let cache = null;
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（坏 JSON/坏形同既有 load 口径降级空表）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
@@ -20,16 +22,20 @@ function createFileCustomStrategyStore(filePath) {
 			if (Array.isArray(parsed)) {
 				for (const item of parsed) if (item && typeof item.id === "string") map.set(item.id, item);
 			}
-			cache = map;
 			return map;
 		} catch (err) {
 			if (err?.code !== "ENOENT") console.error(`[dsh-trading/strategies] failed to read custom strategies from ${filePath}:`, err);
-			cache = /* @__PURE__ */ new Map();
-			return cache;
+			return /* @__PURE__ */ new Map();
 		}
 	}
-	async function flush(map) {
-		await writeJsonAtomic(filePath, [...map.values()], "[dsh-trading/strategies] failed to atomic flush custom strategies to");
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
+	}
+	async function commit(mutate) {
+		cache = await transactStore(filePath, readFromDisk, mutate, (table) => [...table.values()], LOG_PREFIX);
+		return cache;
 	}
 	return {
 		async list() {
@@ -39,23 +45,25 @@ function createFileCustomStrategyStore(filePath) {
 			return (await load()).get(id);
 		},
 		async save(record) {
-			const map = await load();
-			map.set(record.id, { ...record });
-			await flush(map);
+			await commit((onDisk) => {
+				onDisk.set(record.id, { ...record });
+				return onDisk;
+			});
 		},
 		async remove(id, archive = false) {
-			const map = await load();
-			const removedRecord = map.get(id);
-			const existed = map.delete(id);
-			if (existed) {
-				if (archive && removedRecord !== void 0) try {
-					const archivePath = `${filePath}.archive.jsonl`;
-					await mkdir(dirname(filePath), { recursive: true });
-					await appendFile(archivePath, `${JSON.stringify(removedRecord)}\n`);
-				} catch (error) {
-					console.error("[dsh-trading/strategies] failed to archive removed strategy record:", error);
-				}
-				await flush(map);
+			let existed = false;
+			let removedRecord;
+			await commit((onDisk) => {
+				removedRecord = onDisk.get(id);
+				existed = onDisk.delete(id);
+				return existed ? onDisk : SKIP_WRITE;
+			});
+			if (existed && archive && removedRecord !== void 0) try {
+				const archivePath = `${filePath}.archive.jsonl`;
+				await mkdir(dirname(filePath), { recursive: true });
+				await appendFile(archivePath, `${JSON.stringify(removedRecord)}\n`);
+			} catch (error) {
+				console.error("[dsh-trading/strategies] failed to archive removed strategy record:", error);
 			}
 			return existed;
 		}

package/lib/custom-screener-fs.js

@@ -1,19 +1,21 @@
 import { dirname } from "node:path";
-import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { SKIP_WRITE, transactStore } from "@dshtrading/dsh-home";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 //#region src/custom-screener-fs.ts
 /**
 * 文件持久化版自定义选股器存储（Node.js 宿主侧使用，
 * 落 ~/.dsh/strategies/custom-screeners.json）。
 *
-* 与 custom-fs.ts 同款 tmp + rename 原子写入模式。
+* 整表持久化经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 +
+* 锁内新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复）。
 * remove(archive=true) 先把被删记录归档到 sidecar（<path>.archive.jsonl，JSONL
 * 追加）——选股器管理丢弃用户 override 时可找回（2026-09-07 审查补强）。
 */
+const LOG_PREFIX = "[dsh-trading/strategies] failed to atomic flush custom screeners to";
 function createFileCustomScreenerStore(filePath) {
 	let cache = null;
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（坏 JSON/坏形同既有 load 口径降级空表）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
@@ -21,16 +23,20 @@ function createFileCustomScreenerStore(filePath) {
 			if (Array.isArray(parsed)) {
 				for (const item of parsed) if (item && typeof item.id === "string") map.set(item.id, item);
 			}
-			cache = map;
 			return map;
 		} catch (err) {
 			if (err?.code !== "ENOENT") console.error(`[dsh-trading/strategies] failed to read custom screeners from ${filePath}:`, err);
-			cache = /* @__PURE__ */ new Map();
-			return cache;
+			return /* @__PURE__ */ new Map();
 		}
 	}
-	async function flush(map) {
-		await writeJsonAtomic(filePath, [...map.values()], "[dsh-trading/strategies] failed to atomic flush custom screeners to");
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
+	}
+	async function commit(mutate) {
+		cache = await transactStore(filePath, readFromDisk, mutate, (table) => [...table.values()], LOG_PREFIX);
+		return cache;
 	}
 	return {
 		async list() {
@@ -40,23 +46,25 @@ function createFileCustomScreenerStore(filePath) {
 			return (await load()).get(id);
 		},
 		async save(record) {
-			const map = await load();
-			map.set(record.id, { ...record });
-			await flush(map);
+			await commit((onDisk) => {
+				onDisk.set(record.id, { ...record });
+				return onDisk;
+			});
 		},
 		async remove(id, archive = false) {
-			const map = await load();
-			const removedRecord = map.get(id);
-			const existed = map.delete(id);
-			if (existed) {
-				if (archive && removedRecord !== void 0) try {
-					const archivePath = `${filePath}.archive.jsonl`;
-					await mkdir(dirname(filePath), { recursive: true });
-					await appendFile(archivePath, `${JSON.stringify(removedRecord)}\n`);
-				} catch (error) {
-					console.error("[dsh-trading/strategies] failed to archive removed screener record:", error);
-				}
-				await flush(map);
+			let existed = false;
+			let removedRecord;
+			await commit((onDisk) => {
+				removedRecord = onDisk.get(id);
+				existed = onDisk.delete(id);
+				return existed ? onDisk : SKIP_WRITE;
+			});
+			if (existed && archive && removedRecord !== void 0) try {
+				const archivePath = `${filePath}.archive.jsonl`;
+				await mkdir(dirname(filePath), { recursive: true });
+				await appendFile(archivePath, `${JSON.stringify(removedRecord)}\n`);
+			} catch (error) {
+				console.error("[dsh-trading/strategies] failed to archive removed screener record:", error);
 			}
 			return existed;
 		}

package/lib/plugin.js

@@ -54,7 +54,7 @@ function createStrategyAuthorTool(options) {
 	const { store, tombstones, onWritten } = options;
 	return defineTool({
 		name: "strategy_author",
-		description: "Author, validate, and persist a custom trading strategy from JavaScript compute source. compute(bars, params) must return StrategySignal[] (entry/exit at bar close, filled at next bar open by the backtest engine). The validator runs sandbox trial calculations across multiple kline scenarios and replays the signal sequence for engine-replayability. If valid, the strategy is persisted and immediately available for backtesting and the strategy roster. Submitting an id equal to a built-in paradigm id (donchian-breakout / rsi-reversion / ema-crossover / bollinger-reversion / sma-baseline / momentum-12m) OVERRIDES that built-in strategy (the factory default stays recoverable via strategy_reset).",
+		description: "Author, validate and persist a custom trading strategy from JavaScript compute source. compute(bars, params) must return StrategySignal[] (entry/exit at bar close, filled at the next bar open). The validator runs sandbox trials over kline scenarios and replays the sequence for engine replayability; a valid strategy is persisted and immediately backtestable. A built-in paradigm id overrides that built-in; strategy_reset restores the factory default.",
 		parameters: {
 			id: {
 				type: "string",
@@ -64,12 +64,12 @@ function createStrategyAuthorTool(options) {
 			title: {
 				type: "string",
 				required: true,
-				description: "Display name (1-32 chars), e.g. \"双均线止损止盈\""
+				description: "Display name (1-32 chars), e.g. \"double-MA stop loss and take profit\"."
 			},
 			horizon: {
 				type: "string",
 				required: true,
-				description: "Strategy horizon: \"short\" (短线), \"swing\" (波段), or \"long\" (长线)"
+				description: "Strategy horizon: \"short\" (intraday), \"swing\" (days to weeks) or \"long\" (months or more)."
 			},
 			summary: {
 				type: "string",
@@ -127,7 +127,7 @@ function createStrategyAuthorTool(options) {
 function createStrategyListTool(options) {
 	return defineTool({
 		name: "strategy_list",
-		description: "List the user strategy roster: built-in paradigms (with their parameter keys/defaults), custom strategies authored via strategy_author, and tombstoned (deleted) built-in ids. Read-only. ALWAYS call this before strategy_backtest / strategy_delete / strategy_reset when you do not already have an id from this session, and before strategy_backtest with paramsJson so you know the declared parameter keys. A paradigm with overridden=true is a built-in currently replaced by a user record; deleted=true means the built-in is tombstoned and hidden from the roster until strategy_reset restores it.",
+		description: "List the strategy roster: built-in paradigms with their parameter keys/defaults, custom strategies authored via strategy_author, and tombstoned built-in ids. Read-only. Call it before strategy_backtest / strategy_delete / strategy_reset when you have no id from this session, and before passing paramsJson so you know the parameter keys. overridden=true means a built-in currently replaced by a user record; deleted=true means it is tombstoned until strategy_reset restores it.",
 		parameters: {},
 		output: {
 			schema: { type: "string" },
@@ -211,7 +211,7 @@ function screenerRecordEntry(record) {
 function createScreenerListTool(options) {
 	return defineTool({
 		name: "screener_list",
-		description: "List the screener roster: built-in screeners (with their parameter keys and result column keys), custom screeners authored via screener_author, and tombstoned (deleted) built-in screener ids. Read-only. ALWAYS call this before screener_run / screener_delete / screener_reset when you do not already have an id from this session. A screener with overridden=true is a built-in currently replaced by a user record; deleted=true means the built-in is tombstoned and hidden from the roster until screener_reset restores it.",
+		description: "List the screener roster: built-in screeners with their parameter and result-column keys, custom screeners authored via screener_author, and tombstoned built-in ids. Read-only. Call it before screener_run / screener_delete / screener_reset when you have no id from this session. overridden=true means a built-in currently replaced by a user record; deleted=true means the built-in is tombstoned until screener_reset restores it.",
 		parameters: {},
 		output: {
 			schema: { type: "string" },
@@ -295,7 +295,7 @@ async function resolveStrategyDefinition(store, strategyId, options) {
 function createStrategyBacktestTool(deps) {
 	return defineTool({
 		name: "strategy_backtest",
-		description: "Backtest a strategy (custom authored via strategy_author, or a built-in paradigm like ema-crossover / donchian-breakout / rsi-reversion / bollinger-reversion / sma-baseline / momentum-12m) on a symbol and interval using the pure-function engine. Returns 8 metrics (totalReturn, cagr, maxDrawdown, sharpe, winRate, profitFactor, tradeCount, exposure), the trade list, and the equity curve. Signals confirm at bar close and fill at the next bar open with fee/slippage modeling; this is simulation only — it never places orders. Pass paramsJson to override declared parameters (values clamped to min/max) and read the echoed params.effective; call strategy_list first when you need an id or its parameter keys.",
+		description: "Backtest a strategy (custom from strategy_author, or a built-in paradigm) on a symbol and interval with the pure-function engine. Returns 8 metrics (totalReturn, cagr, maxDrawdown, sharpe, winRate, profitFactor, tradeCount, exposure), the trade list and the equity curve. Signals confirm at bar close and fill at the next bar open with fee/slippage modeling; simulation only, never places orders. paramsJson overrides declared parameters and is echoed in params.effective.",
 		parameters: {
 			strategyId: {
 				type: "string",
@@ -495,7 +495,7 @@ function createScreenerAuthorTool(options) {
 	const { store, tombstones, onWritten } = options;
 	return defineTool({
 		name: "screener_author",
-		description: "Author, validate, and persist a custom stock screener from JavaScript evaluate source. evaluate(bars, params) is a single-point cross-section predicate: return a ScreenerMatch ({ metrics: Record<string, number> with keys declared in columns, reason }) or null when the symbol does not match / lacks data. The validator runs sandbox trial calculations across multiple kline scenarios. If valid, the screener is persisted and immediately available in the GUI screener roster. Submitting an id equal to a built-in screener id (scr.ma-bull-align / scr.volume-breakout / scr.rsi-oversold / scr.near-high / scr.above-ma) OVERRIDES that built-in screener (factory default stays recoverable via screener_reset).",
+		description: "Author, validate and persist a custom stock screener from JavaScript evaluate source. evaluate(bars, params) is a single-point cross-section predicate returning a ScreenerMatch ({ metrics with keys declared in columns, reason }) or null when the symbol does not match or lacks data. A valid screener is persisted into the GUI roster. An id equal to a built-in screener id overrides that built-in; screener_reset restores the factory default.",
 		parameters: {
 			id: {
 				type: "string",
@@ -505,7 +505,7 @@ function createScreenerAuthorTool(options) {
 			title: {
 				type: "string",
 				required: true,
-				description: "Display name (1-32 chars), e.g. \"量价双确认\""
+				description: "Display name (1-32 chars), e.g. \"price-volume double confirmation\"."
 			},
 			summary: {
 				type: "string",
@@ -834,7 +834,7 @@ function parseParamsOverride(paramsJson, specs, tool, ownerId) {
 function createScreenerRunTool(deps) {
 	return defineTool({
 		name: "screener_run",
-		description: "Run one screener (built-in or custom, by id from screener_list) over a market and return the matched instruments with their metric columns and a one-line reason. Read-only cross-sectional scan: it fetches daily candles from the routed market data provider, evaluates a pure function per instrument, and never places orders or emits trading signals. Instruments whose window is too short are skipped silently (contract semantics); per-instrument fetch/evaluate failures are counted, never fatal. Cost guards are explicit in the result: scanPool (pool cap), scanned, failed, insufficient, resultLimit, truncated, budgetMs and deadlineExceeded (no cancellation channel exists — the scan stops taking new instruments once the time budget is spent). ALWAYS call screener_list first to get the id and its parameter/column keys.",
+		description: "Run one screener (id from screener_list) over a market and return matched instruments with their metric columns and a one-line reason. Read-only cross-sectional scan: daily candles come from the routed market-data provider, a pure function runs per instrument, and no order is ever placed. Instruments with too short a window are skipped silently; per-instrument failures are counted, never fatal. The result carries the cost guards (scanned, failed, truncated, deadlineExceeded).",
 		parameters: {
 			screenerId: {
 				type: "string",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/strategies",
   "description": "Trading strategies kernel for dsh-trading: pure math backtesting engine, strategy contracts, and 6 reference paradigms (short, swing, long). Pure library (zero runtime dependencies, browser-packable).",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,8 +21,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/dsh-home": "^0.5.0",
-    "@dshtrading/indicators": "0.5.0"
+    "@dshtrading/dsh-home": "^0.6.1",
+    "@dshtrading/indicators": "0.6.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -32,7 +32,7 @@
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
     "typescript": "^5.5.0",
-    "@dshtrading/api": "0.5.0"
+    "@dshtrading/api": "0.6.1"
   },
   "scripts": {
     "build": "tsdown",