fix(service-messaging,metadata-protocol)!: a notification preference's User is a sys_user reference, so its title names the person and the default for every user is an empty User instead of '*'

.changeset/24895-preference-user-reference.md

@@ -0,0 +1,23 @@
+---
+'@objectstack/service-messaging': patch
+'@objectstack/metadata-protocol': patch
+---
+
+fix(service-messaging,metadata-protocol)!: a notification preference's User is a `sys_user` reference, so the record title names the person and the write door refuses an id no user holds; the default for every user is an empty User instead of `'*'`
+
+Clause-②: yes (narrowing)
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling or exported declaration is added, removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite. What changes is a platform object this package ships and owns, `sys_notification_preference`: its `user_id` column becomes a `sys_user` lookup, and what narrows is the write accept set of that object's rows, which are admin-authored data rather than metadata. No ADR-0087 conversion reaches a stored data row; the stored rows that spelled the retired `'*'` are rewritten by this package itself at boot, and the one-default-per-key index is a runtime migration in `@objectstack/metadata-protocol`. The other categories are closed on facts: both packages publish (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
+
+**BREAKING** (a platform object's write accept set narrows, and one stored value is rewritten). It changes what a data writer can store in `sys_notification_preference`, not what a metadata author can write, so it ships as `patch` with this banner.
+
+- **FROM:** `sys_notification_preference.user_id` was a required text column holding a user id or the literal `'*'`, which meant "the default for every user". Any string was stored: a mistyped id matched nobody, silently. The record title (Setup → Notification Preferences) read the raw id, for example `ISu3jHPIrdgD45L1rrC2FuE7DIcsk2ap · urgent_task · inbox`. Two defaults for every user could be stored for one topic and channel in one organization, and which one applied was unspecified.
+- **TO:** `user_id` is an optional `sys_user` lookup (ADR-0118 D1: no sentinel in a user column). An empty User is the default for every user, and a user's own row still overrides it.
+  - A write that names an id no user holds, `'*'` included, is refused: the REST data door answers `400` with `code: 'VALIDATION_FAILED'` and a finding on `user_id` with `code: 'reference_not_found'`.
+  - The title names the person: their name, or their email where the name is blank, then the topic and the channel. A row with an empty User reads `All users · TOPIC · CHANNEL`. A row whose User this reader cannot read, or that no longer exists, has no title rather than a misleading one.
+  - Deleting a user deletes that user's preference rows (`deleteBehavior: 'cascade'`). Under the lookup default (`set_null`) the person's own mute would have become the default for every user.
+  - At every boot (`kernel:ready`), the messaging service rewrites each stored `user_id = '*'` to an empty User, in every organization. A second run changes nothing. A `'*'` row whose topic and channel already have a default with an empty User is left as stored and reported once at `error`, naming the row; it is never deleted for you.
+  - On SQLite and PostgreSQL, `@objectstack/metadata-protocol` rebuilds the index `uniq_sys_notification_preference_a22d7d27` at `kernel:ready` as `(organization_id, COALESCE(user_id, ''), topic, channel)`, so a second default for one topic and channel in one organization is refused (`409`). If existing rows already break that rule, it refuses to migrate: the previous index stays, no row is touched, and the boot log and `os migrate duplicates` list the rows. MySQL/MariaDB and driver-memory keep the declared index, which does not constrain empty Users, and the boot log says so on MySQL.
+- **Unchanged:** `topic = '*'` and `channel = '*'` are still the topic and channel wildcards. Most-specific-wins resolution, mandatory topics, quiet hours and digests behave as before. A row for a real user is read, matched and titled as before, except for the title text. The physical column is still a `varchar(255)`, so no DDL change is needed for it.
+- **The fix for an operator:** nothing, normally; the boot rewrites the old `'*'` rows. If the boot log reports a `'*'` row that shares its topic and channel with a default whose User is already empty, delete the one that should not apply and restart. If it reports that the one-default-per-key index could not be built because two such defaults exist, list them with `os migrate duplicates`, delete one, and restart. A script or import that wrote `user_id: '*'` writes an empty `user_id` (omit it, or send `null`) for the default for every user.

content/docs/permissions/tenant-audit-census.mdx

@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **51 of the 236 sites are spelled that way**. A
+forwarding shim cannot, and **51 of the 237 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **236** |
+| 175 write call sites | quoted in the merged changeset | **237** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **159 of 236** decidable, **77** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 134 decidably elevated, 0 decidably not, 94 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **160 of 237** decidable, **77** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 135 decidably elevated, 0 decidably not, 94 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -201,17 +201,17 @@ at any commit.
 
 Two structural facts do plausibly widen this reading against any hand or regex
 one, and both are counted in the generated tables below: the 41 sites reached
-through an erased (`any`) receiver, and the 50 that name their object through a
+through an erased (`any`) receiver, and the 51 that name their object through a
 `const` rather than inline. An instrument that read either the way a person does
 would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-134 of 236 (57%) as decidably elevated, with 94 more whose elevation is a
+135 of 237 (57%) as decidably elevated, with 94 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 236`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 237`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **29 further sites** have an options argument this
@@ -223,29 +223,29 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **236** |
-| …whose object name is statically decidable | 159 |
+| write call sites on the application surface | **237** |
+| …whose object name is statically decidable | 160 |
 | …whose object name is chosen at run time | 77 |
-| …against an object with tenancy ENABLED | 158 |
+| …against an object with tenancy ENABLED | 159 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 177 |
+| threading a tenant context | 178 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 51 |
 | …of those, against a decidably tenancy-enabled object | 29 |
-| threading a decidably ELEVATED (`isSystem`) context | 134 |
+| threading a decidably ELEVATED (`isSystem`) context | 135 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 94 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 195 |
+| receiver carried a readable engine type | 196 |
 | receiver erased, placed by the object NAME | 31 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
 | object name spelled inline | 109 |
-| object name spelled through a `const` | 50 |
+| object name spelled through a `const` | 51 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 70 |
 
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-20 at `a454cbcc4`.
+Measured on 2026-10-22 at `452e9963c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 684 |
-| engine-shaped types recognised | 82 |
-| declared objects in the registry | 118 |
+| tracked non-test sources scanned | 700 |
+| engine-shaped types recognised | 86 |
+| declared objects in the registry | 117 |
 | same-named calls subtracted as non-engine | 169 |
 
 {/* END GENERATED: tenant-audit-census */}

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 236 |
-| Object name statically decidable | 159 |
+| Write call sites | 237 |
+| Object name statically decidable | 160 |
 | Object name chosen at run time | 77 |
-| Against a tenancy-enabled object | 158 |
+| Against a tenancy-enabled object | 159 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 177 |
+| Threading a tenant context | 178 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 51 |
 | …and decidably tenancy-enabled | 29 |
-| Threading a decidably elevated context | 134 |
+| Threading a decidably elevated context | 135 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 94 |
 
@@ -90,13 +90,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-20 at `a454cbcc4`.
+Measured on 2026-10-22 at `452e9963c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 684 |
-| engine-shaped types recognised | 82 |
-| declared objects in the registry | 118 |
+| tracked non-test sources scanned | 700 |
+| engine-shaped types recognised | 86 |
+| declared objects in the registry | 117 |
 | same-named calls subtracted as non-engine | 169 |
 
 ## Every site
@@ -221,6 +221,7 @@ Measured on 2026-10-20 at `a454cbcc4`.
 | `packages/services/service-messaging/src/messaging-service.ts` | `insert` | `RECEIPT_OBJECT` | undecidable | context, elevation undecidable | 1 |
 | `packages/services/service-messaging/src/messaging-service.ts` | `update` | `RECEIPT_OBJECT` | undecidable | options unreadable | 1 |
 | `packages/services/service-messaging/src/messaging-service.ts` | `insert` | `sys_notification` | enabled | context, elevation undecidable | 1 |
+| `packages/services/service-messaging/src/preference-user-conversion.ts` | `update` | `sys_notification_preference` | enabled | elevated | 1 |
 | `packages/services/service-messaging/src/sql-http-outbox.ts` | `insert` | `this.objectName` | undecidable | context, elevation undecidable | 1 |
 | `packages/services/service-messaging/src/sql-http-outbox.ts` | `update` | `this.objectName` | undecidable | context, elevation undecidable | 4 |
 | `packages/services/service-messaging/src/sql-http-outbox.ts` | `update` | `this.objectName` | undecidable | options unreadable | 1 |

packages/cli/src/commands/migrate/duplicates.contract.test.ts

@@ -231,7 +231,7 @@ describe('#8928 os migrate duplicates — the report document', () => {
           organizationCounters: [{ organization: 'org_x', lastValue: 4 }],
         },
       ],
-      // One entry per index the two `kernel:ready` migrations tighten — THREE,
+      // One entry per index the three `kernel:ready` migrations tighten — FOUR,
       // because the overlay migration builds one per state and either can be
       // blocked on its own. Present whatever the outcome: an index left out
       // would make "nothing blocks it" and "it was never probed" the same
@@ -253,14 +253,17 @@ describe('#8928 os migrate duplicates — the report document', () => {
     });
   });
 
