fix(service-messaging)!: mark-read writes a read receipt only for a notification delivered to that user

[objectstack-fleet]

Fixes #22026
Clause-②: no (narrowing)

A read receipt belongs to a recipient: ADR-0030 keys sys_notification_receipt by recipient. MessagingService.markRead is the method behind the notifications mark-read door and behind markReadAsCaller. It used to insert a read receipt for any notification id it was handed, stamped with that notification's organization, and never checked that the caller was a recipient. It now inserts one only for a notification that was delivered to that user. This follows triage's direction (6022270298) and the seat verdict on the measure-first round (6023979476, option A). Rows already written are not cleaned up; the verdict ruled that out.

What changed

Positions are at base b88c356413, in packages/services/service-messaging/src/messaging-service.ts.

• upsertReadReceipt (near :888) keeps its first step: it flips a receipt keyed (notification_id, user_id, channel 'inbox') to read in place. That read is also the receipt half of the delivery check. The receipt key is the delivered receipt's key, so when the read finds nothing, there is no delivered receipt either.
• When nothing is found, the new private inboxMessageNames checks for the inbox half. It reads the caller's own sys_inbox_message for that notification: where: { user_id, notification_id }, fields: ['id'], under INBOX_SYSTEM_CONTEXT. An inbox message is enough on its own, because the inbox channel's delivered receipt is best-effort: writeDeliveredReceipt logs a failure and moves on, and the inbox row stays.
• If neither half holds, upsertReadReceipt returns 0. No row is written, readCount does not count the id, and notificationOrganization is not called. That organization read now happens only on the delivered path.
• If the inbox read throws, the error reaches markRead's existing per-id catch. It is logged at warn, the id counts 0, and no row is written. A check should fail in that direction.
• markAllRead is unchanged. Its ids come from unreadNotificationIds, which reads the user's own inbox rows that carry a notification_id. So every id it passes already has an inbox message for that user. A pin below covers it.
• Doc comments. The markRead docblock now says an undelivered id writes nothing. The inbox-system-context.ts docblock lists the new read among the calls that context carries; that edit is comment-only, in the same package.
• Unchanged: the response shape { success, readCount }. There is no spec, permission-set or plugin-security change, and nothing changes who may read what.

Reachability, measured before the build

Triage asked for this measurement first. It was taken on base b88c356413 with a local engine-level probe: the real SecurityPlugin, ObjectQL and SqlDriver, the shipped permission sets, and the isolated, group and single postures. The probe was deleted and never committed. Classes and roles only:

• No reader in the stamped organization reads a non-recipient's receipt row, by list or by id. That covers the member, the viewer, the org admin, and the platform admin with that organization active. The _self policy binds every authenticated principal on this object, and the object grants no superuser bypass.
• The stamp grants nobody a read. Its only effect on reads: the writer cannot see their own wrongly stamped row on the generic data door. That row is the defect's own output, and this change stops producing it.
• The inbox's own reads run under their user-keyed context, and the stamp does not reach them.

Report: 6023938722. Seat verdict: 6023979476.

Pins and ablation

