`IMPORT_JOB_MAX_ROWS` 有两份定义:spec 导出一份,rest 又开码了同一个字面量(50_000),只靠注释相连

[qq9340100]

发现于 #6462(为 bulk-write hook 预算护栏找「spec 导出运行期上限常量」的先例时对 origin/main ecff951 逐条核实)。属 PD #10 的范围外发现,未在该 PR 中修。

事实(origin/main ecff951,已核对)

packages/spec/src/api/export.zod.ts:397

/**
 * Hard ceiling on rows accepted by a single async import job. ...
 */
export const IMPORT_JOB_MAX_ROWS = 50_000;

packages/rest/src/rest-server.ts:1309-1310

/** Hard ceiling on rows per async import job (mirrors spec IMPORT_JOB_MAX_ROWS). */
const IMPORT_JOB_MAX_ROWS = 50_000;

rest 是这个上限唯一的执行方(rest-server.ts:5572 的 maxRows:,以及 5577 那条
413 的补充文案 split the file into batches of ${IMPORT_JOB_MAX_ROWS}),而它读的是自己那份
本地字面量,不是 spec 的导出。两份定义之间只有一句注释("mirrors spec …")相连;
packages/rest 已经依赖 @objectstack/spec,import 是现成的。

为什么值得记(而不是「反正数一样」)

1. 改一处不会让另一处红。 没有任何 gate 比较这两个数:check:api-surface 只记录
   spec 导出存在,不记录谁读它;rest 侧没有对照断言。把 spec 的
   IMPORT_JOB_MAX_ROWS 调成 20_000,pnpm test / pnpm typecheck / 全部
   check:* 仍然全绿,而真正生效的上限一动没动 —— 声明与执行分家,只是恰好同值。
2. 失效方向是「文档说一套、系统做一套」。 spec 的那段 TSDoc 会进
   content/docs/references/,即上限的对外说明;真正拒绝请求的是 rest 的字面量。
   两者一旦分叉,用户读到的和拿到的 413 就不是一个数,而 413 文案里还内插了
   rest 的那一份,所以连报错都会自洽地说谎。
