[objectstack-fleet]

Requested by 田騏 · project thread

Part of #30237
Clause-②: yes (widening)
Metadata-protocol: none
Skills-docs: follow-up #30847

维护者速读

• 改了什么：回收站可以"恢复"了。ObjectQL.restore(entryId) 把一条回收站记录按原 id 写回（主记录先、明细随后），保留创建人和创建时间，不跑新建钩子；删除时被清空的引用在没人改过的前提下重新挂回；汇总字段重算；每行发一个 data.record.restored 事件；成功后这条回收站记录被删掉。spec 只动了您同意的范围：两个事件枚举加 data.record.restored，回收站常量注释和测试钉子翻转；按您 16:53Z 选的 C，新增第四个拒绝码 RESTORE_PARENT_IN_RECYCLE_BIN（码表、错误码台账各一行），ADR-0148 D2 加一条、Consequences 加一句。
• 为什么改：ADR-0148 的第三步（engine: snapshot deletes into the recycle bin, restore under original ids, purge, and the TTL reap (#3146 slice 3) #30237 拆分的 PR 3）。删除进回收站（PR 1）、彻底删除/清空（PR 2）已上线，没有恢复，回收站就只进不出。
• 风险与回滚：恢复要么整条成功要么什么都不写：唯一值被占、母记录已彻底删除、母记录还在回收站、对象已卸载这四种情况一律 409 拒绝，记录留在回收站；其中"母记录还在回收站"会给出母记录所在条目的 id，先恢复它就能再恢复子记录。权限读取要等 PR 4，在那之前非系统调用者一律被安全插件拒绝，所以这个 PR 上线后普通用户还用不到恢复，只有系统上下文能用。回滚就是 revert 本 PR。
• 先看：packages/objectql/src/recycle-bin/restore.ts（judgeRestore 四个拒绝、writeBack 的事务与逐笔撤销）；docs/adr/0148-…md 的 D2 与 Consequences；packages/spec/src/data/recycle-bin.zod.ts 码表；packages/spec/src/api/events.zod.ts 与 realtime.zod.ts（枚举加值）。
• 两分钟验证：pnpm --filter @objectstack/objectql exec vitest run src/recycle-bin/restore.test.ts，应看到 26 个用例全过，含四个 409 和"不跑新建钩子"。
• 需要你做的：本 PR 改了 docs/adr/，属 Tier H：席位用 Fable 复核 spec、ADR 和实现拒绝的代码，ACCEPT 后请您亲手合并或入队。

What changes

ObjectQL.restore(entryId, { context }) (new, packages/objectql/src/recycle-bin/restore.ts; the engine keeps a delegation stub, so the facade gate holds with no new registry row):

• Reads the entry raw through the bin's driver, scoped to the caller's organization, and answers null when no entry is visible or no bin is registered. A malformed entry id is refused 400 VALIDATION_ERROR (param: 'entryId'), as purge(entryId) refuses one.
• Dispatches ONE restore operation on the business object of the entry's master row, with no ast and no id, as purge(entryId) is dispatched.
• Judges before it writes (reads only, as the caller). Each refusal is 409 in the ADR-0112 envelope with object, recordId, field, entryId where they apply, and writes nothing; the entry stays:
  • RESTORE_PACKAGE_UNINSTALLED: an object of the entry is no longer registered;
  • RESTORE_PARENT_PURGED: a row's master-detail parent is neither live, nor a row of this entry, nor held by another entry, or its object is no longer registered (parentObject, parentId);
  • RESTORE_PARENT_IN_RECYCLE_BIN: a row's master-detail parent is not live but is held by another entry, as that entry's master or as a row of its cascade (parentObject, parentId, parentEntryId). The parents that are neither live nor in the entry are collected across every row and field first (each probed once), then answered together: one indexed master lookup per parent object, and for the rest (the cascade-row case, account ← contact ← task: the task deleted alone, then the account) at most ONE walk over the entries the caller can see by key (keysetWalk, pages of 200), each snapshot searched, stopping once every parent is answered. All on the refusal path only; a walk the store cut short throws a store-defect error, not a refusal. Unlike the other three it is not permanent: restoring the parent's entry first lets this one through, which two tests drive end to end. It is answered only after every row has been judged for the three permanent refusals, so it never hides one;
  • RESTORE_UNIQUE_VALUE_TAKEN: a live row holds the id or a unique value (unique: true | 'organization' scoped to the row's own organization, 'global' unscoped) of a snapshotted row. A value the caller cannot see (a global unique across organizations) is caught by the store's own unique constraint at the write, and answered with the same code.
• Writes back in one unit of work: the rows raw through each object's driver, the master first, under their original ids, created_by / created_at as the snapshot holds them, no insert hook; then the re-links; then the entry's removal (last, so a restore that did not land keeps its entry). One transaction when every object involved is stored by the bin's driver; otherwise each write already made is undone when a later one fails, and the split is logged at warn.
• Re-link (ADR-0148 D2, both arities per the feat(spec): declare the recycle-bin surface: the sys_recycle_bin entry contract, the retention hook, the restore refusals, the restored event and two grant keys (ADR-0148) #30577 review should-fix 1) through engine.update with the restore's context, as the delete's set_null clear went: a single-valued field while it still holds no value; a multi-valued one while it no longer holds the member (the member is appended).
• Roll-ups recompute from the rows that are back, one recomputeSummaries call per object; a failure surfaces as SummaryRecomputeError after the rows are back, as on insert.
• Events: one data.record.restored per row, master first, through the engine's own publishDataEvent (credential mask, internal omission and organizationId off the row, as every record event).

Engine shape (hand-over 6690307585, "How PR 2 shaped the engine"):

• OperationContext['operation'] gains 'restore'; ENGINE_OPERATION_VERBS.restore = false, so beforeRestore / afterRestore stay outside the hook namespace and registerHook is not narrowed.
• restore joins WRITE_EPOCH_OPERATIONS.
• The [finding] The bulk AST write path passes opCtx.operation raw, so purge / transfer / restore derive no row scope while update / delete now do (#7665 asymmetry) #7809 pin (engine-middleware-operation-vocabulary.test.ts) holds 9 verbs; restore is a dispatched destructive verb, never with an AST, object-level only.
• plugin-security is untouched: DESTRUCTIVE_OPERATIONS already refuses restore fail-closed for every non-system caller. A new pin in security-plugin.test.ts holds that for the engine's object-level dispatch, for a caller holding every CRUD bit, both super-user bypasses and both new grant keys, with no row read.

Spec (consent records 6709046255, 「A 同意三处（推荐）」, and 6710220841, ruling C 「C 新码,并入 PR 3(推荐)」), Clause-②: yes (widening):

• packages/spec/src/api/events.zod.ts: DataEventType gains 'data.record.restored'; its docblock says four events and names RECORD_RESTORED_EVENT.
• packages/spec/src/api/realtime.zod.ts: RealtimeEventType gains the same value; its docblock lists it.
• packages/spec/src/data/recycle-bin.zod.ts: the "NAMED, NOT YET EMITTED" comment flips to emitted; recycle-bin.zod.test.ts's pin flips to "a member of both enums".
• packages/spec/src/api/events.test.ts: the DataEventType.options equality pin gains the value (seat ruling Q2, recorded on engine: snapshot deletes into the recycle bin, restore under original ids, purge, and the TTL reap (#3146 slice 3) #30237, the mechanical consequence of the consented enum change).
• packages/spec/src/data/recycle-bin.zod.ts: RECYCLE_BIN_RESTORE_REFUSAL_CODES gains parentInRecycleBin: 'RESTORE_PARENT_IN_RECYCLE_BIN'; the doc comment says four codes, the first three permanent for the entry, the fourth clearing once the parent's entry is restored. recycle-bin.zod.test.ts pins four codes.
• packages/spec/src/api/error-code-ledger.zod.ts: the code joins the @objectstack/objectql block (the block's comment says four); error-code-ledger.test.ts pins the four values in order.
• Regenerated: content/docs/references/api/events.mdx, realtime.mdx, error-code-ledger.mdx, automation-api.mdx, contract.mdx (gen:docs). No export added or removed in spec.

ADR (Tier H, ruling 6710220841): docs/adr/0148-…md D2 gains a fourth refusal bullet (the parent is in the bin; dated, citing the ruling record), and Consequences gains one sentence: the fourth refusal is not permanent. The status line, D5's reader table and the rest are untouched.

Acceptance notes

• Parent in the bin (ruling C, 6710220841; replaces the seat's interim Q1 = A): answered by its own code RESTORE_PARENT_IN_RECYCLE_BIN, not RESTORE_PARENT_PURGED. The interim answer is gone with no fallback; an ablation that stamps the interim code back turns the refusal's tests red.
• Known gap: ADR-0148 D5's reader table still lists the refusal codes in words as "unique value taken, parent purged, package uninstalled". That row is outside the ADR hunk ruling 6710220841 consented to, so this PR leaves it (seat, contract review round 1).
• Contract review round 1 (6711252037), fixed in 511372165: a parent held as a cascade row of another entry was answered RESTORE_PARENT_PURGED (must-fix); a parent in the bin could hide a permanent refusal of a later row (should-fix); a parent whose object is unregistered now answers RESTORE_PARENT_PURGED. The refusal codes and 409 stay literal stamps in restore.ts, the form check:error-status-conformance reads (its assignment reader pairs err.code = '...' with the status); a test pins the four codes and 409 by value against RECYCLE_BIN_RESTORE_REFUSAL_CODES / _STATUS.
• Contract review round 2 (6711739005), fixed in 82b042200: the miss path walked the bin once per (row, field); it now walks it at most once per restore, pinned by a test that counts bin reads (3 for five lines under one parent). An unregistered parent object's refusal now says the object no longer exists, rather than "deleted for good".
• A failed restore outside a transaction that had already re-linked a reference publishes two data.record.updated events for that row (the re-link and its undo), since both go through engine.update; a comment in writeBack says so.
• The re-link runs as the restoring caller, as the clear ran as the deleting one. Until PR 4 only the system restores, so nothing can be refused there today; PR 4 decides whether a restorer who may not edit the referencing row re-links it.
• A composite unique index (indexes[].unique) is not probed before the write; the store's constraint catches it at the write and it is answered RESTORE_UNIQUE_VALUE_TAKEN, the unit undone.
• A plain (non master-detail) lookup in a restored row that points at a row deleted since stays as the snapshot holds it; ADR-0148 names no refusal for it.
• Not in this PR: the permission reader (PR 4), the REST doors (PR 5), the Console (ui: the admin recycle-bin page (list, restore, empty) and the 已删除 · 撤销 toast (#3146 slice 4) #30239), the skills text (skills: objectstack-api still teaches that DELETE is unrecoverable and that there is no recycle bin (#30237, ADR-0148) #30847). @objectstack/client's subscribeToRecords still lists created/updated/deleted only (an explicit list, not an exhaustive switch); whether it also subscribes to restored by default is PR 5's / ui: the admin recycle-bin page (list, restore, empty) and the 已删除 · 撤销 toast (#3146 slice 4) #30239's choice. service-knowledge does not re-index a restored record; it listens to created/updated only.
• Dispatch-order conflict, resolved by the rules file: the order asked for @objectstack/spec minor, but the claim declares Metadata-protocol: none, and AGENTS.md step 3 / check-changeset-no-major grade a none change patch. The changeset is patch for both packages.

Tests

All on head 82b042200 (the merge of origin/main 13c6d8f, the ruling-C commit, and the contract-review round 1 and 2 fixes):

• pnpm --filter @objectstack/objectql exec vitest run src/recycle-bin/restore.test.ts: Tests 31 passed (31). Round trip and dispatch shape, created_by / created_at kept, no insert hook, restored events, roll-up recompute, organization scoping, null and bad-id answers, the security refusal and the system path, re-link for both arities (changed since, row gone, the relinkedValue units), and the refusals: RESTORE_PACKAGE_UNINSTALLED; RESTORE_PARENT_PURGED (parent purged; parent object unregistered); RESTORE_PARENT_IN_RECYCLE_BIN (parent the master of another entry; grandchild whose parent is a cascade row of another entry, each refused, then the parent's entry restored, then the row restores); five lines under one parent held as a cascade row answered with 3 bin reads; a permanent refusal (id taken) winning over a parent in the bin; RESTORE_UNIQUE_VALUE_TAKEN (a value, a per-organization value in another organization allowed, the id, and the store's own violation with the undo); the four codes and 409 pinned by value against the spec constants.
• Full @objectstack/objectql suite on 82b042200: Test Files 566 passed (566), Tests 11458 passed (11458).
• On ff9ad72fb (the review fixes touch only restore.ts and its test): full @objectstack/plugin-security Test Files 248 passed, Tests 5821 passed, 45 skipped, with the new pin [#30237] DENIES the engine's object-level restore dispatch fail-closed; full @objectstack/spec Test Files 911 passed, Tests 27487 passed, 1 todo.

Ablations on 82b042200 (scripts/ablation-replace.mjs, each mutation proven on disk, then restored to the HEAD blob with an empty git diff HEAD). Clean run: Tests 31 passed (31). Each mutated run:

Mutation	Result
bin asked once per missing reference, not once for all	1 failed, 30 passed: the bin-read count test (expected 11 to be 3)
bin lookup by master only (no snapshot walk)	2 failed, 29 passed: the grandchild and the read-count tests
first reason wins (in-bin thrown at the reference, not deferred)	1 failed, 30 passed: a permanent refusal wins over RESTORE_PARENT_IN_RECYCLE_BIN
unregistered parent object check off	1 failed, 30 passed: RESTORE_PARENT_PURGED: a parent whose object is no longer registered
purged-before-in-bin check off	1 failed, 30 passed: RESTORE_PARENT_PURGED: a detail whose master was deleted for good
unique-value probe off	1 failed, 30 passed: RESTORE_UNIQUE_VALUE_TAKEN: a live row holds a unique value
id probe off	2 failed, 29 passed: a live row holds the id and the permanent-first test
master-detail parent check off	5 failed, 26 passed: every parent test
interim code stamped back (RESTORE_PARENT_PURGED for the in-bin case)	3 failed, 28 passed: every RESTORE_PARENT_IN_RECYCLE_BIN test
package check off	1 failed, 30 passed: RESTORE_PACKAGE_UNINSTALLED
raw create swapped for the engine's hooked insert (two files: restore.ts plus an insert arrow held on the engine host)	4 failed, 27 passed, among them runs no insert hook (received beforeInsert:account, afterInsert:account, ...)
'restore' removed from plugin-security DESTRUCTIVE_OPERATIONS (vitest run src/security-plugin.test.ts -t 30237, on ff9ad72fb)	1 failed: promise resolved ... instead of rejecting; clean run 1 passed

Verification

On head 82b042200:

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 119 commands, each run and recorded as CMD :: exit N; all 119 exit 0. --ran: 119 derived, 119 run, 0 NOT-MEASURED, 0 UNRUN.
• pnpm --filter @objectstack/objectql run typecheck: exit 0. ESLint on packages/objectql/src/recycle-bin/: exit 0.
• On ff9ad72fb: pnpm lint exit 0; @objectstack/plugin-security and @objectstack/spec typecheck exit 0; a whole-workspace pnpm build (119 tasks) ran before the gate rounds, and @objectstack/objectql was rebuilt for each later head.
• CI check-runs are not cited: this thread does not wait on CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_017ihL2fsWoxB3no3RuuUR8y

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/spec, touching 46 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

54 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b.

⛔ 12 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: recordId (4 routes)
• 2 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 80 pages), master_detail (literal, 41 pages)
• 13 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 63 of 226 client-bound route-ledger rows — the other 163 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 163: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 173 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4c8ff42ffca4c8d4158616c2f4cbc1667bfd44cd — the merge of head 32307090b166c9c1ca73da26fa100ecbf3055b6e into base cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 4c8ff42ffca4c8d4158616c2f4cbc1667bfd44cd && git checkout 4c8ff42ffca4c8d4158616c2f4cbc1667bfd44cd
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b 32307090b166c9c1ca73da26fa100ecbf3055b6e && git checkout -B drift-repro cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b && git merge --no-ff 32307090b166c9c1ca73da26fa100ecbf3055b6e

node scripts/docs-audit/affected-docs.mjs --json cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs cba7d8ae719f22e80ae7b336e4ee3a15d5c3057b → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

Contract review — CONTRACT_REVIEW_TIER

Head-sha: ff9ad72fbf8af10992779250472ad240a1c7e424

Round 1 · 2026-11-07T18:20Z

Scope, per the narrowed rule of 2026-11-07: the spec hunks (events, realtime, recycle-bin with their tests, and the error-code ledger with its test), the regenerated reference pages, ADR-0148, and the code in recycle-bin/restore.ts that implements the refusals and the event. Also the engine wiring (the delegation stub, the operation vocabulary, WRITE_EPOCH_OPERATIONS) and plugin-security's fail-closed restore. This is an independent Fable review; the seat checked its must-fix in the code.

Verdict: CHANGES — one must-fix and one should-fix, both local to restore.ts.

Conforms (checked):

• Consent scope: the spec hunks are exactly records 6709046255 and 6710220841 (two enum members, the comment and pin flips, the fourth code, the ledger entry, the reworded doc comment). The ADR hunk is exactly the D2 bullet and one Consequences sentence.
• All-or-nothing: judgeRestore is read-only and runs before writeBack. writeBack runs in one transaction when every object is on the bin's driver, and compensates write by write otherwise. The entry is deleted last, and the undo is pinned.
• Events: data.record.restored is emitted only after the write-back commits, one per row, master first, with after set to the snapshot row and organizationId taken from the row.
• 409 is set on status and httpStatus; the ledger and RECYCLE_BIN_RESTORE_REFUSAL_CODES agree on four codes. created_by / created_at are kept, no insert hook runs, the D2 re-link covers both arities, and recomputeSummaries runs. restore is in the op union with ENGINE_OPERATION_VERBS.restore = false and is in WRITE_EPOCH_OPERATIONS; plugin-security denies a non-system restore with every bit set. The regenerated pages match the enums.
• The patch level on the spec changeset is right: AGENTS.md Post-Task step 3 says Metadata-protocol: none takes patch, and these are API vocabularies, not authorable keys.

Must-fix — a parent that is in the bin as a DETAIL of another entry is refused as purged. parentEntryOf (restore.ts ~:370–381) looks the parent up only as an entry's master (object_name / record_id). Scenario: account a1 ← contact c1 ← task t1, both links master-detail. Delete t1 (entry E1 = {t1}). Delete a1 (entry E2 = {a1, c1}). Restoring E1 then refuses RESTORE_PARENT_PURGED, which is permanent and says "deleted for good", even though c1 is in E2 and restoring E2 first clears the refusal. That contradicts ADR-0148 D2 ("no longer in the bin and no longer live") and the ruling's RESTORE_PARENT_IN_RECYCLE_BIN. Fix: when the master lookup misses, search the caller-visible entries' snapshot.rows for the parent (paged, the way emptyRecycleBin's fallback pages), and name the holding entry as parentEntryId. Add the grandchild test, with an ablation (master-only lookup ⇒ red).

Should-fix — a transient refusal can hide a permanent one. judgeRestore judges row by row (parent, then id and unique values) and throws on the first hit. Take an entry {c1, whose parent is in the bin; c2, whose id is now taken}. The caller is told to restore the parent first, does so, and only then hears RESTORE_UNIQUE_VALUE_TAKEN. Judge every row's permanent refusals (purged parent, id, unique values, uninstalled package) before any RESTORE_PARENT_IN_RECYCLE_BIN, so the first answer is the one that stands. Pin it with one test.

Nits (optional): the four code strings and the 409 are hard-coded in restore.ts instead of being read from RECYCLE_BIN_RESTORE_REFUSAL_CODES / RECYCLE_BIN_RESTORE_REFUSAL_STATUS, and the test pins only parentInRecycleBin by value. A parent whose object is unregistered falls through to IN_BIN or PURGED, and IN_BIN then names an entry that will itself refuse PACKAGE_UNINSTALLED. The compensating undo of a re-link goes through engine.update, so a failed restore publishes two data.record.updated for the referencing row; a comment saying so would help.

Dev questions, seat calls:

1. The ADR-0148 D5 reader table (~:298) still lists three refusal codes. That line is outside the ruling's ADR hunk, so do not edit it here. Add one Known gap: line to the PR body naming it; the maintainer can extend the consent by one line when merging, or it goes to a docs-only follow-up.
2. The spec changeset stays patch (see above).
3. The attribution link naming the card thread is acceptable.
4. The seat sets pm:awaiting-merge and the assignee at ACCEPT. This PR is Tier H, so a human merges it.

The patch round's delta review is Fable over restore.ts's judgement only.

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

Contract review — delta round 2

Head-sha: 511372165305be3e987c4a68a456ae7461ea331b

Delta review · 2026-11-07T19:04Z

Scope: restore.ts and restore.test.ts since ff9ad72fbf. This is an independent Fable review of judgeRestore and parentEntryOf.

Verdict: both round-1 findings are fixed. One should-fix (cost) remains before ACCEPT.

• The must-fix is fixed. In the grandchild case (a1 ← c1 ← t1, E1 = {t1}, E2 = {a1, c1}), the master lookup misses, the keyset walk finds c1 in E2's snapshot, and the restore refuses RESTORE_PARENT_IN_RECYCLE_BIN with parentEntryId = E2. Once E2 is restored, E1 restores. A test pins this.
• The should-fix is fixed. Every permanent refusal (an uninstalled package for all rows, a purged parent, an id or unique value taken) throws inline, and RESTORE_PARENT_IN_RECYCLE_BIN is answered only after the loop. The mixed-entry test pins it.
• Both bin reads take the caller's buildDriverOptions, so the walk stays inside the caller's organization and no other tenant's entry can be named.
• The truncated-walk path cannot be reached with production drivers: no max is passed, so keysetWalk reports truncated only on a reader defect.

Should-fix — memoize the walk. parentEntryOf runs once per (row, field) on the miss path, and each call walks the whole bin, parsing every entry's snapshot. Take an entry {product p1, order_line l1..l500}, where the orders went earlier as details of their customers' cascades. Restoring it walks the bin up to 500 times before it answers. Cache the result by ${object}\0${id} within one restore, or better, collect the missing parents and resolve them all in one walk. Pin it with one test that counts the bin reads.

Nits (optional): an unregistered parent object answers RESTORE_PARENT_PURGED, whose sentences ("deleted for good", "nor the record of another recycle-bin entry") are then false; reword that case, or answer it as RESTORE_PACKAGE_UNINSTALLED naming the parent object. The truncated walk is a store defect like the unparseable-snapshot path, so a non-refusal error would be more faithful than a warning plus a permanent 409. The developer messages around restore.ts ~:163 and ~:189 still say "the record of another entry", and the detail-of-a-cascade case is now possible too. Skipping entryId in the walk is redundant but harmless.

After that patch, the seat reviews the delta in-seat and then posts ACCEPT. The PR is Tier H, so a human merges it.

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

Contract review — ACCEPT

Head-sha: 82b042200e8060518639c7464fc3f53bc6263ca5

ACCEPT · Tier H (docs/adr) · 2026-11-07T19:47Z

This is the in-seat delta over 511372165305 → 82b042200e, round 3. It reads restore.ts and restore.test.ts only, per the os-dev addendum 6712176747.

• Round 2's should-fix is resolved. judgeRestore now collects every master-detail parent that is neither live nor in the entry, each one once (missingParents). It asks the bin about all of them through parentEntriesOf: one record_id $in read per parent object, then at most one keyset walk for the parents still unanswered, which stops once all are answered. The new pin has five details under one parent that is held as another entry's cascade row, and asserts exactly 3 bin reads. The per-reference ablation reds it, 11 ≠ 3.
• Order of reasons. Permanent reasons still win. The unique and id checks run in the row loop. After that, an unregistered parent object, then a parent that no entry holds, answers RESTORE_PARENT_PURGED. Only when no permanent reason stands does the first missing reference answer RESTORE_PARENT_IN_RECYCLE_BIN with its parentEntryId, which is ruling C. The pins and their ablations (do not judge purged first, throw on the first cause) are in the addendum.
• Unregistered parent object. It stays RESTORE_PARENT_PURGED with a sentence that names the gone object. RESTORE_PACKAGE_UNINSTALLED is the entry's own object, per the ledger text, so this is right.
• Truncated walk. It now throws a coded-less store-defect error carrying entryId, where before it answered purged on a reason it had not established. The seat accepts this without a pin, because a seek-ignoring full page has no honest fixture.
• Seat nit, not owed: a parent that is live is still probed once per referencing row (isLive is skipped only for a key already known missing). That costs a live read, never a bin read, and is outside the should-fix.
• Gates: 119 derived exit 0 with --ran reconciled; objectql 566 files / 11,458 tests; typecheck and eslint 0 (thread report).

Review record for the PR: round 1 Fable 6711252037 (CHANGES), round 2 Fable delta 6711739005 (one should-fix), round 3 in-seat delta (this). The ADR-0148 D5 table stays a Known gap in the PR body.

Landing: Tier H (docs/adr/0148), so a human merges it (os-zhuang or hotlong). It is labelled pm:awaiting-merge and assigned to marchtian. CI on this head was still running at ACCEPT; the human merge waits for green.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 42429362317 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

分类：failure —— 按下面的日志分诊。

失败的 job（日志抽取，best effort）：

• Test Core (6/8) — 失败步骤: Run this shard's tests

  @objectstack/example-todo:test:  FAIL  test/loop-body-iteration.test.ts > #19206 — the loop body runs and binds `currentTask` > ESCALATION: the run reaches `notify_owner` and the notice renders the re
    ↳ 失败原因: @objectstack/example-todo:test: Error: Test timed out in 5000ms.
  @objectstack/example-todo:test:  FAIL  test/overdue-escalation-days-overdue.test.ts > #18584 — the overdue escalation projection carries a day count > every `{{ currentTask.… }}` hole in the escalatio
    ↳ 失败原因: @objectstack/example-todo:test: Error: Test timed out in 5000ms.
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/loop-body-iteration.test.ts — 24h 内已弹出 6 个 PR（feat(objectql): restore a recycle-bin entry under its original ids and emit data.record.restored (#30237 PR 3) #31220、i18n(platform-objects): ship the platform objects, Setup, Studio and Account in French #31233、fix(auth): record an MCP access token as used only after the MCP door admits the call #31247、feat(plugin-auth, plugin-audit): a sign-in the IP allow-list refuses writes one login_failed row, bounded per address #31249、feat(spec): declare the optional ISecurityService.describeEffectiveAccess and its EffectiveAccess answer types #31256、feat(plugin-auth)!: an organization administrator reads their judged client address; the console's retired MFA notices are gone #31258），分属 4 条投机栈 ⇒ 4 次独立命中。汇总 issue：Queue-flake anchor: test/loop-body-iteration.test.ts #31294（已刷新）
• test/overdue-escalation-days-overdue.test.ts — 24h 内已弹出 2 个互相独立的 PR（feat(objectql): restore a recycle-bin entry under its original ids and emit data.record.restored (#30237 PR 3) #31220、feat(spec): declare the optional ISecurityService.describeEffectiveAccess and its EffectiveAccess answer types #31256）。汇总 issue：Queue-flake anchor: test/overdue-escalation-days-overdue.test.ts #31311（新建）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 26 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fsWoxB3no3RuuUR8y

Merge queue dequeue at 00:41Z (CI_FAILURE), read from the queue run 42429362317 on gh-readonly-queue/main/pr-31220-0f254f47… (base main 0f254f4):

• The only red job is Test Core (6/8), step "Run this shard's tests", with the turbo task @objectstack/example-todo#test failing (76 of 77 tasks green). The aggregate Test Core job is red because of it. The failing test's own lines fall outside the last 5000 lines of the job log, which is all this session can read, so the failing case is not named here.
• Reproduced locally on the same tree: origin/main 0f254f4 merged into this PR's head 82b0422 (no conflict). After a pnpm install --frozen-lockfile and a build of @objectstack/example-todo..., pnpm --filter @objectstack/example-todo test passes 4 runs out of 4, each with Test Files 9 passed (9) and Tests 249 passed (249). That count includes test/mcp-actions.test.ts, which test(example-todo): boot the MCP action drive with its Default Organization and run it in the example suite #31230 added to main.
• This PR touches nothing the example-todo suite imports beyond @objectstack/objectql and @objectstack/spec. The PR's own CI on 82b0422 was green, and the main push run at 0f254f4 was green.
• No fix is pushed, because nothing reproduces. The branch is unchanged at 82b0422, so the existing approvals and ACCEPT still apply. Re-queueing is the next step. If the same task fails again in the queue, the failing case is needed from the full job log, and I will root-cause it from there.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fsWoxB3no3RuuUR8y

Second merge queue dequeue at 01:37Z (CI_FAILURE). This one is this PR's, and it is fixed on the new head 32307090b:

• Queue run 42433827133 on gh-readonly-queue/main/pr-31220-cba7d8ae… (base main cba7d8a, after test(example-todo): boot the loop-body kernel once per file under a measured budget #31312). Red: Type Check · source gates, step "Check generated reference docs are in sync with the spec": content/docs/references/api/contract.mdx and automation-api.mdx out of date. The example-todo timeouts from the first dequeue did not recur.
• Cause: feat(cloud-connection)!: refuse a managed upgrade that renames or retypes a stored field until it is declared or confirmed #31243 on main added SCHEMA_UPGRADE_CONFIRMATION_REQUIRED to the error-code ledger, and this PR adds RESTORE_PARENT_IN_RECYCLE_BIN. Both regenerated the same ApiErrorSchema.code line from +361 more to +362 more, so the merged file is one short (+363 is current).
• Fix: 7a25b6c05 merges origin/main cba7d8a into the branch (a merge, no rebase); 32307090b is gen:schema && gen:docs on the merged tree (3 files, 5 insertions, 2 deletions: the two counts and the new code's list entry in contract.mdx, automation-api.mdx and error-code-ledger.mdx). No source file changed.
• Checked on 32307090b: pnpm --filter @objectstack/spec check:docs exit 0, check:skill-refs exit 0, check:generated exit 0 (after a spec build); error-code-ledger.test.ts, recycle-bin.zod.test.ts, events.test.ts Tests 71 passed (71); restore.test.ts Tests 31 passed (31).

The head moved, so this needs approval again and a re-queue.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

Contract review — ACCEPT (delta)

Head-sha: 32307090b166c9c1ca73da26fa100ecbf3055b6e

ACCEPT · delta over 82b042200e (ACCEPT stands) · 2026-11-08T01:43Z

• The cause of the second dequeue (queue run 42433827133) is a semantic merge race, not this PR's logic. feat(cloud-connection)!: refuse a managed upgrade that renames or retypes a stored field until it is declared or confirmed #31243 (on main since 01:26Z) added SCHEMA_UPGRADE_CONFIRMATION_REQUIRED, and this PR adds RESTORE_PARENT_IN_RECYCLE_BIN. Each regenerated the same "+N more" count from its own base, so the merged tree's check:docs was one short.
• 7a25b6c05d is a merge of origin/main. --remerge-diff shows conflict resolution only in the three generated reference pages (automation-api.mdx, contract.mdx, error-code-ledger.mdx).
• 32307090b1 is gen:schema && gen:docs on the merged tree: those three pages, +5 / −2, no source file. On this head, spec check:docs, check:skill-refs and check:generated exit 0; spec ledger, recycle-bin and events tests pass 71/71; restore.test.ts passes 31/31 (thread report).
• The approval stands. os-zhuang's APPROVE is on 82b042200e, and main's ruleset does not dismiss stale reviews. This PR is Tier H, so re-queueing it is a human act once CI is green on this head.