The pins are in messaging-service.test.ts, block [#22026]. They use the file's existing stateful inboxEngine double, observed through spies, so no new double was added.

• The recipient half: with an inbox message and no receipt, the receipt persists, is stamped with the notification's organization, and counts 1.
• ⛔ The non-recipient half, for the same notification: the call returns { success: true, readCount: 0 }. The receipt table stays empty, nothing is inserted, the event's organization is not read, and the recipient's state does not move.
• ⛔ The same holds through markReadAsCaller.
• A mixed call counts only the delivered id and writes only its receipt.
• The receipt half: a delivered receipt with no inbox message is still flipped in place, as before.
• The delivery check reads only the caller's own inbox: keyed on user_id, run with { isSystem: true }, and projecting id alone.
• An inbox row with no notification_id: a call naming its row id writes nothing, and the row still lists as unread.
• markAllRead: only delivered ids are swept, by construction. The test counts 2 and finds receipts for that user only.

Fixture triage: in read-receipt-organization.test.ts (pins E and E2), the reader had no delivery evidence. The fixture now gives them their inbox message, which is exactly the case the insert path exists for. The assertions are unchanged.

Ablation. Run on the committed state 7eb0b82008 with scripts/ablation-replace.mjs in wrap mode: delete the delivery-check statement, run the block, restore.

• The anchor count went 1 to 0, and the blob went 448159c99cee to ac84bbb73a43.
• 5 of the 8 pins turned red. The non-recipient half read expected { success: true, readCount: 1 } to deeply equal { success: true, readCount: +0 }.
• The 3 that stayed green are the recipient half, the receipt half and markAllRead, which do not depend on the check.
• After the restore, the blob matched HEAD 448159c99cee and git diff HEAD was empty.

#22025's pins (system-context.pin.test.ts) are green and unchanged.

Tests

Head f2d085db22 unless a line says otherwise. That commit merges origin/main 2301e17eaf, a CI-script commit that touches none of these files.

• Builds. pnpm --filter '@objectstack/service-messaging^...' build exited 0. pnpm --filter @objectstack/service-messaging build exited 0, with check-dts-emitted: 2/2.
• Package suite. pnpm --filter @objectstack/service-messaging test: 48 files and 531 tests passed. typecheck exited 0, and tsc --listFiles shows its program includes all 48 test files, the two edited ones among them.
• Gates. node scripts/pm/dispatch-gates.mjs --commands, run on this change with no paths, derives 65 commands: the dispatch's 51 plus 14 from the changeset and test-file families, none dropped. All 65 exit 0. The --ran reconciliation over the recorded exit codes reads "65 derived, 65 run, 0 NOT-MEASURED, 0 UNRUN".
• Two gates needed a build first. In the first run, at 7eb0b82008, check:dual-build-cjs-loads and check:i18n exited 3 (PREREQUISITE NOT MET: no build output). After a turbo build of the workspace (72 tasks, 71 cached), both exited 0, and they exit 0 at the merge head too.
• Verdict lines.
  • check-nul-bytes: OK, no raw ASCII control bytes.
  • check-adr-0087-registration printed its no-migration-prescription exemption notice.
  • check-empty-changeset: "No empty-frontmatter changeset introduced by this diff".
  • check-system-context-census: OK.
  • check-changeset-no-major reads its level axis from the PR payload, so that half is answered in CI.
• Dogfood, at 7eb0b82008 (the merge touched no package). These suites reach service-messaging through dist/, which was checked to contain the change: approval-notification-body.dogfood.test.ts, schedule-acting-organization.dogfood.test.ts, schedule-sweep-organization-scope.dogfood.test.ts and platform-app-object-entry-views.test.ts. 4 files and 84 tests passed.
• Runtime, through the real HTTP mark-read door, at 7eb0b82008. notifications.hono.integration.test.ts delivers through the real pipeline, marks one notification read (readCount: 1), then marks all read. Together with notification-schema-conformance.test.ts and domains/notifications-query-validation.test.ts: 3 files and 54 tests passed.
• Left to CI: repo-wide lint, the whole-workspace type-check lanes, the Test Core shards and the full dogfood shards.

Acceptance notes

• Comment drift in plugin-security, carrier: none. In default-permission-sets.ts, the comment above sys_inbox_message_self says neither inbox object declares organization_id, so Layer 0 is inert on them. In fact the registry injects organization_id into sys_notification_receipt (it is engine-owned, not better-auth), and the tenant wall and the driver's native tenant scope do act on it, only ever narrowing. This is comment drift, not a behaviour defect. That file is not edited here.
• Rows written by the old path stay. No non-system reader can read them, and they expire under the object's declared 90-day transient lifecycle. If the same user marks the same id read again, that existing row is flipped, as before: the flip path is unchanged by ruling.
• Inbox rows without a notification_id. notification: 没有 notification_id 的 sys_inbox_message 行永远无法被标记已读 —— 读态的键在事件 id 上 #6448, which asked about such rows, ended in the not-planned state. listInbox looks up read state only through a row's notification_id, so a row without one always lists as unread. Nothing regresses for those rows.
• The changeset is minor with a BREAKING banner (an accept-set narrowing, under the launch-window convention) and carries an ADR-0087 not-required (no-migration-prescription) disposition.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-messaging, touching 3 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-messaging/src/inbox-system-context.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/releases/v17/17-2.mdx (via MessagingService (symbol, a top-level class))

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

• 1 changed file(s) yielded no anchor (packages/services/service-messaging/src/inbox-system-context.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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 — 5 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 2301e17eaf470c2cdefe2eb1cd05b41ba350cc84 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 2301e17eaf470c2cdefe2eb1cd05b41ba350cc84

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