Skip to content

Commit 12bc827

Browse files
committed
docs(handoff): finish the ADR-0030 retirement — the runbook's own description too
The first pass tombstoned only the cut-over sequence's step 2. Three claims above it still described the migration as live: the `### Data migration (not auto-run)` section that names the deleted file and its export, the breaking-change callout telling a reader to "do the objectui cut-over and the data migration together", and the Tests line counting the migration's own suites among the green ones. Found by the docs-drift round on the PR. The runbook tombstone is now a pointer to the one full account, so the file states it once. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QE8qk46e5CHJxyQEUjbf8
1 parent bb65e0f commit 12bc827

1 file changed

Lines changed: 34 additions & 25 deletions

File tree

docs/handoff/adr-0030-notification-convergence.md

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -62,24 +62,43 @@ a per-user inbox row directly.
6262
a `dedupKey`. No more direct `sys_notification` writes. The plugin resolves the
6363
`messaging` service lazily at hook time (`audit-plugin.ts`).
6464

65-
### Data migration (not auto-run)
65+
### ⚰️ Data migration — RETIRED, there is none
66+
67+
This section used to describe
6668
`packages/metadata/src/migrations/migrate-sys-notification-to-event.ts`
67-
(exported from `@objectstack/metadata/migrations`). Splits each legacy
68-
`sys_notification` inbox row into `sys_inbox_message` + a receipt, rewrites the
69-
row to the event shape, and clears the legacy columns. **Idempotent**; reports
70-
`not_applicable` on fresh installs.
69+
(exported from `@objectstack/metadata/migrations`), which split each legacy
70+
`sys_notification` inbox row into `sys_inbox_message` + a receipt, rewrote the
71+
row to the event shape and cleared the legacy columns.
72+
73+
**That runner is gone (#16194).** It had zero production callers and no
74+
`os migrate` sub-command, and both ways of giving it one were refused: an
75+
operator door is a permanent surface for a migration with no measured demand,
76+
and a boot-time invoker is an unattended data rewrite. ⇒ **Pre-ADR-0030
77+
`sys_notification` rows are not carried by the platform on this line.** After
78+
the cut-over the bell shows rows emitted from the new pipeline onward; older
79+
per-user inbox rows stay where they are, unread by the new UI.
80+
81+
⚠️ Nobody has measured whether any live deployment still holds pre-ADR-0030
82+
`sys_notification` rows. If **your named deployment** does and needs them, ⛔ do
83+
not re-add the call — the migration returns as an operator-runnable `os migrate`
84+
sub-command shaped exactly like `files-to-references` / `value-shapes` (dry-run
85+
default, `--apply` gate, documented consequence), under its own card. Say so on
86+
#16194.
7187

7288
### Tests
73-
`messaging-service`, `inbox-channel`, `messaging-service-plugin`, `notify-node`,
74-
and the migration all have updated/added coverage. All green.
89+
`messaging-service`, `inbox-channel`, `messaging-service-plugin` and
90+
`notify-node` all have updated/added coverage. All green. (The migration's own
91+
suites went with the runner.)
7592

7693
---
7794

7895
## ⚠️ Breaking change — Console bell (objectui, separate repo)
7996

8097
The bell read `sys_notification.{recipient_id, is_read, title, body, …}`. Those
8198
fields **no longer exist**. Until objectui is updated, the bell will be empty /
82-
error. **Do the objectui cut-over and the data migration together.**
99+
error. ⚰️ There is **no data migration to pair it with** any more (see above):
100+
do the objectui cut-over on its own, and expect the bell to start from the
101+
rows the new pipeline emits.
83102

84103
### objectui changes required (`app-shell`)
85104
1. **`AppHeader.tsx` / `InboxPopover.tsx`**: poll **`sys_inbox_message`** filtered
@@ -103,23 +122,13 @@ error. **Do the objectui cut-over and the data migration together.**
103122
(Step order tolerates a brief window where new rows exist but the UI hasn't
104123
flipped — the inbox is being populated the whole time.)
105124

106-
> ⚰️ **The data-migration step is GONE.** This runbook used to carry a step 2,
107-
> `migrateSysNotificationToEvent({ driver, data })`, that carried pre-cut-over
108-
> `sys_notification` rows into `sys_inbox_message` + receipts. The runner has
109-
> been **retired** (#16194): it had zero production callers and no `os migrate`
110-
> sub-command, and both ways of giving it one were refused — an operator door is
111-
> a permanent surface for a migration with no measured demand, and a boot-time
112-
> invoker is an unattended data rewrite. **Pre-ADR-0030 `sys_notification` rows
113-
> are not carried by the platform on this line**: after the cut-over the bell
114-
> shows rows emitted from the new pipeline onward, and older per-user inbox rows
115-
> stay where they are, unread by the new UI.
116-
>
117-
> ⚠️ Nobody has measured whether any live deployment still holds pre-ADR-0030
118-
> `sys_notification` rows. If **your named deployment** does and needs them, do
119-
> not re-add the call — the migration returns as an operator-runnable
120-
> `os migrate` sub-command shaped exactly like `files-to-references` /
121-
> `value-shapes` (dry-run default, `--apply` gate, documented consequence),
122-
> under its own card. Say so on #16194.
125+
> ⚰️ **This sequence used to have three steps.** The middle one was
126+
> `migrateSysNotificationToEvent({ driver, data })`, carrying pre-cut-over
127+
> `sys_notification` rows into `sys_inbox_message` + receipts. That runner is
128+
> retired (#16194) and **pre-ADR-0030 rows are not carried by the platform on
129+
> this line** — the reasoning, the unmeasured-deployment caveat and the reversal
130+
> path are in [Data migration — RETIRED](#-data-migration--retired-there-is-none)
131+
> above. ⛔ Do not re-add the call here.
123132
124133
---
125134

0 commit comments

Comments
 (0)