-  it('names the three kernel:ready indexes, and the migration behind each — none for the retired sys_view_definition (ADR-0131 D13)', async () => {
+  it('names the four kernel:ready indexes, and the migration behind each — none for the retired sys_view_definition (ADR-0131 D13)', async () => {
     const report = await collect();
     expect(
       report.runtimeIndexPreflight.map((p) => `${p.migration}:${p.table}:${p.index}`),
     ).toEqual([
       'ensureMetadataOverlayIndexes:sys_metadata:idx_sys_metadata_overlay_active',
       'ensureMetadataOverlayIndexes:sys_metadata:idx_sys_metadata_overlay_draft',
       'ensureSysSettingIdentityIndex:sys_setting:uniq_sys_setting_organization_id_namespace_key_scope_user_id',
+      // One admin-global default (an empty User) per (organization, topic,
+      // channel): service-messaging's preference table, ADR-0118 D1.
+      'ensureNotificationPreferenceIdentityIndex:sys_notification_preference:uniq_sys_notification_preference_a22d7d27',
     ]);
   });
 

packages/cli/src/commands/migrate/duplicates.integration.test.ts

@@ -311,9 +311,9 @@ describe('#8928 os migrate duplicates — against a really booted stack', () =>
     // sees that something is blocked without reading every entry.
     expect(produced.summary.runtimeIndexesBlocked).toBe(1);
     expect(produced.summary.runtimeIndexBlockingRows).toBe(2);
-    // `sys_setting` is absent on this fixture; whatever each status, the three
+    // `sys_setting` is absent on this fixture; whatever each status, the four
     // indexes are all accounted for.
-    expect(produced.runtimeIndexPreflight).toHaveLength(3);
+    expect(produced.runtimeIndexPreflight).toHaveLength(4);
     expect(produced.reportVersion).toBe(2);
 
     // The whole run — boot included — wrote nothing. If a future change arms a

packages/drivers/driver-sql/src/sql-driver-tenant-scoped-declared-unique.test.ts

@@ -252,7 +252,11 @@ const SUBJECTS: Subject[] = [
     control: { user_id: 'user_only_yi', topic: 'billing.invoice', channel: 'email' },
     trailingControl: { user_id: 'user_u1', topic: 'billing.invoice', channel: 'push' },
     filler: {},
-    platformKey: { user_id: '*', topic: 'billing.invoice', channel: 'email' },
+    // A plain user id like every other subject's platform key. It spelled
+    // `'*'` once, the text column's admin-global sentinel; `user_id` is now a
+    // `sys_user` reference whose EMPTY value is that default (ADR-0118 D1), so
+    // the sentinel is no stored value any more. At this layer it is just a key.
+    platformKey: { user_id: 'user_platform', topic: 'billing.invoice', channel: 'email' },
     legacyName: 'uniq_sys_notification_preference_user_id_topic_channel',
     // ⚠️ HASH-SUFFIXED, and this is the case the PM's A1 flagged as the one
     // where a single-column assumption would hide. The base name