[Bug] Lossless JSON snapshots change raw values into objects: exact-integer transport

[TanTsiChen]

DSH's lossless-JSON validator currently accepts genuine JSON.rawJSON values, but its snapshot helper changes them into ordinary objects. A JSON number can therefore become a JSON object despite successful validation.

This deserves tracking independently of input-number rounding. The motivating use case is AI4S involving category theory, where exact integer coefficients must retain their mathematical value. The reproduction uses only public DSH code and generic values.

Reproduction

Verified on Node.js v22.23.2 against upstream commit 5badb15009ae1756c3afe0ae0cef1faafc290ccc. From a checkout of that revision:

node --experimental-strip-types --input-type=module <<'JS'
import { isJsonValue, snapshotJsonValue } from './packages/util/values/src/index.ts';

const value = { n: JSON.rawJSON('9007199254740993') };
console.log(isJsonValue(value));
console.log(JSON.stringify(value));
console.log(JSON.stringify(snapshotJsonValue(value)));
JS

Actual output:

true
{"n":9007199254740993}
{"n":{"rawJSON":"9007199254740993"}}

No model, credentials, or application code is required. The same type change occurs with nested arrays, negative integers, and even JSON.rawJSON('7').

Expected: either explicitly reject unsupported raw-JSON values or preserve their JSON meaning in a detached snapshot. Successful validation should not silently change the value's type. This expectation does not require arbitrary-precision arithmetic inside DSH.

Cause and affected boundary

snapshotJsonValue copies the enumerable rawJSON property into an ordinary object, losing the original object's special JSON serialization behavior.

The helper is used for argument and result materialization in packages/core/tools/src/index.ts. Preserving integer tokens during parsing alone would therefore be insufficient if the proposed representation subsequently goes through this snapshot path.

Related discussion: #6002 reports tool-argument rounding in JSON.parse. The current parser still rounds 9007199254740993 to 9007199254740992. The snapshot issue above is a separate failure with an already-exact input. It was initially noted in a comment there and is being moved here for independent tracking.

Exact-integer support and a possible plugin

The immediate snapshot defect can be addressed independently of a broader exact-number feature. For that broader feature, a small, opt-in plugin or tool-author helper could provide an explicit exact-integer representation at tool boundaries. A schema-declared decimal string is one possible representation; it preserves digits without requiring a JavaScript number.

Such a plugin must operate before information is lost. Ordinary execution hooks receive parsed arguments, so converting an already-rounded number to a string or BigInt cannot recover its original digits. A plugin should not claim to transparently repair all existing tools.

Useful acceptance coverage would include:

• Tool input, result snapshots, persisted history, and replay.
• Nested values, positive and negative integers, safe integers, and strings containing digits.
• Ordinary approximate numbers retaining their declared semantics; no global conversion of all large numbers to strings.
• Plain {"rawJSON":"..."} objects remaining ordinary objects, distinct from genuine raw-JSON values.
• Explicit unsupported-value errors where exact transport is unavailable.

Feedback on the intended raw-JSON contract and the appropriate extension boundary for opt-in exact integers would help keep a community plugin small and compatible with DSH.

Validation scope

I executed the current upstream value helpers directly and reproduced five raw-JSON cases: positive/negative large integers, a small integer, a boolean, and a string. Ordinary safe numbers, an approximate 1e30, decimal strings, plain rawJSON-named objects, and text content retain their serialized values; native BigInt is explicitly rejected. I also checked the extracted unchanged argument-parser body.

A full current-version agent/provider/session test was not run. The dispatch/history/replay checks above are proposed acceptance coverage, not claimed completed validation. The plugin is a proposal, not an implemented or published artifact.

[PerryLink]

这条要能被修，关键是说清"快照"应当保真到什么程度

1. 你指出的矛盾是实在的

你写：lossless-JSON 校验器接受真正的 JSON.rawJSON，但快照助手把它变成普通对象 ⇒ 一个 JSON number 可以变成 JSON object，而校验还通过了。

⇒ 这属于"校验与变换的口径不一致"：校验认为它合法，变换却改了它的种类。这类问题比单纯的四舍五入更难发现，因为它不改变"是否合法"，只改变"它是什么"——你的定位是对的。

2. 建议把诉求落在"契约"上，而不是某个函数

建议这样写（可判定）：

