@v587d/capital-generation 2.8.3 → 2.9.1

package/lib/data-collector/hub.d.ts

@@ -1,35 +1,19 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { DataTimeContract } from '../time/tools.js';
 import type { DatasetRef, SaveDatasetInput, SessionLike } from './store.js';
-/**
- * 规范化内部 data_key 片段：斜杠/冒号等路径分隔符一律映射为点，其余非常规
- * 字符折叠为点、合并连续点、去掉首尾点。data_key 只是宿主内部路由/审计身份，
- * 不出现在模型可见协议、人设或工具输出中。
- */
+/** Normalize an internal data_key token; data_key is host-only and never model-visible. */
 export declare function normalizeKeyToken(value: string): string;
-/**
- * 生成内部 data_key：provider.kind.resource（例如
- * buildDataKey('fuyao', 'api', '/api/a-share/prices/snapshot')
- * => 'fuyao.api.api.a-share.prices.snapshot'）。
- */
 export declare function buildDataKey(provider: string, kind: string, resource: string): string;
-/**
- * 数据请求：capability 是模型可见的短能力名（全局唯一），session 由工具层以
- * exec.agent.session 注入，不接受模型传参。内部 data_key 不出现在请求协议里。
- */
+/** capability is the model-visible unique key; session is injected by the tool layer, not supplied by the model. */
 export interface DataRequest {
     capability: string;
     params: Record<string, unknown>;
-    /** force_refresh=true 绕过已验证 manifest 并生成新的不可变 Dataset。 */
+    /** force_refresh bypasses manifest reuse and creates a new immutable Dataset. */
     force_refresh?: boolean;
-    /** 本次用户任务关联 id（可复用）；只用于追溯，不要求模型理解。 */
     task_id?: string;
     session: SessionLike;
 }
