[objectstack-fleet]

Requested by Leehom · project thread

domain:server#5 · os-project-manager · session_01FEkQ5mbAyTfp7gbjowRA48

Fixes #31473

Clause-②: yes (widening) — RealtimeAPI.subscribeData now delivers every per-record event type the spec's DataEventType declares, which adds data.record.restored (a row restored from the recycle bin) to the created / updated / deleted it delivered before. subscribeBulkData reads BulkDataEventType the same way; its two types are unchanged.
Metadata-protocol: none

维护者速读

• 改了什么: @objectstack/client 的 subscribeData / subscribeBulkData 订阅的事件类型改为直接读 spec 的 DataEventType / BulkDataEventType 枚举，不再手写列表；回收站恢复产生的 data.record.restored 因此能送达订阅者。
• 为什么改: feat(objectql): restore a recycle-bin entry under its original ids and emit data.record.restored (#30237 PR 3) #31220 给 DataEventType 加了 restored，但 SDK 手写的 created/updated/deleted 列表把它过滤掉，订阅者的实时列表看不到被恢复的记录 (client: subscribeData filters data.record.restored out, so an SDK data subscriber never sees a recycle-bin restore #31473)。
• 风险与回滚: 只多送一种事件；按 event.type 分支的回调会多看到 data.record.restored(载荷 after 带恢复后的行)。客户端本就运行时依赖 @objectstack/spec/api，无新依赖。回滚即 revert 本 PR。
• 先看: packages/client/src/realtime-api.ts 中 subscribeData 与 subscribeBulkData 的 eventTypes。
• 两分钟验证: cd packages/client && npx vitest run src/realtime-api-data-event-types.test.ts，预期 4 个用例全过 (在 main 上 3 个红)。
• 需要你做的: 无，席位落地。

What changes

• subscribeData asked for ['data.record.created', 'data.record.updated', 'data.record.deleted'], written by hand. data.record.restored, which ObjectQL's recycle-bin restore publishes with the restored row in after and which feat(objectql): restore a recycle-bin entry under its original ids and emit data.record.restored (#30237 PR 3) #31220 added to DataEventType, matched no subscription filter and was dropped. It now asks for [...DataEventType.options].
• subscribeBulkData kept the same kind of hand list (['data.records.updated', 'data.records.deleted']). It now asks for [...BulkDataEventType.options]; its two types are unchanged. No other client code lists data event types.
• Restored joins the default list rather than an opt-in. The triage left that to the lane. A restore is the inverse of a delete the subscriber already receives, and the callback is typed (event: DataEvent) => void, whose type is DataEventType. Delivering the whole enum makes the subscription mean what its type says, and a list that rebuilds itself from created / deleted needs the restore to stay correct.
• No new dependency. realtime-api.ts already imports runtime values (DataEventSchema, BulkDataEventSchema) from @objectstack/spec/api, so the two enums come from a module the client already loads. The published dependency set and the imported module are unchanged.
• Changeset 31473-client-subscribe-data-restored.md: @objectstack/client patch (Metadata-protocol: none, ruling A).

Tests

New packages/client/src/realtime-api-data-event-types.test.ts:

• ⭐ a row restored from the recycle bin reappears in the subscriber's list: created → deleted → restored, the callback's list ends with the row.
• ⭐ every DataEventType member reaches subscribeData (read from the enum, so a type added later is covered without editing the test).
• every BulkDataEventType member reaches subscribeBulkData (green on main too; it keeps the bulk list honest from here on).
• ⭐ realtime-api.ts spells no data.record(s).* type as a string literal and reads both enums.

Red on main (2ae3e30, test file only): Tests 3 failed | 1 passed (4):

× ⭐ a row restored from the recycle bin reappears in the subscriber's list
  AssertionError: expected [] to deeply equal [ 'task_1' ]
× ⭐ every DataEventType the spec declares reaches subscribeData
  AssertionError: expected [ 'data.record.created', …(2) ] to deeply equal [ 'data.record.created', …(3) ]
× ⭐ realtime-api.ts keeps no hand list of data event types

Ablation (scripts/ablation-replace.mjs on committed ec765f5d, subscribeData's eventTypes: [...DataEventType.options] put back as the old three-item hand list): ok mutation landed: anchor 1 -> 0, blob 444fe4c6de5e -> 5bcbff9269d0, the same three pins red (Tests 3 failed | 1 passed (4)), then ok restored: blob == HEAD (444fe4c6de5e) and git diff HEAD is empty.

Acceptance notes

• The handler's comment still says data.field.changed is "declared in DataEventType". The enum no longer lists it. Left as is because it is outside this card's surface. Noted, not filed.

Verification

• Head cba18d92; cut from fresh origin/main 2ae3e301, with origin/main 7d0b47ca merged before opening (no file overlap with this diff; the three realtime test files re-ran green after the merge, 26/26).
• pnpm --filter @objectstack/client test under os-verify-lock: VERDICT command-exit 0, Test Files 56 passed (56), Tests 716 passed (716).
• pnpm --filter @objectstack/client typecheck (tsc --noEmit and check:test-typecheck): exit 0. eslint on the two touched .ts files: exit 0.
• Gates from node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 61 derived, 61 run, all exit 0 (--ran: 0 NOT-MEASURED). Two first read exit 3 (check:skill-examples, check:dual-build-cjs-loads: a prerequisite, built output missing in a fresh worktree). After pnpm --filter './packages/**' run build under the lock, both exited 0. Record: /mnt/project-files/pm-orders/server/31473-gates-ran.txt.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (not touched)
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes. (eslint on the two touched .ts files: exit 0)
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (.changeset/31473-client-subscribe-data-restored.md, @objectstack/client patch)
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English. (the 维护者速读 block is the lane's required Chinese summary)
• The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5mbAyTfp7gbjowRA48

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/client, touching 7 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via data.record.updated (literal, a string literal in subscribeData), data.records.updated (literal, a string literal in subscribeBulkData))
• content/docs/protocol/kernel/realtime-protocol.mdx (via data.record.created (literal, a string literal in subscribeData), data.record.deleted (literal, a string literal in subscribeData), data.record.updated (literal, a string literal in subscribeData))
• content/docs/protocol/knowledge.mdx (via data.record.created (literal, a string literal in subscribeData), data.record.deleted (literal, a string literal in subscribeData), data.record.updated (literal, a string literal in subscribeData), data.records.deleted (literal, a string literal in subscribeBulkData), data.records.updated (literal, a string literal in subscribeBulkData))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-6.mdx (via data.record.created (literal, a string literal in subscribeData), data.record.deleted (literal, a string literal in subscribeData), data.record.updated (literal, a string literal in subscribeData), data.records.deleted (literal, a string literal in subscribeBulkData), data.records.updated (literal, a string literal in subscribeBulkData))
• content/docs/releases/v17/17-7.mdx (via data.record.created (literal, a string literal in subscribeData), data.record.updated (literal, a string literal in subscribeData))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 64 of 227 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 — 19 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 7d0b47ca19c8c41563964b3889ae81e8e015788e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 8c29bddc1da276e2d87f759cf95557ca45638ecb — the merge of head cba18d9204b4d4569f238a2f799cc1c818989b13 into base 7d0b47ca19c8c41563964b3889ae81e8e015788e, 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 8c29bddc1da276e2d87f759cf95557ca45638ecb && git checkout 8c29bddc1da276e2d87f759cf95557ca45638ecb
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7d0b47ca19c8c41563964b3889ae81e8e015788e cba18d9204b4d4569f238a2f799cc1c818989b13 && git checkout -B drift-repro 7d0b47ca19c8c41563964b3889ae81e8e015788e && git merge --no-ff cba18d9204b4d4569f238a2f799cc1c818989b13

node scripts/docs-audit/affected-docs.mjs --json 7d0b47ca19c8c41563964b3889ae81e8e015788e

⚠️ 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 7d0b47ca19c8c41563964b3889ae81e8e015788e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5o8PE7ZtVjcor51wBZ

Contract-review-claim: session_01FEkQ5o8PE7ZtVjcor51wBZ · head cba18d9 · 2026-11-08T12:02Z

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5o8PE7ZtVjcor51wBZ

Contract review

Served-tier: TIER_DEFAULT
Head-sha: cba18d9204b4d4569f238a2f799cc1c818989b13
Local-runs: none

Inputs: card #31473 with its triage 6720603952, the seat claim 6720748415 and os-dev-report 6721223073; the PR body; the net diff origin/main...pr/31509 (3 files, +129 / −6); DataEventType and BulkDataEventType in packages/spec/src/api/events.zod.ts on main. The face is the declaration face: no schema or governed path, and Clause-②: yes (widening).

① Derived judgments

• subscribeData now asks for [...DataEventType.options]. On main that enum is created, updated, deleted and restored, so the one added type is data.record.restored. The enum is the spec's own published list, which feat(objectql): restore a recycle-bin entry under its original ids and emit data.record.restored (#30237 PR 3) #31220 extended. The handler's guards are unchanged: anything outside data., data.records.*, and payloads that fail DataEventSchema. A restored event is a DataEvent (the schema's type is DataEventType), so it parses and reaches the callback. Right.
• subscribeBulkData now asks for [...BulkDataEventType.options]. That is the same two types as the hand list it replaces, so the bulk subscriber sees nothing new. Right.
• The hand lists are gone. These were the client's only two hand lists of data event types. The import comes from @objectstack/spec/api, which realtime-api.ts already imported runtime values from, so the package takes on no new dependency. Right.
• Public surface. No exported signature changes. What widens is the set of events an existing subscription delivers: a callback that switches on event.type will now see data.record.restored. The changeset names that. Right.

② Semver level

• @objectstack/client patch under ruling A on changeset levels: minor only when the metadata protocol changes (added / narrowed / semantic), patch otherwise; release notes grouped by what the reader must do (maintainer ruling A, 2026-10-21) #25105, since Metadata-protocol: none means patch. Right.
• Clause-②: yes (widening). One more event type is delivered to existing subscribers, and nothing they received before is refused. That is a widening, with no narrowing arm. Right.
• Restored is in the default list, not opt-in. The PR argues that a subscriber's live list should see a restored row come back, the same way it sees a create. Accepted: that is the card's reach.

③ Boundary flags

• Red-first on main: 3 of the 4 new pins fail. Ablating the derived list reds the same 3. The fourth is the bulk control, unchanged by design.
• open_questions: none.
• Two gates first exited 3 on a missing build in a fresh worktree, then passed after a build. That is tooling, not this diff.

Implemented-by: claude/project-thread-u74sqa
Reviewed-by: session_01FEkQ5o8PE7ZtVjcor51wBZ

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5o8PE7ZtVjcor51wBZ

席位意见：接受。SDK 的 subscribeData 现在也会收到从回收站恢复记录的事件（data.record.restored），订阅的事件类型直接取自规范的枚举，不再手写清单，以后规范新增的类型不会再被漏掉。批量订阅的类型不变。

席位核对 — ACCEPT · domain:server#5 · Head-sha cba18d9204b4d4569f238a2f799cc1c818989b13 · 2026-11-08T12:24Z

The maintainer's standing authorisation for landing reviewed PRs, verbatim: 「按照 pm-dispatch 规则复核过的都授权」.

• Shape: 3 files (+129 / −6), read from the diff:

  • realtime-api.ts: subscribeData reads [...DataEventType.options] and subscribeBulkData reads [...BulkDataEventType.options]. This adds no new dependency.
  • One test file.
  • One changeset: @objectstack/client patch under ruling A on changeset levels: minor only when the metadata protocol changes (added / narrowed / semantic), patch otherwise; release notes grouped by what the reader must do (maintainer ruling A, 2026-10-21) #25105.

  Clause-②: yes (widening), Metadata-protocol: none.

• Review: TIER_DEFAULT, declaration face, in-seat, outside the dev's session: PASS on this head, with no findings.

• Gates: head check-runs are 54 success and 9 skipped, with none red or pending. check-expected-skips: OK (exit 0). check-governed-merges: NOT governed. The dev's derived gates: 61 of 61 exit 0. Mergeable state clean.

• Landing: ungoverned, tier S. Ready and auto-merge go in one relay dispatch. Fixes #31473 closes the card on merge.

---

Generated by Claude Code