快照（snapshot）应当是保真的：若它接受 JSON.rawJSON，就必须原样保留其种类与字面量；否则应在校验阶段就拒绝它，而不是在变换阶段悄悄降级为普通对象。

两条择一是关键：现在的组合（校验放行 + 变换降级）是唯一不可接受的那一种——它让"校验通过"失去意义。把这一句写出来，维护者不必猜你要哪种语义。

3. 请补三样（能让它落到一行）

1. 快照助手的位置（源码路径 + 符号名；若只在产物里，请给产物路径与版本）；
2. 最小复现：一个含 JSON.rawJSON 的输入 ⇒ 校验结果 + 快照结果（两个值并排）；
3. 版本基线：⚠️ 当前最新是 0.2.1-alpha.1（latest/next = 0.2.0-rc.2）——请确认该助手在新版是否仍如此。

4. 为什么值得独立跟踪（你的理由我认同）

你写"这值得独立于 input-number rounding 单独跟踪"——对：四舍五入是精度问题，而这是类型问题。前者可以靠"提高精度"缓解，后者会让下游拿到错误类型（例如把整数当对象解析）。建议把这一层区分写进正文的第一段，否则容易被合并进那条更显眼的精度讨论里而被稀释。

5. 你的用例很有说服力，建议保留

"AI4S 涉及范畴论、需要精确整数系数"——给出真实用例（而不是抽象地谈 lossless），是这类"类型保真"报告最缺的东西：它说明了为什么"变成对象"是不可接受的。请保留，并补一句"该对象在下游会被怎样误用"（例如被当作结构体解析），影响面就完整了。

一条边界

我没有核对 lossless-JSON 的实现（你引的是行为，不是行号）。上面是按你的描述给出的契约级定位——补上第 3 节三样之后，这条就能落到"改校验"或"改变换"这一个选择上。

[TanTsiChen]

I've published an opt-in tool-side implementation: dsh-exact-integers (MIT), with a separate plugin showcase discussion.

Exact-integer fields are declared as canonical decimal strings in tool schemas, decoded to bigint inside handlers, and encoded back to strings before DSH snapshots the results. This supports arbitrary-precision finite integers, subject to runtime resources and optional configured limits. It does not patch DSH's snapshot implementation or recover values that have already been rounded to number.

To answer the request above for a minimal reproduction, I verified the following with the published @deepseek-ai/dsh-util-values@0.2.1-alpha.1 package on Node 22.23.2. The relevant entry points are isJsonValue and snapshotJsonValue, exported from that package's lib/index.js:

import {
  isJsonValue,
  snapshotJsonValue,
} from '@deepseek-ai/dsh-util-values';

const raw = JSON.rawJSON(((1n << 80n) + 1n).toString());
const copy = snapshotJsonValue(raw);

console.log(isJsonValue(raw));       // true
console.log(JSON.isRawJSON(raw));    // true
console.log(JSON.isRawJSON(copy));   // false
console.log(JSON.stringify(raw));    // 1208925819614629174706177
console.log(JSON.stringify(copy));   // {"rawJSON":"1208925819614629174706177"}

The public plugin suite has 18 synthetic tests, including actual DSH tool execution, streamed arguments from a scripted provider, plain/compressed JSONL persistence, replay and resume. CI passes on Node 22.19 and 24; these tests do not call a live model.

The plugin provides an explicit string-based transport contract. The core snapshot-contract issue remains separate: accepting a raw JSON value and copying it into a plain object changes its serialized JSON kind. Preserving the supported kind and literal, or explicitly rejecting unsupported raw JSON values, would make that boundary predictable.

[PerryLink]

你给的符号我核到了——而且它正是工具结果那条路，所以核心问题应当继续挂着

1. 核实结果（HEAD = dsh-v0.2.1-alpha.1）

snapshotJsonValue 在仓库里存在，并且被工具层消费：

packages/core/session/src/index.ts          ← 定义/导出所在
packages/core/tools/src/index.ts            ← 工具层使用
packages/core/tools/src/ptc.ts              ← PTC 路径也使用
packages/core/session/tests/json.spec.ts
packages/core/session/README.md / README.zh.md

⇒ 两点值得注意：