-/**
- * 数据源契约：capability 为唯一注册键与模型可见名；name/source/data_key
- * 均为宿主内部字段（日志、路由、审计），不得进入工具 schema、输出或人设。
- */
+/** capability is the unique registration key; name/source/data_key stay host-internal (logs, routing, audit). */
 export interface SchemaDescriptor {
     capability: string;
     name: string;
@@ -37,34 +21,29 @@ export interface SchemaDescriptor {
     data_key: string;
     source_label?: string;
     paginated?: boolean;
-    /** 可复用 Dataset 的最长采集年龄；未声明时仅受 Dataset 保留期约束。宿主内部字段。 */
+    /** Longest reusable Dataset age; defaults to the retention window. Host-only. */
     cacheMaxAgeMs?: number;
-    /**
-     * 行数组位置的显式声明。龙虎榜这类响应的行数组不在 `item` 下（`stock_items`），
-     * 只靠形状推断会把整份数据判成「不可读的文档」。谁产出数据谁声明行在哪里，
-     * 存储层不再猜。
-     */
+    /** Where the row array lives; without it, envelopes such as `stock_items` look unreadable. */
     rowShape?: RowShapeHint;
-    /** 一行摘要：只用于能力目录（选能力够用），控制在 ~50 字以内。 */
+    /** One-line catalog summary (~50 chars max). */
     summary?: string;
-    /** 完整说明：只在 describe_capability 详情里返回（单位、null 语义、时间口径、分页口径）。 */
+    /** Full detail for describe_capability only (units, null semantics, time/pagination rules). */
     description?: string;
     input_schema: object;
-    /** 机器可读时间参数契约，由时间工具与数据源共同使用。 */
+    /** Machine-readable time-parameter contract shared with the time tools. */
     time_contract?: DataTimeContract;
     output_schema?: object;
 }
-/** 能力目录项：只带"选能力"所需的信息，体积必须远小于工具结果剪枝阈值。 */
+/** Catalog entry: just enough to pick a capability. */
 export interface CapabilitySummary {
     capability: string;
     summary: string;
     paginated: boolean;
 }
-/** 单个能力的完整契约：参数与输出字段字典，调用前必读。 */
+/** Full contract for one capability; must be read before calling. */
 export interface CapabilityDetail extends CapabilitySummary {
     description: string;
     input_schema: object;
-    /** `output_schema` 的模型可见投影，见 renderOutputFields；声明不出字段时为 null。 */
     output_fields: string | null;
 }
 export interface DataSource {
@@ -73,22 +52,16 @@ export interface DataSource {
         data: unknown;
         schema?: object | null;
     }>;
-    /** Optional source-specific output guard; false rejects the result before persistence. */
+    /** Optional source guard; false rejects the result before persistence. */
     validateOutput?: (data: unknown) => boolean;
     /**
-     * Optional parameter canonicalization. The Hub calls it BEFORE computing the
-     * in-flight merge key and params_digest, so requests that differ only in
-     * case/whitespace/list order/default values share one Dataset instead of
-     * writing several. It must be idempotent (execute calls it again) and may
-     * throw to reject invalid parameters before anything is queued. Sources that
-     * omit it keep their previous behaviour exactly.
+     * Optional canonicalization; the Hub calls it before merge key and params_digest, so equivalent
+     * requests share one Dataset. Must be idempotent (execute calls it again) and may throw.
      */
     normalizeParams?: (params: Record<string, unknown>) => Record<string, unknown>;
 }
-/** Dataset 落盘器（Hub 的唯一成功出口）。 */
 export interface DatasetStoreLike {
     save(input: SaveDatasetInput): Promise<DatasetRef>;
-    /** Optional for compatibility with lightweight test stores; production store implements manifest lookup. */
     findLatest?(input: {
         session: SessionLike;
         capability: string;
@@ -96,35 +69,29 @@ export interface DatasetStoreLike {
         signal?: AbortSignal;
     }): Promise<DatasetRef | undefined>;
 }
-/** 数据源声明的行数组位置；缺省按 `item` 推断。 */
 export interface RowShapeHint {
-    /** 行数组所在的顶层键名（默认 `item`）。 */
+    /** Top-level key holding rows (default `item`). */
     rowKey?: string;
-    /** 可选的多个行数组路径，支持 `[]` 展开并合并为一组 rows。 */
+    /** Multiple row paths; `[]` expands and merges them into one row set. */
     rowKeys?: string[];
-    /** 顶层本身就是行数组。 */
+    /** The top level is itself the row array. */
     rootArray?: boolean;
 }
 export interface DataCollectorHubOptions {
-    /** 必需：宿主侧 Dataset store；缺失时 request 直接失败。 */
+    /** Required Dataset store; request fails without it. */
     store: DatasetStoreLike;
-    /** 队列最大长度；默认 50。 */
+    /** Queue length (default 50). */
     maxQueueLength?: number;
-    /** 传输层执行超时；默认 30_000 ms。只是请求超时，不是数据生命周期。 */
+    /** Transport timeout only (30s default), not data lifetime. */
     requestTimeoutMs?: number;
-    /** 时钟注入（测试用）；默认 Date.now。 */
     now?: () => number;
 }
 /**
- * Phase 1 数据执行器：FIFO 串行执行外部数据源，成功后由宿主 store 立即
- * 原子落盘为不可变 Dataset，只回传 DatasetRef。
- *
- * 明确不做：长期 raw data 内存缓存、按 data_key 的查询、source_preference 路由。
- * 已验证 DatasetRef 的复用由 workspace manifest 提供，内存只保留 in-flight 队列。
+ * FIFO executor: success is persisted immediately as an immutable Dataset and only a DatasetRef is
+ * returned. In-flight queue is the only in-memory raw data; reuse comes from workspace manifests.
  */
 export declare class DataCollectorHub {
     private readonly queue;
-    /** 正在执行的队列项（执行期间不在 queue 中，但仍参与合并与容量判断）。 */
     private active;
     private readonly sources;
     private readonly cacheLookups;
@@ -136,46 +103,21 @@ export declare class DataCollectorHub {
     constructor(options: DataCollectorHubOptions);
     registerSource(source: DataSource): () => void;
     /**
-     * 入队并阻塞等待完成：先按 capability+params_digest 查找当前 session 下仍有效的
-     * manifest；force_refresh=true 或没有可复用 Dataset 时才进入数据源队列。相同的
-     * in-flight 请求仍共享一次执行，成功后立即由宿主 store 原子落盘。
-     *
-     * 参数规范化（source 可选）发生在这里：merge key 与 digest 都用规范化后的参数，
-     * 因此「大小写/空白/重复项不同、语义相同」的请求命中同一个 Dataset。未知
-     * capability 不做处理，仍由执行阶段抛出统一的 no data source 错误。
+     * Enqueue and wait: reuse a valid manifest unless force_refresh; identical in-flight requests share
+     * one execution. Params are normalized before merge key and digest.
      */
     request(request: DataRequest, options?: {
         signal?: AbortSignal;
     }): Promise<DatasetRef>;
-    /** 应用 source 的可选参数规范化；未声明或 capability 未注册时原样返回。 */
     private normalizeRequest;
-    /** 挂一个等待者并返回其结算承诺；signal 触发时摘除等待者并拒绝（不影响共享执行）。 */
     private awaitSettlement;
-    /** 结算一个等待者：无论成败都摘除监听，防止重复结算。 */
     private settleWaiter;
-    /**
-     * 能力目录（模型可见的最外层发现入口）：只含 capability、一行摘要与是否分页。
-     *
-     * 目录刻意不带 input_schema / output_schema —— 全量 schema 一度达 23KB，
-     * 会被工具结果剪枝器截掉中间部分，导致排在中间的能力在发现阶段不可见。
-     * 目录必须一次性全部返回（体积预算由测试守住），详情走 describeCapability。
-     * 不含任何内部路由字段（name/source/data_key/source_label）。
-     */
+    /** Catalog: capability, one-line summary, paginated only. Full schemas would be pruned; details come from describeCapability. */
     listCapabilities(): CapabilitySummary[];
-    /** 当前已注册的能力名（用于未知名字的引导与诊断）。 */
     capabilityNames(): string[];
-    /**
-     * 能力目录的模型可见形态：一行一条 `capability|summary|paginated`（1=分页、0=不分页）。
-     * 同等信息量下 JSON 数组要 5530 字符（69 条实测，其中 58% 是键名与标点），行编码 2435、
-     * 均摊从 80 降到 35 字符——目录余量从 +7 条变成 +105 条。信息量没变、依然一次性全量返回，
-     * §1.1 那条"不分页、不裁剪"的硬约束原样成立。结构化形态仍由 listCapabilities 提供（测试与内部消费）。
-     */
+    /** Model-visible catalog: one `capability|summary|paginated` line each; JSON costs about twice the tokens. */
     capabilityDirectory(): string;
-    /**
-     * 单个能力的完整契约；名字未注册时返回 undefined，由工具层分类成可引导的错误。
-     * 返回值只含模型可见字段，是新建的普通对象，不回传内部 live data。
-     * `output_fields` 是 `output_schema` 的投影：详情体积按列数增长会被宽表打穿，见 renderOutputFields。
-     */
+    /** Single capability contract; undefined for unknown names (the tool layer classifies it). */
     describeCapability(capability: string): CapabilityDetail | undefined;
     private processNext;
 }

package/lib/data-collector/hub.js

@@ -1,23 +1,13 @@
-/**
- * 规范化内部 data_key 片段：斜杠/冒号等路径分隔符一律映射为点，其余非常规
- * 字符折叠为点、合并连续点、去掉首尾点。data_key 只是宿主内部路由/审计身份，
- * 不出现在模型可见协议、人设或工具输出中。
- */
+/** Normalize an internal data_key token; data_key is host-only and never model-visible. */
 export function normalizeKeyToken(value) {
     return value.replace(/[\\/:]+/g, '.')
         .replace(/[^A-Za-z0-9._-]+/g, '.')
         .replace(/\.{2,}/g, '.')
         .replace(/^\.+|\.+$/g, '');
 }
-/**
- * 生成内部 data_key：provider.kind.resource（例如
- * buildDataKey('fuyao', 'api', '/api/a-share/prices/snapshot')
- * => 'fuyao.api.api.a-share.prices.snapshot'）。
- */
 export function buildDataKey(provider, kind, resource) {
     return [provider, kind, resource].map(normalizeKeyToken).filter(Boolean).join('.');
 }
-/** 目录项摘要的兜底：描述缺失或没有 summary 时取首句并截断。 */
 function summarize(source) {
     if (typeof source.summary === 'string' && source.summary.trim().length > 0)
         return source.summary.trim();
@@ -27,10 +17,7 @@ function summarize(source) {
     const firstSentence = description.split(/[。；;.]/)[0]?.trim() ?? description;
     return firstSentence.length > 80 ? `${firstSentence.slice(0, 79)}…` : firstSentence;
 }
-/**
- * 目录字段的转义：`|` 与换行是行编码的分隔符，撞上去的后果是**一条能力被读成两条**
- * （错了不报错、只是话说错那一族），所以由生产者转义而不是指望摘要里恰好没有。
- */
+/** Escape `|` and newlines: they delimit catalog lines, and one unescaped splits a capability in two. */
 function encodeDirectoryField(value) {
     return value
         .replace(/\\/g, '\\\\')
@@ -42,14 +29,13 @@ function encodeDirectoryField(value) {
 function isPlainRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** 说明段里不许有换行：一个字段变成两行会让字典的"一行一字段"承诺失效。 */
 function inlineFieldText(value) {
     if (typeof value !== 'string')
         return undefined;
     const text = value.replace(/\s+/g, ' ').trim();
     return text.length === 0 ? undefined : text;
 }
-/** 字段字典的递归上界：真实契约最深 3 层，留余量，也不给畸形 schema 无限展开的机会。 */
+/** Recursion bound for field dictionaries; real contracts are at most 3 deep. */
 const MAX_FIELD_DEPTH = 5;
 function inspectField(node) {
     if (!isPlainRecord(node))
@@ -58,7 +44,7 @@ function inspectField(node) {
     if (Array.isArray(node.oneOf)) {
         const branches = node.oneOf.filter((branch) => !isPlainRecord(branch) || branch.type !== 'null');
         const nullable = branches.length !== node.oneOf.length;
-        // 可空字段的说明写在联合的外侧（{ oneOf: [...], description }），内侧分支的说明作兜底。
+        // Nullable unions carry their description on the outer node, not the null branch.
         const note = outerNote === undefined ? undefined : { description: outerNote };
         if (branches.length === 1)
             return { ...inspectField(branches[0]), nullable, ...(note ?? {}) };
@@ -79,8 +65,7 @@ function inspectField(node) {
     if (properties !== undefined) {
         return { label: typeof node.type === 'string' ? node.type : 'object', nullable: false, nested: properties, ...(description === undefined ? {} : { description }) };
     }
-    // 只有 `enum` 没写 `type` 的字段（龙虎榜渠道、板块类型这类）：按取值推断类型，并把取值列进说明段。
-    // 标成 `json` 是话说错——模型会以为取值开放，于是写出目录里不存在的值。
+    // Fields with enum but no type: infer type and list values instead of calling them open-ended json.
     if (typeof node.type !== 'string' && Array.isArray(node.enum) && node.enum.length > 0) {
         const kinds = new Set(node.enum.map((value) => (typeof value === 'number' && Number.isInteger(value) ? 'integer' : typeof value)));
         const values = node.enum.join('/');
@@ -101,14 +86,8 @@ function emitFields(properties, prefix, lines, depth) {
     }
 }
 /**
- * 把声明好的 `output_schema` 投影成字段字典：一行一个字段 `路径:类型[:说明]`，
- * 类型后缀 `?` 表示可为 null，`[].` 表示数组元素的字段，取值受限时说明段给出 `取值 a/b`。
- *
- * 为什么不直接把 JSON Schema 交给模型（实测）：详情体积几乎就等于 `output_schema` 体积，
- * 而它按每列 ~55 字符随**列数**线性增长——72 列的可转债档案光 schema 就 4699 字符，第一次
- * 注册就打穿单能力 4096 的预算。字典把每列压到 ~15 字符，列数不再卡住补录。
- * 权威声明仍住 `output_schema`：护栏与返回值契约照旧按 schema 校验，这里只是给模型看的投影，
- * 不是第二份真相。
+ * Project output_schema into one line per field. Raw JSON Schema costs ~55 chars per column and
+ * blows the per-capability budget; this is display-only, output_schema stays authoritative.
  */
 function renderOutputFields(schema) {
     if (!isPlainRecord(schema))
@@ -142,20 +121,14 @@ function paramsDigest(request) {
     }
     return hash.toString(16).padStart(16, '0').repeat(4);
 }
-/** in-flight 合并键：同一 capability+params+task 的并发请求共享同一次执行。 */
+/** In-flight merge key: same capability + params + task share one execution. */
 function mergeKey(request) {
     return `${request.capability}:${request.task_id ?? ''}:${stableSerialize(request.params)}`;
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-/**
- * 把上游错误重新包装成 Error 时**保留稳定错误码**。
- *
- * DatasetStoreError 带 `code`（如 workspace_not_writable / dataset_expired），但此前一律被
- * 拍成纯文本 Error，调用方只能从消息前缀里猜。协议要求失败回传携带 `error` 与 `code`，
- * 因此这里把 code 原样挂到新 Error 上，工具层与上层消费者都可直接读取。
- */
+/** Preserve a stable error `code` when rewrapping upstream errors; callers read it directly. */
 function errorWithCode(message, source) {
     const failure = new Error(message);
     if (source && typeof source === 'object' && typeof source.code === 'string') {
@@ -165,15 +138,11 @@ function errorWithCode(message, source) {
     return failure;
 }
 /**
- * Phase 1 数据执行器：FIFO 串行执行外部数据源，成功后由宿主 store 立即
- * 原子落盘为不可变 Dataset，只回传 DatasetRef。
- *
- * 明确不做：长期 raw data 内存缓存、按 data_key 的查询、source_preference 路由。
- * 已验证 DatasetRef 的复用由 workspace manifest 提供，内存只保留 in-flight 队列。
+ * FIFO executor: success is persisted immediately as an immutable Dataset and only a DatasetRef is
+ * returned. In-flight queue is the only in-memory raw data; reuse comes from workspace manifests.
  */
 export class DataCollectorHub {
     queue = [];
-    /** 正在执行的队列项（执行期间不在 queue 中，但仍参与合并与容量判断）。 */
     active = null;
     sources = new Map();
     cacheLookups = new Map();
@@ -208,13 +177,8 @@ export class DataCollectorHub {
             this.sources.delete(capability); };
     }
     /**
-     * 入队并阻塞等待完成：先按 capability+params_digest 查找当前 session 下仍有效的
-     * manifest；force_refresh=true 或没有可复用 Dataset 时才进入数据源队列。相同的
-     * in-flight 请求仍共享一次执行，成功后立即由宿主 store 原子落盘。
-     *
-     * 参数规范化（source 可选）发生在这里：merge key 与 digest 都用规范化后的参数，
-     * 因此「大小写/空白/重复项不同、语义相同」的请求命中同一个 Dataset。未知
-     * capability 不做处理，仍由执行阶段抛出统一的 no data source 错误。
+     * Enqueue and wait: reuse a valid manifest unless force_refresh; identical in-flight requests share
+     * one execution. Params are normalized before merge key and digest.
      */
     async request(request, options = {}) {
         if (!request.capability)
@@ -231,9 +195,7 @@ export class DataCollectorHub {
         if (normalized.force_refresh !== true && this.store.findLatest) {
             let lookup = this.cacheLookups.get(key);
             if (!lookup) {
-                // 这个 lookup 会被同一 mergeKey 的**所有**并发调用者共享，因此绝不能绑定
-                // 其中任何一个人的 AbortSignal：首个调用者取消会让其余调用者一起收到同一个
-                // lookup 失败，而不是各自独立等待。取消只作用于调用者自己的 waiter。
+                // Shared by every caller with this mergeKey, so it must not bind any caller's AbortSignal.
                 lookup = this.store.findLatest({
                     session: normalized.session,
                     capability: normalized.capability,
@@ -262,14 +224,12 @@ export class DataCollectorHub {
         void this.processNext();
         return pending;
     }
-    /** 应用 source 的可选参数规范化；未声明或 capability 未注册时原样返回。 */
     normalizeRequest(request) {
         const source = this.sources.get(request.capability);
         if (!source?.normalizeParams)
             return request;
         return { ...request, params: source.normalizeParams(request.params) };
     }
-    /** 挂一个等待者并返回其结算承诺；signal 触发时摘除等待者并拒绝（不影响共享执行）。 */
     awaitSettlement(item, signal) {
         return new Promise((resolve, reject) => {
             const waiter = { resolve, reject, signal };
@@ -287,7 +247,6 @@ export class DataCollectorHub {
             item.waiters.add(waiter);
         });
     }
-    /** 结算一个等待者：无论成败都摘除监听，防止重复结算。 */
     settleWaiter(item, waiter, outcome) {
         item.waiters.delete(waiter);
         if (waiter.onAbort && waiter.signal)
@@ -297,14 +256,7 @@ export class DataCollectorHub {
         else
             waiter.reject(outcome.error);
     }
-    /**
-     * 能力目录（模型可见的最外层发现入口）：只含 capability、一行摘要与是否分页。
-     *
-     * 目录刻意不带 input_schema / output_schema —— 全量 schema 一度达 23KB，
-     * 会被工具结果剪枝器截掉中间部分，导致排在中间的能力在发现阶段不可见。
-     * 目录必须一次性全部返回（体积预算由测试守住），详情走 describeCapability。
-     * 不含任何内部路由字段（name/source/data_key/source_label）。
-     */
+    /** Catalog: capability, one-line summary, paginated only. Full schemas would be pruned; details come from describeCapability. */
     listCapabilities() {
         return [...this.sources.values()].map((source) => ({
             capability: source.schema.capability,
@@ -312,26 +264,16 @@ export class DataCollectorHub {
             paginated: source.schema.paginated === true,
         }));
     }
-    /** 当前已注册的能力名（用于未知名字的引导与诊断）。 */
     capabilityNames() {
         return [...this.sources.keys()];
     }
-    /**
-     * 能力目录的模型可见形态：一行一条 `capability|summary|paginated`（1=分页、0=不分页）。
-     * 同等信息量下 JSON 数组要 5530 字符（69 条实测，其中 58% 是键名与标点），行编码 2435、
-     * 均摊从 80 降到 35 字符——目录余量从 +7 条变成 +105 条。信息量没变、依然一次性全量返回，
-     * §1.1 那条"不分页、不裁剪"的硬约束原样成立。结构化形态仍由 listCapabilities 提供（测试与内部消费）。
-     */
+    /** Model-visible catalog: one `capability|summary|paginated` line each; JSON costs about twice the tokens. */
     capabilityDirectory() {
         return this.listCapabilities()
             .map((entry) => `${encodeDirectoryField(entry.capability)}|${encodeDirectoryField(entry.summary)}|${entry.paginated ? 1 : 0}`)
             .join('\n');
     }
-    /**
-     * 单个能力的完整契约；名字未注册时返回 undefined，由工具层分类成可引导的错误。
-     * 返回值只含模型可见字段，是新建的普通对象，不回传内部 live data。
-     * `output_fields` 是 `output_schema` 的投影：详情体积按列数增长会被宽表打穿，见 renderOutputFields。
-     */
+    /** Single capability contract; undefined for unknown names (the tool layer classifies it). */
     describeCapability(capability) {
         const source = this.sources.get(capability);
         if (!source)
@@ -361,9 +303,7 @@ export class DataCollectorHub {
             const controller = new AbortController();
             let timeout;
             const operation = source.execute(item.request, controller.signal);
-            // Abort cooperative sources and also release the FIFO worker if a source
-            // ignores the signal. Observe the underlying promise to avoid an
-            // unhandled rejection after the timeout race has settled.
+            // Abort cooperative sources and release the FIFO worker even if a source ignores the signal.
             void operation.catch(() => { });
             const timeoutPromise = new Promise((_, reject) => {
                 timeout = setTimeout(() => {
@@ -413,13 +353,7 @@ export class DataCollectorHub {
         }
     }
 }
-/**
- * 从数据源声明的行形状推导存储 format 与行数；未声明时退化为形状推断。
- *
- * 之前只认 `data.item`，于是龙虎榜（行数组在 `stock_items`）被整份判成
- * `format: 'json'`，data_junior 连 inspect 都说不可读。行在哪里是数据源的
- * 契约知识，不该由存储层猜。
- */
+/** Derive storage format and row count from the declared row shape; fall back to inference. */
 function shapeOf(data, hint) {
     if (Array.isArray(data))
         return { format: 'json_rows', rowCount: data.length };

package/lib/data-collector/query-time.d.ts

@@ -1,28 +1,14 @@
 import { type QuerySpec } from './query.js';
 import type { SessionLike, TimeAxisSnapshot } from './store.js';
 /**
- * 受控查询的**时间轴归一**：唯一实现，`query_dataset` 与 `describe_dataset.queries` 共用。
- *
- * ⛔ 2026-09-23 事故（会话 `66fa9666`）：这一层最初只接在 `query_dataset` 上，`describe_dataset`
- * 内嵌的 queries 直接走引擎，于是同一个模型在同一个回合里得到两种行为——
- *   - `query_dataset`：`">=": "2026-09"` → 正确当作 9 月区间；
- *   - `describe_dataset.queries`：`">=": "2026"` → 被引擎当**数字 2026** 比较，243 行全中
- *     （`days_2026: 243`，静默错误）；`">=": "2026-07"` → 整条被 `skip_with_warning` 跳过，
- *     `matched_row_count: 0`（静默空结果）。
- * 协议与委派消息都写着"时间筛选直接写日期串"，所以**只要有一个入口没接上，模型就一定踩**。
- * 新增任何"执行 QuerySpec"的入口都必须复用本模块，不要在别处再写一份。
+ * Query-time normalization: the single implementation shared by query_dataset and
+ * describe_dataset.queries. Every entry point executing a QuerySpec must call it; an entry that
+ * skips it gives date strings a different meaning in the same turn.
  */
 /**
- * 时间轴归一：把 filter 里的日期写法（`2026-08-23`、`2026-08`、`2026`、`{period:"last_3_months"}`）
- * 翻译成该 Dataset 时间列自己的边界值，并给结果补 `*_iso` 可读时间列。
- *
- * 为什么在工具边界做（真机会话 1e44050e 实测）：`date_ms` 列只接受毫秒，模型于是把
- * "近 1 月 / 近 3 月 / 52 周 / 年初至今 / 历年 10 月"全部手算成 epoch——单步思考 41,961
- * 字符里绝大部分是这类算术，而且算错就是错口径。日历换算是确定性计算，属于宿主：
- * 模型只写日历，宿主按**该列观测到的偏移**换算。
- *
- * 日期串落到数值时间列时**一律响亮失败**：旧路径下 `skip_with_warning` 会把这条 filter
- * 整条跳过（`filter X skipped incompatible value`），于是"筛选消失、返回全量"却看起来成功。
+ * Translate date-like filter values into this Dataset's time-axis bounds and add `*_iso` result
+ * columns. Date strings against a numeric time column fail loudly; a skipped filter would look
+ * like a successful full-table result.
  */
 export declare function normalizeQueryDates(input: {
     store: TimeAxisProbe;
@@ -38,7 +24,6 @@ export declare function normalizeQueryDates(input: {
         time_zone?: string;
     };
 }>;
-/** 时间轴只读探针：`WorkspaceDatasetStore` 与测试替身都满足这个形状。 */
 export interface TimeAxisProbe {
     describeTimeAxis(input: {
         session: unknown;
@@ -47,11 +32,7 @@ export interface TimeAxisProbe {
         signal?: AbortSignal;
     }): Promise<TimeAxisSnapshot | undefined>;
 }
-/**
- * 结果补 ISO 时间列：`date_ms: 1787414400000` 旁边给 `date_ms_iso: "2026-08-23"`。
- * 只加不删，原值仍是唯一权威（回传口径要求"字段按工具返回原样"）。
- * 已有同名 `*_iso` 列时不覆盖，避免与 Dataset 自带字段撞名。
- */
+/** Add `*_iso` columns without replacing originals; skip an existing column to avoid collisions. */
 export declare function withIsoTimeColumns(result: Record<string, unknown>, axis: {
     column: string;
     time_zone?: string;

package/lib/data-collector/query-time.js

@@ -2,28 +2,14 @@ import { MAX_QUERY_FILTERS, DatasetQueryError } from './query.js';
 import { isRecord } from './args.js';
 import { isoDateFromEpoch, translateFilterDateValue } from './time-axis.js';
 /**
- * 受控查询的**时间轴归一**：唯一实现，`query_dataset` 与 `describe_dataset.queries` 共用。
- *
- * ⛔ 2026-09-23 事故（会话 `66fa9666`）：这一层最初只接在 `query_dataset` 上，`describe_dataset`
- * 内嵌的 queries 直接走引擎，于是同一个模型在同一个回合里得到两种行为——
- *   - `query_dataset`：`">=": "2026-09"` → 正确当作 9 月区间；
- *   - `describe_dataset.queries`：`">=": "2026"` → 被引擎当**数字 2026** 比较，243 行全中
- *     （`days_2026: 243`，静默错误）；`">=": "2026-07"` → 整条被 `skip_with_warning` 跳过，
- *     `matched_row_count: 0`（静默空结果）。
- * 协议与委派消息都写着"时间筛选直接写日期串"，所以**只要有一个入口没接上，模型就一定踩**。
- * 新增任何"执行 QuerySpec"的入口都必须复用本模块，不要在别处再写一份。
+ * Query-time normalization: the single implementation shared by query_dataset and
+ * describe_dataset.queries. Every entry point executing a QuerySpec must call it; an entry that
+ * skips it gives date strings a different meaning in the same turn.
  */
 /**
- * 时间轴归一：把 filter 里的日期写法（`2026-08-23`、`2026-08`、`2026`、`{period:"last_3_months"}`）
- * 翻译成该 Dataset 时间列自己的边界值，并给结果补 `*_iso` 可读时间列。
- *
- * 为什么在工具边界做（真机会话 1e44050e 实测）：`date_ms` 列只接受毫秒，模型于是把
- * "近 1 月 / 近 3 月 / 52 周 / 年初至今 / 历年 10 月"全部手算成 epoch——单步思考 41,961
- * 字符里绝大部分是这类算术，而且算错就是错口径。日历换算是确定性计算，属于宿主：
- * 模型只写日历，宿主按**该列观测到的偏移**换算。
- *
- * 日期串落到数值时间列时**一律响亮失败**：旧路径下 `skip_with_warning` 会把这条 filter
- * 整条跳过（`filter X skipped incompatible value`），于是"筛选消失、返回全量"却看起来成功。
+ * Translate date-like filter values into this Dataset's time-axis bounds and add `*_iso` result
+ * columns. Date strings against a numeric time column fail loudly; a skipped filter would look
+ * like a successful full-table result.
  */
 export async function normalizeQueryDates(input) {
     const filters = input.query.filters;
@@ -39,8 +25,7 @@ export async function normalizeQueryDates(input) {
         });
     }
     catch {
-        // 探针只服务"日期写法"这一便利：探针不可用（文档型 Dataset、不可读）时保持原样，
-        // 让真正的查询路径去报它自己的错，不要在这里把错误提前成另一种。
+        // Probe failure only affects this convenience translation; let the real query path report its own error.
         return { query: input.query };
     }
     if (snapshot === undefined)
@@ -75,11 +60,7 @@ export async function normalizeQueryDates(input) {
         axis: { column: snapshot.axis.column, ...(snapshot.axis.time_zone === undefined ? {} : { time_zone: snapshot.axis.time_zone }) },
     };
 }
-/**
- * 结果补 ISO 时间列：`date_ms: 1787414400000` 旁边给 `date_ms_iso: "2026-08-23"`。
- * 只加不删，原值仍是唯一权威（回传口径要求"字段按工具返回原样"）。
- * 已有同名 `*_iso` 列时不覆盖，避免与 Dataset 自带字段撞名。
- */
+/** Add `*_iso` columns without replacing originals; skip an existing column to avoid collisions. */
 export function withIsoTimeColumns(result, axis) {
     const rows = result.rows;
     if (!Array.isArray(rows))