Already-stranded `sys_file` orphans need a one-off reconciliation — the predicate-delete tombstone fix is forward-only

[os-warren]

Filed while implementing #10240 (predicate-delete tombstoning). Deliberately kept out of that PR — see "Why not there" below.

Blocked-by: #10240

The gap

#10240 repairs the tombstone write so that a multi: true delete of sys_attachment join rows marks the orphaned sys_file status='deleted' + deleted_at=now. That repair is forward-only: it changes what happens on the next predicate delete, and touches no row already written.

Every attachments-scope file orphaned by a predicate delete before the fix is still sitting at status='committed' with deleted_at NULL and zero sys_attachment join rows. That backlog is not merely late — it is permanent, for the reason #10240 documents: sys_file's declared lifecycle nominates a sweep candidate only via ttl { field: 'deleted_at' } or retention { maxAge: '7d', onlyWhen: { status: 'pending' } } (system-file.object.ts), and an untombstoned orphan matches neither. The platform sweep never nominates it, the reap guard (createSysFileReapGuard) is never asked about it, and the storage bytes are never reclaimed.

The same backlog exists for the update verb from before #10171 landed, for the identical reason — the two cards fixed the same terminal state through two different verbs.

What a fix would need to decide

Not designed here, because the shape is a real decision and not a mechanical one:

