fix(objectql): 悬空引用巡检为「预算没轮到」的对象建诚实桶 unscannedObjects (#5718)

[os-zhuang]

Fixes #5718

问题

packages/objectql/src/integrity/dangling-reference-audit.ts 主循环在
report.scanned >= maxRows(默认 DEFAULT_MAX_ROWS = 5_000)时直接 break,
其后所有对象既没被读、也没进任何桶。它们的 dangling: [] 与「真的读过且
干净」的表在报告里完全无法区分 —— 而这正是本文件所有诚实桶存在的理由:

已有桶	覆盖的不完整路径
truncatedObjects	某张表内部的行预算用完,只看了样本
unreadableObjects	试着读了,数据源不给
aborted(#4747)	运行被叫停

「整张表没轮到」是唯一没有对应桶的一条 —— 模块头注释原话:Together they are
what stops 0 dangling from ever being read as everything is fine。

改动

新增 unscannedObjects: string[],在主循环每一处提前退出前把未轮到的对象名记下:

• 按扫描顺序(feat(objectql): 悬空引用巡检纳入 readonly 溯源族,单独分桶为 provenance (#4743 事实二) #5719 落地的 prioritise 三档:安全面 → 业务引用 → 仅溯源),
  所以调用方可以把它直接回喂 options.objects 续跑,补齐画面。
• 类型 optional,运行时永远赋值 —— 与 aborted、哨兵拆掉之后：#4441 的 readonly 收窄与 #4551 的巡检跳过还需要吗？——注释已过期，跳过范围值得收窄 #4743 的 provenance
  同一契约:手写 report 字面量(测试替身)仍可编译;而本模块产出的每一份报告
  都显式写入,走到底就是 [],永不缺席。因此 undefined 不需要被猜,它只可能
  意味着「旧报告形状」,绝不会意味着「完整」。
• 两类刻意不入桶:①无任何引用字段的对象 —— prioritise 在循环前就丢弃了
  它们,它们不出现在 dangling 里是被证明的而非假设的;②调用方用
  options.objects 排除的对象 —— 那是调用方自己的收窄,把它报回去等于把调用方
  的选择说成巡检的漏看。
• 不单独抬告警,与 truncatedObjects 同族:大库每次健康运行都会耗尽预算,
  常亮告警就是 每个 os migrate 子命令关停时，悬空引用巡检都会把 sys_metadata / sys_view_definition 报成 unreadableObjects（连接已关闭） #4747 的坏警报,会把读者训练得跳过那一行。它在告警载荷里逐项
  带出(对象量级而非行量级,读者要拿名字去续跑),并始终留在返回的报告里。
• 被叫停的运行同样填桶:否则 unscannedObjects: [] 与 aborted: true 并排
  会读成「早停了但什么都没漏」。唯一边界是在枚举注册表之前就被叫停 —— 那时
  没有名单可给,由 aborted 承担,已用一条测试把这个边界钉住而不是留给下一个人踩。

与 #5719 的关系:#4743 不是成因,只是把这条路径抬到「容易踩到」—— 溯源族入巡检
后几乎每个对象都有可审计字段,同样的预算摊到多得多的表上,提前 break 的概率显著
上升。三档 prioritise 决定谁拿到有限预算,本桶报告谁一点也没拿到,两件
事独立:扫描顺序无法让有界运行变完整,只有说出漏了什么才能让它诚实。

反向验证(方向在跑之前就预测好了)

预测:删掉预算处的 fileUnscanned(i) → 依赖预算停的用例转红;不依赖它的用例
(显式 []、被叫停、枚举前叫停)保持绿。实测完全一致:

× the objects behind the stop are listed, in the order the run would have read them
× an object with NO reference field is not listed — its silence was already proven
× an object the CALLER excluded is not listed — that narrowing is not the audit missing it
× a zero budget reads nothing and names EVERYTHING — the whole report is "not looked at"
× a truncated run and an unscanned run are DIFFERENT reports
× rides along in the warning payload, and does NOT raise the line on its own
AssertionError: expected [] to deeply equal [ 'showcase_task', 'showcase_note' ]
Tests  6 failed | 3 passed | 29 skipped (38)

第二处限位单独验:只删 abort 分支的 fileUnscanned(i) →
a called-off run names what it never reached too 单独转红
(expected [] to deeply equal [ 'showcase_task', 'showcase_note' ]),其余保持绿。

注意这里断言的选择是关键:只断言 dangling 或 scanned 的测试在旧的静默
break 下同样是绿的 —— 发现数一个都不变。名字本身才是被测行为。

测试证据

pnpm --filter @objectstack/objectql exec vitest run \
  src/integrity/dangling-reference-audit.test.ts \
  src/engine-dangling-reference-audit.test.ts --maxWorkers=2
 Test Files  2 passed (2)
      Tests  45 passed (45)

# 新增 [#5718] 块 10 例全绿
 Tests  10 passed | 29 skipped (39)

pnpm --filter @objectstack/objectql test        # 全包
 Test Files  123 passed (123)
      Tests  2031 passed (2031)

pnpm --filter @objectstack/objectql typecheck   # tsc --noEmit,无输出即通过

门禁:

check:nul-bytes                OK (5641 tracked text files, no raw control bytes)
check:query-options-erasure    ratchet holds, baseline verified against 5e3c83b
check:engine-double-contract   OK — 27 pinned, 65 DEBT, 1 exempt
check:type-check-coverage      OK — 63/78 packages
check:durability-log-level     OK — 24 seams, all loud
eslint (两个改动文件, --no-inline-config)  clean

改动面

• packages/objectql/src/integrity/dangling-reference-audit.ts(主循环 + 报告类型)
• packages/objectql/src/integrity/dangling-reference-audit.test.ts(新增 [#5718] 块 10 例)
• .changeset/dangling-audit-unscanned-bucket.md(patch)

未碰 engine.ts / lifecycle-service.ts(有其他 dev 在飞),未碰
content/docs/releases/。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 4:05am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

13 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.