1. 它就是你说的那个快照函数（你在 @deepseek-ai/dsh-util-values 的 lib/index.js 里读到 isJsonValue / snapshotJsonValue；仓库侧对应这里）；
2. ⭐ core/tools 是它的消费方 ⇒ 工具结果恰好就是受影响的那条路——所以你的用例（工具 schema / 工具结果里的精确整数）正落在刀刃上，这不是巧合。

2. ⇒ 但请把"变通方案"与"核心修复"分开写（这一点很重要）

你的 dsh-exact-integers 是约定式的：把精确整数字段声明为规范十进制字符串、在 handler 内解码成 bigint、在 DSH 快照之前再编码回字符串。⇒ 这确实绕过了快照，但：

• 它只对"由工具作者控制的 schema"有效——别人写的工具只要不遵守这个约定，照样会被降级；
• 它不修补快照实现（你自己也写明了），也无法恢复已被舍入成 number 的值。

⇒ 所以核心缺陷应当继续挂着，而不是因为有了插件就关闭。建议你在帖子里明确写这两句话（我很认同你已写出的那半句"does not patch DSH's snapshot implementation"）——它能让维护者不把这条当作已解决。

3. 核心修复的形态（建议照这个措辞）

快照要么保真（保留 JSON.rawJSON 的种类与字面量），要么在校验阶段就拒绝它；"校验放行 + 变换降级"是唯一不可接受的那一种——它让"校验通过"失去意义。

"二选一"是关键：现在的组合恰好落在两者之外。把这一句写进正文，维护者不必猜你要哪种语义。

4. 请补一样（能让修复落到具体一行）

你在 core/tools 里读到的调用点（index.ts / ptc.ts 里调用 snapshotJsonValue 的那一处，源码或产物行号均可）⇒ 有了它，这条就从"快照助手有问题"变成"某一个调用点需要决定保真还是拒绝"，可修性完全不同。

5. 一点肯定

你给出了包名、版本（0.2.1-alpha.1）、Node 版本、以及导出符号，并附上可跑的验证片段。⇒ 这是这类"类型保真"报告里最缺的东西（多数只给现象）。请把这些保留在正文——它们是你这条能被接手的原因。

[TanTsiChen]

补充逐项核验结果。基线为 dsh-v0.2.1-alpha.1 对应的提交 5badb15009ae1756c3afe0ae0cef1faafc290ccc，以及已发布的 @deepseek-ai/dsh-util-values / @deepseek-ai/dsh-tools@0.2.1-alpha.1，运行环境为 Node 22.23.2。

源码定位上有一处需要校正：snapshotJsonValue 定义在 packages/util/values/src/index.ts:172；core/session/src/index.ts:12 是导入方。工具结果路径是 createSuccessResult():1833 → snapshotToolValue():562 → snapshotJsonValue，随后才进行输出 schema 校验和渲染。PTC 中的 190、197 行则处理绑定调用的参数及其日志副本。

我用独立合成数据验证了真实工具运行时，影响范围需要区分：

返回值与输出 schema	实测结果
JSON.rawJSON('7')，输出声明为整数	返回 INVALID_TOOL_OUTPUT
{ value: JSON.rawJSON('7') }，输出为允许未知属性的对象	调用成功，但返回值变为 { value: { rawJSON: '7' } }
普通整数、十进制字符串、普通 rawJSON 属性对象，配合相应 schema	正常保留

因此，工具层确实受影响，但不能概括成所有未接入插件的工具都会降级，也不能把 isJsonValue() 返回 true 等同于所有后续校验通过。小整数 7 也触发此问题，说明它独立于大整数舍入。上述 PTC 结论来自源码调用关系；这次没有执行完整 PTC 沙箱路径。

插件的准确描述是：先把精确整数字段编码为字符串，再正常经过 DSH 的快照与冻结流程。它需要显式接入，不修改共享快照函数，也不恢复已经舍入的 number。本次重跑的 18 项公开测试全部通过，目前这些发现不要求修改插件的整数传输协议。

这条核心问题仍应单独跟踪。我认同接受与变换的契约需要一致：明确拒绝不支持的 raw JSON，或提供一致的保真支持。具体修复不能仅凭一个调用点确定；尤其是现有整数 schema 在快照前也不接受 raw JSON 对象，仅保留其特殊身份并不自动完成工具层的大整数支持。若选择支持，还需要核验 schema、持久化和回放的一致性。