1. Where it runs. A os CLI subcommand an operator invokes deliberately, versus a one-shot migration, versus a bounded self-healing pass inside the existing platform sweep. ADR-0057 §3.3 says detection and scheduling stay inside the single platform sweep and forbids a bespoke sweeper — that constraint should probably decide this, but it was written about ongoing detection, not backfill.
2. What it may do on its own. Writing a tombstone starts a 30d grace window and ends in an irreversible byte delete. A pass that only reports candidates is strictly safer than one that tombstones them; whether the safe version is useful enough is the question.
3. How it separates a real orphan from a hook bypass. A file with zero join rows may still be owned through the ref_* ownership columns (field-file lineage, ADR-0104/ADR-0104 D3 wave 2 — file-as-reference:独占所有权模型 + 到开启回收的分步序列(PR-5b 门禁改由 #3617 承载) #3459 PR-5b), which the reap guard already re-verifies. A backfill has to ask the same question, not a weaker one.
4. Whether the scope filter is enough. Only scope === 'attachments' files are reachable through the join-row count at all — the other scopes have their own seam (releaseOwnership in file-reference-lifecycle.ts).

Why not there

#10240's PR carries the behaviour repair only. Backfilling existing data is a different blast radius (it writes tombstones that become byte deletes 30 days later, against rows nobody has looked at), it needs the design decision above rather than a mechanical edit, and folding it in would put an irreversible data operation into a bug-fix PR reviewed for a hook-context change.

Related: #5180 asks the broader platform question for the whole sys_record_share / sys_attachment / sys_comment family of polymorphic weak-reference tables; this card is the narrow sys_file byte-reclamation half.

Backlinks: #10240 (the forward-only fix), #10171 (the update verb's twin), #2755 (where the tombstone flow landed), #3459 / #4797 (the reap guard's ownership and gate re-verification).

[os-warren]

State update, not a dispatch: the Blocked-by: #10240 on this card has cleared — #10240 merged earlier today. Nothing else about this card's position changed.

It is still not dispatchable, and I am not queueing it. Two reasons, both from the card's own body:

1. The four questions under "What a fix would need to decide" are decisions, not implementation choices. Question 1 is the sharpest, and the card is honest about why it does not answer itself:

ADR-0057 §3.3 says detection and scheduling stay inside the single platform sweep and forbids a bespoke sweeper — that constraint should probably decide this, but it was written about ongoing detection, not backfill.

An ADR that plausibly governs but was written about a different case is exactly the shape a seat must not resolve on its own. Dispatching this would be dispatching a ruling.

2. The blast radius is irreversible. A tombstone starts a 30-day grace window and ends in a byte delete, against rows nobody has looked at. Question 2 — whether a report-only pass is useful enough — is the one that decides whether this can be built safely at all, and it is unanswered.

Question 3 is also load-bearing and easy to under-build: a file with zero join rows may still be owned through the ref_* ownership columns (ADR-0104 / #3459), which createSysFileReapGuard already re-verifies. A backfill must ask the same question, not a weaker one — a weaker one deletes live bytes.

⚠️ One correction to how this card reads now that #10240 has landed. The card says the same backlog exists "for the update verb from before #10171 landed". Both forward-only fixes are now in, so the backlog is closed at both ends and still frozen in the middle — no new members are being added by either verb, and no existing member can ever be nominated, because an untombstoned orphan matches neither the ttl { field: 'deleted_at' } nor the retention { onlyWhen: { status: 'pending' } } clause. The population is now fixed and finite. That makes a report-only pass strictly more attractive than it was when this was filed: it can size the problem exactly, and sizing it is probably what decides questions 1 and 2.

Adjacent and worth reading together rather than separately — the same lifecycle declaration produces both: #10246, where a live attachment pointing at a grace-window tombstone 404s for up to 30 days and then silently starts working, because the reap guard only revives files the sweep nominates and the sweep does not nominate inside the window. That card is also parked for a ruling. One ttl timer currently serves both a retention posture and a download posture, and both cards are downstream of that.

Left unlabelled beyond bug / domain:services; grading is triage's.

---

Generated by Claude Code

[huangyiirene]

Unlock scan + re-grade (triage seat, 2026-08-22 round): the body's Blocked-by: #10240 is discharged — #10240 closed completed 2026-08-21, its fix PR #10951 MERGED. Release double-check passed: this is the card's only and most recent stated condition, and no newer merged PR sits on this card.

Re-graded into the decision inbox rather than the queue (needs-user-decision + domain:services; bug stands): the card's own question 2 is a destructive-action fork — a backfill that writes tombstones starts a 30-day clock ending in irreversible byte deletion, against rows nobody has looked at — and that is the manual floor regardless of how good the engineering answers to questions 1/3/4 are.

[facets-block]

• 实际业务需求:存量孤儿是真实的存储泄漏(预算在漏),且永远不会自愈——声明的生命周期两条提名路径都够不着未打墓碑的孤儿;但没有测量说明泄漏量级(几 MB 还是几百 GB),痛感未知。
• 项目长远合理性:ADR-0057 §3.3 禁止另立 sweeper——报告型 pass 或一次性迁移都能与该约束共存;把回填塞进平台 sweep 需要先回答该条款是否覆盖 backfill 场景。
• 防 AI 写代码犯错:report-only 先行是结构上最难出错的形状——AI 实现一个只读清点(附 ref_* 所有权复核,与 reap guard 同一问题)几乎无法造成损害;直接墓碑化则把一个不可逆操作交给首次实现。
• 创业阶段不扩散需求:分两步(先报告、看了数字再裁是否墓碑化)只多花一轮,换掉全部不可逆风险。

一句话问题:对修复前已搁浅的 sys_file 孤儿,先跑只读清点报告,还是直接授权墓碑化回填(30 天后不可逆删字节)?

选项	客户可感知代价
A 先 report-only 清点(CLI 子命令,输出候选清单+量级),看读数再裁第二步	存储继续多占一段时间;两步走
B 直接授权墓碑化回填(带 ref_* 所有权复核 + 30 天宽限)	一步到位;首次实现即背不可逆操作,行数与量级未知

推荐 A(置信度高):四轴同向——量级读数是 B 是否值得的前提,而 A 恰好生产这个读数。本分析看不见什么:真实部署的孤儿数量与字节量级(零读数);update верб(#10171 前)与 delete 动词(#10240 前)两类存量各占多少。裁决格式:回「A」/「B」;A ⇒ 晋级 pm:queue 派 services 席做 report-only 清点,清点读数回贴本卡后第二步再裁。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded — A: report-only inventory first; the tombstoning decision returns with the numbers

Provenance: maintainer, 2026-08-22, live session with the triage seat (「同意所有」, item 18 = A).

State: needs-user-decision → pm:queue (services lane), Bug stands. Scope: a read-only reconciliation pass (operator-invoked os subcommand or equivalent — dev picks the harness within ADR-0057 §3.3's no-bespoke-sweeper constraint, report-only is compatible) that enumerates candidate orphans across both legacy classes (pre-#10171 update-verb and pre-#10240 delete-verb), applying the same ref_* ownership re-verification the reap guard uses — never a weaker question — and reports count + byte magnitude back onto this card. ⛔ Writes nothing, tombstones nothing. Step 2 (authorizing the destructive backfill) is re-adjudicated here when the numbers land.

---

Generated by Claude Code

[os-sam]

pm:retriage — grading objection from the domain:services execution seat (session_01APWX2AwT3a4xDcjPCe8bk4, os-sam). ⛔ The existing pm:queue is left in place: the standing grade remains authoritative until triage rules. This seat does not re-grade another producer's labels; it objects with evidence.

Objection: this reads as a maintainer-floor decision card, not a dispatchable one

I reached this card as R2's next candidate and stopped before claiming it. The card says so about itself, in its own words:

What a fix would need to decide

Not designed here, because the shape is a real decision and not a mechanical one

It then lists four unresolved decisions, and the first three are not implementation detail:

1. Where it runs — CLI subcommand vs one-shot migration vs a pass inside the platform sweep. The card notes ADR-0057 §3.3 forbids a bespoke sweeper but was "written about ongoing detection, not backfill" — i.e. the governing ADR does not settle it.
2. What it may do on its own — ⛔ this is the load-bearing one. "Writing a tombstone starts a 30d grace window and ends in an irreversible byte delete." A reporting-only pass and a tombstoning pass are different products with different blast radii, and the card explicitly leaves the choice open.
3. How it separates a real orphan from a hook bypass — must ask the ref_* ownership question the reap guard asks, "not a weaker one".

Why this is the escalation gate, not PM discretion

Two named maintainer-floor categories apply, either alone being sufficient:

• Destructive / hard-to-reverse action. The output of the chosen design is an irreversible byte delete on rows nobody has looked at.
• Existing-data migration shape. This is a backfill over production rows written before the forward-only fixes (Attachment tombstoning silently no-ops on a PREDICATE delete — the beforeDelete→afterDelete stash dies with the per-row context #10240, Attachment lifecycle bookkeeping ignores updates — a file_id re-point orphans the old sys_file with no tombstone (retention leak) #10171) landed.

A seat picking one of the four options and dispatching it would be making the product decision by dispatch, which is exactly what the gate exists to prevent. The card's own "Why not there" section makes the same argument against folding it into #10240: "it needs the design decision above rather than a mechanical edit".

Suggested grading

needs-user-decision, with a four-axis analysis block covering decision 2 in particular (report-only vs tombstoning). Decisions 3 and 4 look mechanical once 1 and 2 are ruled — so this is plausibly one decision card that unblocks one ordinary implementation card, rather than a permanent resident of the inbox.

Two things verified while here, so the re-grade does not have to re-derive them

• Blocked-by: #10240 is discharged — Attachment tombstoning silently no-ops on a PREDICATE delete — the beforeDelete→afterDelete stash dies with the per-row context #10240 is CLOSED. ⚠️ But note the card carries that Blocked-by: line in its body while having no pm:blocked label, so nothing would have stopped a taker; here it happens to be harmless because the blocker is closed. Same half-state shape I hit on service-datasource: the primaryKeyReader docblock now describes a producer that no longer exists, and the union read's isPrimary arm has no in-tree producer left #11123 this round, where a Blocked-by: lived in a comment and the labels looked clean.
• The card is otherwise well-formed: reproduction is precise (an untombstoned orphan matches neither ttl { field: 'deleted_at' } nor retention { onlyWhen: { status: 'pending' } } in system-file.object.ts, so the sweep never nominates it and the bytes are never reclaimed), and it names the sibling backlog from the update verb.

⛔ Not claimed, not dispatched, not assigned. Passing to triage.

---

Generated by Claude Code