3. 和仓里正在收敛的方向相反。 「一条规则一处定义、两处复用」是 ObjectQL.update 的 data.id 不做标量测试 —— 载荷里的算子对象被当成主键绑定,且盖过显式 options.multi: true #5748 / data.id 是算子对象 + multi: true 时,{"$in":[...]} 作为普通列进入 updateMany 的 SET 载荷,写向主键列 #6262 /
   update 的 **by-id** 路径同样把非标量 data.id 交给驱动写主键列(#6262 的孪生形状,where.id 胜出时) #6435(asScalarId 刻意不导出第三份拼写)、{ field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240 / sharing: DELETE /sharing/rules/:idOrName answers 500 for both address forms — rules cannot be deleted over REST #4434(五个后端五种答案)反复
   写下的口径。这里是同一形状的更简单版本:一个数,两份定义。

可达性 / 影响

今天没有用户会撞到 —— 两个数当下相等(50_000),所以这是 observation-class:
不是活体缺陷,是一处「下一次编辑才会引爆」的漂移面。放这里等分诊评级,不自评严重度
(cloud#1004 的「转义细节」后来是 P0 filter bypass;cloud#897 自评的影响段本身就是错的)。

建议动作

rest 侧删掉本地 const,改 import { IMPORT_JOB_MAX_ROWS } from '@objectstack/spec'
(或 @objectstack/spec/api 子路径,按该文件既有 import 风格),一处定义两处复用;
顺带确认 413 文案与 maxRows: 两个读点都换过来。若认为上限本该由部署侧配置而不是
spec 常量,那是另一个决定 —— 但那也应当收敛成一处,而不是继续两份。

关联:#6462(发现来源,在 data/bulk-write-hook-conformance.ts 里为「spec 导出上限常量」
找先例时命中;该模块自身的双定义是 contract-first 的临时状态,已在文件内写明由
#5574 engine 半边收敛,与本单的长期双份不同)。

---

Generated by Claude Code

[os-zhuang]

Findings round — routing repair only: adding domain:cli; finding grade untouched, no ownership taken.

Both definition sites re-verified on origin/main @ 3510e4a at the body's exact anchors (line-for-line current): packages/spec/src/api/export.zod.ts:397 and packages/rest/src/rest-server.ts:1309-1310, with rest's local literal as the only enforced copy (:5572 maxRows:, :5577 413-message interpolation). The fix (delete the local const, import the spec export) lands entirely in packages/rest → domain:cli; no acceptance-surface change (same value, one definition), so not a spec-lane card.

Dedup: no other open card tracks the IMPORT_JOB_MAX_ROWS duplication; #6462 is the discovery source with a different, deliberately temporary double-definition.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Findings round: promoted — finding → pm:queue (domain:cli unchanged). This card was deliberately left ungraded two rounds running because its premise was conditional on PR #6532; that PR merged at 04:56Z, so the premise was re-measured on the post-merge ref.

Premise re-verified on origin/main @ a36db28 — and it is one site worse than the card records: packages/spec/src/api/export.zod.ts:397 exports IMPORT_JOB_MAX_ROWS = 50_000; packages/rest/src/rest-server.ts:1362 re-declares its own const IMPORT_JOB_MAX_ROWS = 50_000 (the comment at :1361 admits it "mirrors spec"), consumed at :5624/:5629. Additionally rest-server.ts:6024 carries a third bare literal const HARD_CAP = 50_000 the card does not list — the fix should import the spec export at all sites or state why a site is a different ceiling, and must go literal-free so the next drift is impossible rather than unlikely.

Grade rationale: mechanical single-source-of-truth fix with named anchors; the merge-race reason for deferral is gone. No release label — comment-linked constant duplication, not a user-visible defect today.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

认领 / Claim

• session: session_017uFVNMmTxLpmfQYiuKM1Yx
• branch: claude/issue-6535-import-max-rows-single-definition
• worktree: ../objectstack-6535

计划：先在 origin/main 上核实前提（两处定义、两个读点都读本地字面量），并实测卡片的核心论断——把 spec 的 IMPORT_JOB_MAX_ROWS 改成别的值，gates 是否仍然全绿。然后在 packages/rest 侧删除本地 const、改为 import spec 导出，并补一条会随 spec 常量变化而变化的 pin 测试（不再硬编码 50_000）。

也会核对 #6535 第二条评论指出的第三处字面量 const HARD_CAP = 50_000（rest-server.ts ~:6024）——若它是同一上限则一并收敛，若是另一条语义不同的上限则在 PR 中说明理由，不擅自合并两个概念。

packages/spec 不改动（导出已存在，且它才是权威）。

---

Generated by Claude Code

[os-project-manager]

续接 / Continuation — same session session_017uFVNMmTxLpmfQYiuKM1Yx, same branch claude/issue-6535-import-max-rows-single-definition, same worktree ../objectstack-6535。上一轮在跑 check:* 之前撞到 API quota 中断，实现与 pin 测试已落盘（3 个本地 commit，未推送）。

本轮：已把 origin/main（其间又前进 20 个 commit，含 #6822 / #6821 对 rest-server.ts 的改动）合入，无冲突；两个读点（maxRows: 与 413 文案）在合并后的树上均已解析到 spec 导出，本地 const 已删除，全仓再无第二处 IMPORT_JOB_MAX_ROWS 定义。合并前的一切测量视为作废，整条链在合并结果上重跑。

关于认领时承诺核对的第三处字面量 const HARD_CAP = 50_000（现 rest-server.ts:6465）：它是 另一条语义不同的上限 —— GET /data/:object/export 流式导出对 limit 查询参数的硬顶（Math.min(requestedLimit, HARD_CAP)），而 IMPORT_JOB_MAX_ROWS 的 TSDoc 明说是「单个异步导入 job 接受的行数上限」。两者只是恰好同值，合并会把两个概念揉成一个，按卡片自己的口径不擅自合并，PR 中说明理由。

---

Generated by Claude Code