@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/src/modules/notifications/migrations/Migration20260625122947_notifications.ts

@@ -0,0 +1,14 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260625122947_notifications extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "notification_preferences" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "user_id" uuid not null, "notification_type_id" text not null, "channel" text not null, "enabled" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "notification_preferences_unique" on "notification_preferences" ("tenant_id", "user_id", "notification_type_id", "channel");`);
+    this.addSql(`create index "notification_preferences_tenant_user_idx" on "notification_preferences" ("tenant_id", "user_id");`);
+
+    this.addSql(`create table "notification_types" ("id" text not null, "tenant_id" uuid null, "label_key" text not null, "description_key" text null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "notification_types_tenant_idx" on "notification_types" ("tenant_id");`);
+  }
+
+}

package/src/modules/notifications/migrations/Migration20260626120500_notifications_push_payload.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260626120500_notifications_push_payload extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "notifications" add column "data" jsonb null;`);
+    this.addSql(`alter table "notifications" add column "push_options" jsonb null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "notifications" drop column "push_options";`);
+    this.addSql(`alter table "notifications" drop column "data";`);
+  }
+
+}

package/src/modules/notifications/migrations/Migration20260626130000_notifications_non_opt_out.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260626130000_notifications_non_opt_out extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "notification_types" add column "non_opt_out" boolean not null default false;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "notification_types" drop column "non_opt_out";`);
+  }
+
+}

package/src/modules/notifications/migrations/Migration20260626140000_notifications_type_category_silent.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260626140000_notifications_type_category_silent extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "notification_types" add column "category" text null;`);
+    this.addSql(`alter table "notification_types" add column "silent" boolean not null default false;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "notification_types" drop column "silent";`);
+    this.addSql(`alter table "notification_types" drop column "category";`);
+  }
+
+}

package/src/modules/notifications/migrations/Migration20260706120000_notifications_channels.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260706120000_notifications_channels extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "notifications" add column "channels" jsonb null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "notifications" drop column "channels";`);
+  }
+
+}

package/src/modules/notifications/migrations/Migration20260716123121_notifications.ts

@@ -0,0 +1,14 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260716123121_notifications extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "notification_type_overrides" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "notification_type_id" text not null, "channels" jsonb null, "non_opt_out" boolean null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "notification_type_overrides_unique" on "notification_type_overrides" ("tenant_id", "notification_type_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "notification_type_overrides" cascade;`);
+  }
+
+}

package/src/modules/notifications/notification-channels.ts

@@ -0,0 +1,30 @@
+import type { NotificationChannelDefinition } from '@open-mercato/shared/modules/notifications/types'
+
+/**
+ * Core-owned delivery channels. `notifications` is the channel-metadata authority (labels shown in the
+ * preferences UI + the `/api/notifications/channels` catalogue); the delivery *behavior* for each lives
+ * in its own strategy (`in_app`/`email` here, `push` in `push_notifications`). Third-party modules add
+ * further channels by shipping their own generator-discovered `notification-channels.ts`.
+ */
+export const notificationChannels: NotificationChannelDefinition[] = [
+  {
+    id: 'in_app',
+    labelKey: 'notifications.preferences.channels.inApp',
+    descriptionKey: 'notifications.preferences.channels.inAppHint',
+    order: 10,
+  },
+  {
+    id: 'email',
+    labelKey: 'notifications.preferences.channels.email',
+    descriptionKey: 'notifications.preferences.channels.emailHint',
+    order: 20,
+  },
+  {
+    id: 'push',
+    labelKey: 'notifications.preferences.channels.push',
+    descriptionKey: 'notifications.preferences.channels.pushHint',
+    order: 30,
+  },
+]
+
+export default notificationChannels

package/src/modules/notifications/notifications.delivery-strategies.ts

@@ -0,0 +1,15 @@
+import type { NotificationDeliveryStrategy } from './lib/deliveryStrategies'
+import { inAppDeliveryStrategy } from './lib/strategies/in-app-delivery-strategy'
+import { emailDeliveryStrategy } from './lib/strategies/email-delivery-strategy'
+
+/**
+ * Core-owned delivery strategies, discovered by the notifications `delivery-strategies` generator
+ * plugin (see `generators.ts`) and registered at bootstrap. `push` is contributed separately by the
+ * `push_notifications` module through its own `notifications.delivery-strategies.ts`.
+ */
+export const deliveryStrategies: NotificationDeliveryStrategy[] = [
+  inAppDeliveryStrategy,
+  emailDeliveryStrategy,
+]
+
+export default deliveryStrategies

package/src/modules/notifications/setup.ts

@@ -1,10 +1,32 @@
 import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { TYPE_REGISTRY_SYNC_EVENT } from './events'
+
+const logger = createLogger('notifications')
 
 export const setup: ModuleSetupConfig = {
   defaultRoleFeatures: {
     superadmin: ['notifications.*'],
     admin: ['notifications.*'],
-    employee: ['notifications.view'],
+    employee: ['notifications.view', 'notifications.manage_preferences'],
+  },
+
+  async seedDefaults({ container, tenantId, organizationId }) {
+    // Best-effort: nudge the type catalogue into the DB at init time. The
+    // `GET /api/notifications/types` lazy reconcile is the reliable fallback, so
+    // a failure here must never break tenant initialization.
+    try {
+      const eventBus = container.resolve('eventBus') as {
+        emit: (event: string, payload: unknown, options?: unknown) => Promise<void>
+      }
+      await eventBus.emit(
+        TYPE_REGISTRY_SYNC_EVENT,
+        { tenantId, organizationId },
+        { tenantId, organizationId, persistent: true },
+      )
+    } catch (err) {
+      logger.warn('type_registry.sync emit skipped during seedDefaults', { err })
+    }
   },
 }
 

package/src/modules/notifications/subscribers/deliver-notification.ts

@@ -2,12 +2,12 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { Notification } from '../data/entities'
 import { NOTIFICATION_EVENTS } from '../lib/events'
 import { DEFAULT_NOTIFICATION_DELIVERY_CONFIG, resolveNotificationDeliveryConfig, resolveNotificationPanelUrl } from '../lib/deliveryConfig'
-import { getNotificationDeliveryStrategies } from '../lib/deliveryStrategies'
-import { sendEmail } from '@open-mercato/shared/lib/email/send'
-import NotificationEmail from '../emails/NotificationEmail'
-import { loadDictionary } from '@open-mercato/shared/lib/i18n/server'
-import { createFallbackTranslator } from '@open-mercato/shared/lib/i18n/translate'
-import { defaultLocale } from '@open-mercato/shared/lib/i18n/config'
+import { getNotificationDeliveryStrategies, type NotificationDeliveryContext } from '../lib/deliveryStrategies'
+import { resolveEffectiveChannels } from '../lib/shouldDeliver'
+import { getNotificationType } from '../lib/notification-type-registry'
+import { getNotificationTypeOverrides } from '../lib/typeOverrides'
+import { resolveNotificationPreferenceService } from '../lib/notificationPreferenceService'
+import { resolveNotificationCopy } from '../lib/notificationCopy'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { User } from '../../auth/data/entities'
 import type { TenantDataEncryptionService } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
@@ -46,23 +46,6 @@ const buildPanelLink = (panelUrl: string, notificationId: string) => {
   return `${panelUrl}${separator}notificationId=${encodeURIComponent(notificationId)}`
 }
 
-const resolveNotificationCopy = async (
-  notification: Notification
-) => {
-  const dict = await loadDictionary(defaultLocale)
-  const t = createFallbackTranslator(dict)
-
-  const title = notification.titleKey
-    ? t(notification.titleKey, notification.title ?? notification.titleKey, notification.titleVariables ?? undefined)
-    : notification.title
-
-  const body = notification.bodyKey
-    ? t(notification.bodyKey, notification.body ?? notification.bodyKey ?? '', notification.bodyVariables ?? undefined)
-    : notification.body ?? null
-
-  return { title, body, t }
-}
-
 const resolveRecipient = async (
   em: EntityManager,
   notification: Notification,
@@ -94,13 +77,18 @@ const resolveRecipient = async (
   }
 }
 
-
+/**
+ * Dispatches a created notification across every registered delivery channel. This is a pure
+ * "resolve copy → loop strategies" loop with NO channel-specific branches: in-app, email, and push
+ * are all first-class strategies on the seam. Per-channel opt-out / `nonOptOut` / `silent` /
+ * eligibility / per-send targeting were already resolved once at create time into
+ * `notification.channels` (see `shouldDeliver`); here we only replay that target set and apply each
+ * strategy's technical short-circuits (`supports`, `isConfigured`). `notification.channels === null`
+ * means "all channels" (legacy rows + pre-Phase-7 behavior).
+ */
 export default async function handle(payload: NotificationCreatedPayload, ctx: ResolverContext) {
   debug('deliver notification event', payload)
   const deliveryConfig = await resolveNotificationDeliveryConfig(ctx, { defaultValue: DEFAULT_NOTIFICATION_DELIVERY_CONFIG })
-  if (!deliveryConfig.strategies.email.enabled) {
-    debug('email delivery disabled')
-  }
 
   const em = ctx.resolve('em') as EntityManager
   const notification = await findOneWithDecryption(
@@ -159,61 +147,107 @@ export default async function handle(payload: NotificationCreatedPayload, ctx: R
       })
       .filter((action): action is NonNullable<typeof action> => action !== null)
 
-    if (deliveryConfig.strategies.email.enabled && recipient?.email && panelLink) {
-      const subjectPrefix = deliveryConfig.strategies.email.subjectPrefix?.trim()
-      const subject = subjectPrefix ? `${subjectPrefix} ${title}` : title
-      const copy = {
-        preview: t('notifications.delivery.email.preview', 'New notification'),
-        heading: t('notifications.delivery.email.heading', 'You have a new notification'),
-        bodyIntro: t('notifications.delivery.email.bodyIntro', 'Review the notification details and take any required actions.'),
-        actionNotice: t('notifications.delivery.email.actionNotice', 'Actions are available in Open Mercato and are read-only in this email.'),
-        openCta: t('notifications.delivery.email.openCta', 'Open notification center'),
-        footer: t('notifications.delivery.email.footer', 'Open Mercato notifications'),
-      }
-
+    const strategyConfigs = deliveryConfig.strategies.custom ?? {}
+    const strategies = getNotificationDeliveryStrategies()
+    // Authoritative per-send target resolved at create time. A null snapshot (legacy pre-Phase-7 row,
+    // or a create that ran before the delivery strategies were registered) would otherwise deliver
+    // every channel with no gate — so recompute the effective set from current preferences here,
+    // keeping the single `shouldDeliver` gate instead of re-checking opt-out inside each strategy.
+    const persistedChannels = notification.channels
+    const registeredStrategyIds = strategies.map((strategy) => strategy.id)
+    let targetChannels: string[] | null = persistedChannels ?? null
+    // Only recompute for a null-snapshot row when strategies are actually registered — mirror the
+    // create path (`resolveChannelsFor`: `registeredChannels.length === 0 => null`). With zero
+    // strategies, `resolveEffectiveChannels` returns `[]` (never null); persisting that would HIDE
+    // the row (the visibility layer treats `[]` as "no channels"), so leave `channels` null and keep
+    // legacy all-channels back-compat instead.
+    if (persistedChannels == null && registeredStrategyIds.length > 0) {
       try {
-        debug('sending email', { recipientUserId: notification.recipientUserId })
-        await sendEmail({
-          to: recipient.email,
-          subject,
-          from: deliveryConfig.strategies.email.from,
-          replyTo: deliveryConfig.strategies.email.replyTo,
-          react: NotificationEmail({
-            title,
-            body,
-            actions: actionLinks,
-            panelUrl: panelLink,
-            copy,
-          }),
+        const typeOverrides = (
+          await getNotificationTypeOverrides(em as EntityManager, notification.tenantId, [notification.type])
+        ).get(notification.type)
+        targetChannels = await resolveEffectiveChannels({
+          typeId: notification.type,
+          type: getNotificationType(notification.type),
+          scope: { tenantId: notification.tenantId, userId: notification.recipientUserId },
+          targetChannels: null,
+          registeredChannels: registeredStrategyIds,
+          preferences: resolveNotificationPreferenceService({ resolve: ctx.resolve }),
+          channelsOverride: typeOverrides?.channels ?? null,
+          nonOptOutOverride: typeOverrides?.nonOptOut ?? null,
         })
-      } catch (error) {
-        logger.error('Email delivery failed', { err: error })
+      } catch (err) {
+        // Fail CLOSED, not open. Falling back to `null` here means "deliver EVERY registered channel"
+        // — which now includes push and email — for a type the user may have opted out of, so a
+        // transient overrides/preference-service blip would leak a push/email on opt-out. Re-throw
+        // instead: this subscriber is `persistent` (retried with backoff) and the recompute runs
+        // BEFORE any strategy delivers, so the retry recomputes the correct target set with no
+        // double-send. In-app visibility is unaffected meanwhile — the row's `channels` stays null,
+        // which the visibility layer already treats as "visible everywhere".
+        logger.error('failed to recompute delivery channels; retrying via persistent subscriber', {
+          notificationId: notification.id,
+          type: notification.type,
+          err,
+        })
+        throw err
+      }
+    }
+    // Persist the recomputed set back onto a null-channels row so the in-app
+    // VISIBILITY path (bell/inbox/unread — see notificationVisibility.ts) reads
+    // the same authoritative target the DELIVERY gate just applied. Without this
+    // the row stays `null` ⇒ "visible everywhere", so a notification suppressed
+    // from in_app by the user's opt-out would still surface in the bell while
+    // delivery correctly skipped it. `targetChannels` is null (skip persist) only
+    // when no strategies are registered or the recompute fell back — both keep the
+    // row null for legacy all-channels back-compat. `channels` is a plaintext JSONB
+    // column, so a forked nativeUpdate avoids the shared UoW.
+    if (persistedChannels == null && targetChannels != null) {
+      try {
+        await (em as EntityManager)
+          .fork()
+          .nativeUpdate(
+            Notification,
+            { id: notification.id, tenantId: notification.tenantId },
+            { channels: targetChannels },
+          )
+      } catch (err) {
+        debug('failed to persist recomputed channels', err)
       }
     }
-
-    const strategyConfigs = deliveryConfig.strategies.custom ?? {}
-    const strategies = getNotificationDeliveryStrategies()
     for (const strategy of strategies) {
+      if (targetChannels && !targetChannels.includes(strategy.id)) {
+        debug('channel not targeted', strategy.id)
+        continue
+      }
       const strategyConfig = strategyConfigs[strategy.id]
       const enabled = strategyConfig?.enabled ?? strategy.defaultEnabled ?? false
       if (!enabled) {
-        debug('custom delivery disabled', strategy.id)
+        debug('delivery disabled', strategy.id)
+        continue
+      }
+      if (strategy.supports && !strategy.supports(notification)) {
+        debug('strategy does not support notification', strategy.id)
         continue
       }
+      const context: NotificationDeliveryContext = {
+        notification,
+        recipient,
+        title,
+        body,
+        panelUrl,
+        panelLink,
+        actionLinks,
+        deliveryConfig,
+        config: strategyConfig ?? {},
+        resolve: ctx.resolve,
+        t,
+      }
       try {
-        await strategy.deliver({
-          notification,
-          recipient,
-          title,
-          body,
-          panelUrl,
-          panelLink,
-          actionLinks,
-          deliveryConfig,
-          config: strategyConfig ?? {},
-          resolve: ctx.resolve,
-          t,
-        })
+        if (strategy.isConfigured && !(await strategy.isConfigured(context))) {
+          debug('strategy not configured', strategy.id)
+          continue
+        }
+        await strategy.deliver(context)
       } catch (error) {
         logger.error('Delivery strategy failed', { strategyId: strategy.id, err: error })
       }

package/src/modules/notifications/subscribers/sync-notification-types.ts

@@ -0,0 +1,18 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { TYPE_REGISTRY_SYNC_EVENT } from '../events'
+import { syncNotificationTypes } from '../lib/notification-type-registry'
+
+export const metadata = {
+  event: TYPE_REGISTRY_SYNC_EVENT,
+  persistent: true,
+  id: 'notifications:sync-notification-types',
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handler(_payload: unknown, ctx: ResolverContext): Promise<void> {
+  const em = ctx.resolve<EntityManager>('em')
+  await syncNotificationTypes(em, { force: true })
+}

package/src/modules/notifications/widgets/injection/profile-preferences-menu/widget.ts

@@ -0,0 +1,35 @@
+import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'
+import type { InjectionMenuItemWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+/**
+ * Adds a "Notification Preferences" entry to the top-right profile dropdown,
+ * next to "My communication channels". The per-user preferences page
+ * (`/backend/profile/notification-preferences`) is `pageContext: 'profile'`, so
+ * it is excluded from the main sidebar and otherwise only reachable via the
+ * profile-mode sidebar or a direct URL — this gives it a discoverable entry.
+ * Mirrors `communication_channels.injection.profile-channels-menu`.
+ *
+ * Feature-gated on `notifications.manage_preferences` (the same guard as the
+ * page), so users who cannot edit preferences don't see a dead link. Wildcard
+ * grants (`notifications.*`, `*`) are honored by the menu filter's
+ * wildcard-aware matcher.
+ */
+const widget: InjectionMenuItemWidget = {
+  metadata: {
+    id: 'notifications.injection.profile-preferences-menu',
+    title: 'Notification preferences profile menu item',
+  },
+  menuItems: [
+    {
+      id: 'notification-preferences-profile-link',
+      labelKey: 'notifications.preferences.pageTitle',
+      label: 'Notification Preferences',
+      icon: 'Bell',
+      href: '/backend/profile/notification-preferences',
+      features: ['notifications.manage_preferences'],
+      placement: { position: InjectionPosition.After, relativeTo: 'change-password' },
+    },
+  ],
+}
+
+export default widget

package/src/modules/notifications/widgets/injection-table.ts

@@ -0,0 +1,18 @@
+import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'
+
+/**
+ * Profile dropdown (top-right avatar): a discoverable entry to the per-user
+ * notification-preferences page, placed directly under "Change Password" —
+ * the same pattern `communication_channels` uses for its per-user
+ * channel-connect page.
+ */
+export const injectionTable: ModuleInjectionTable = {
+  'menu:topbar:profile-dropdown': [
+    {
+      widgetId: 'notifications.injection.profile-preferences-menu',
+      priority: 90,
+    },
+  ],
+}
+
+export default injectionTable

package/src/modules/push_notifications/AGENTS.md

@@ -0,0 +1,92 @@
+# push_notifications Module — Agent Guidelines
+
+Push delivery **rails**. Owns the delivery log, the `push` notification delivery strategy, and the
+`send-push` worker. It does **not** own device tokens (that's `devices`), per-user opt-out (that's
+`notifications`), or provider credentials/transport (that's the `communication_channels` hub +
+FCM/APNs/Expo channel packages). Spec: `.ai/specs/2026-04-28-push-notifications-and-devices.md` (Module 3).
+
+## Architecture
+
+- **Strategy** (`lib/push-delivery-strategy.ts`) registers via the notifications `delivery-strategies`
+  generator plugin (export `deliveryStrategies` from `notifications.delivery-strategies.ts`). It runs
+  inside the persistent `notifications:deliver` subscriber and only enqueues — the actual send happens
+  in the worker so a slow provider never blocks notification creation.
+- **Worker** (`workers/send-push.worker.ts` → `lib/push-delivery.ts`) atomically claims the row
+  (`pending` → `sending`, so a redelivered at-least-once job is processed once), resolves the tenant push
+  `CommunicationChannel` + hub adapter (`channelAdapterRegistry`) + creds (`integrationCredentialsService`)
+  and calls `convertOutbound` → `sendMessage` — the `communication_channels` `test-send` flow. Retries
+  transient failures with exponential backoff + jitter (3 attempts, shared
+  `@open-mercato/shared/lib/delivery/retry`), records `next_retry_at`, and marks the row `expired` once
+  retries are exhausted (vs `failed` for terminal errors); on the `unregistered` sentinel soft-deletes the device.
+- **Queue** (`lib/queue.ts`) mirrors the webhooks queue: `createModuleQueue` + `enqueuePushDelivery` +
+  a local-worker bootstrap for dev/test (`QUEUE_STRATEGY !== 'async'`).
+- **Reaper** (`lib/push-reaper.ts` → `workers/reclaim-stuck.worker.ts`) recovers rows stranded in
+  `sending` by a crashed worker — the send-path claim only matches `pending`, so such a row has no
+  outstanding job and would never terminate. A per-tenant `@open-mercato/scheduler` interval entry
+  (registered best-effort in `setup.ts`, mirroring the `communication_channels` poll-tick) fires the
+  tick; rows still in `sending` past `OM_PUSH_STUCK_RECLAIM_MINUTES` (default 5) are re-opened +
+  re-enqueued when attempts remain, else finalized `expired`. Each transition is an atomic
+  `nativeUpdate` guarded on `status='sending'` + still-stale `updated_at`, so overlapping ticks or a
+  worker that re-claimed the row never re-open an active delivery. The per-tick scan is batch-bounded
+  by `OM_PUSH_STUCK_RECLAIM_BATCH_LIMIT` (default 500, oldest-stuck first) so a stranded backlog from a
+  provider/queue outage cannot load an unbounded row set into memory in one tick — the remainder drains
+  on subsequent ticks (mirrors the receipt reaper's `OM_PUSH_RECEIPT_BATCH_LIMIT`).
+- **Fan-out** (`lib/push-fanout.ts`, `fanOutPushDeliveries`) is the shared device-resolution + provider
+  routing + delivery-row insert + enqueue. The strategy (visible notifications) and `sendCustomPush`
+  call it; it stays preference-agnostic. Its channel/device short-circuits (no push channel / no
+  devices / no provider match → `{ enqueued: 0 }`) are push's technical `isConfigured` equivalent and
+  remain the authoritative "is push set up for this tenant/recipient" check.
+- **Opt-out is enforced upstream, once (Phase 7).** The `push` strategy no longer calls
+  `isChannelEnabled`/checks `nonOptOut`; the notifications create-time gate (`shouldDeliver`) already
+  resolved per-channel opt-out into `notification.channels`, and the dispatcher only invokes this
+  strategy when `push ∈ channels`. The strategy still reads the **type** for `silent` (delivery style).
+- **Silent push** is **not** a separate API — it is just a notification whose **type** is declared
+  `silent: true` (`NotificationTypeDefinition.silent`), created through the **normal**
+  `notificationService.create()` flow (`create()` → `notifications:deliver` subscriber → the `push`
+  strategy). The strategy derives `silent` from the type, sends a content-available (data-only) push,
+  and skips user-facing copy; the in-app `Notification` row is still created and per-channel
+  preferences still apply (now enforced by the notifications create-time gate, not the strategy) — to
+  make a silent type always fire, declare it `nonOptOut: true`. There is no `sendSilentPush` helper.
+- **Admin custom push** (`lib/send-custom-push.ts`, exposed in DI as `pushNotificationService`) is a
+  one-off **visible** push with literal title/body that fans out directly (no in-app row, no email, no
+  preference check); it backs `api/custom-send/route.ts`.
+- **Flexible payload.** A notification's optional `data` (arbitrary app-readable map, also exposed to
+  in-app clients) and `pushOptions` (flat `sound`/`badge`/`image`/`priority`/`channelId`/`body` map, both
+  from the `notifications` module) ride the push envelope `raw`. The adapters map `pushOptions` onto each
+  provider's native message and branch on `silent`; see `communication_channels/lib/push-envelope.ts`
+  (`PushOptions`, `readPushEnvelope`, `resolvePushBody`).
+
+## Always
+
+- Never export `OM_PUSH_FAKE_PROVIDERS` by hand and point `TC-PUSH-004+` / `TC-CHANNEL-PUSH-005..007` at a
+  live server that does not itself have it. Their `.meta.ts` gate skips them when the flag is absent from the
+  test process, which is the protection you want; exporting it defeats that gate. The fake swaps the provider
+  SDK client in `di.ts` `register()`, so whichever process claims the delivery job must have the flag — a dev
+  server without it runs its in-process worker against the **real** provider, and on real credentials that
+  means a real push to the recipient's real devices. Start the server with `OM_PUSH_FAKE_PROVIDERS=1`, or use
+  the ephemeral harness, which sets it for both the app and the drain child.
+- Resolve cross-module entities (`UserDevice`, `CommunicationChannel`) via DI tokens (`ctx.resolve(...)`),
+  not import-time references, to stay decoupled.
+- Keep `push_token` a secret: persist only `provider` + last-8 `token_snapshot`; never expose a full token
+  in any API/UI/log.
+- Soft-delete an `unregistered` device through the `devices.user_devices.deactivate` command (system ctx:
+  `auth: null, systemActor: true`) — never mutate the `devices` table directly.
+- Keep the `unregistered` sentinel identical across provider adapters (`result.metadata.unregistered ===
+  true` or `result.error === 'device_unregistered'`) so the worker's soft-delete fires uniformly.
+- Keep the delivery log append-only (status transitions only); it is intentionally optimistic-lock-exempt.
+- To send a silent push, declare the notification type `silent: true` (in its module's
+  `notifications.ts`) and create it via the normal `notificationService.create()` — the `push`
+  strategy turns it into a content-available wake-up. Do not add a bespoke silent-send path.
+
+## Never
+
+- Never add token-management or self-serve notification CRUD here (device fields live in `devices`).
+- Never introduce a `PushProvider` interface — the hub `ChannelAdapter` registry is the provider seam;
+  real providers are separate `channel-*` packages (Phase 4).
+
+## Validation
+
+```bash
+yarn workspace @open-mercato/core test -- push_notifications
+yarn workspace @open-mercato/core build
+```

package/src/modules/push_notifications/acl.ts

@@ -0,0 +1,9 @@
+export const features = [
+  // Admin observability over the push delivery log. There are no self-serve push features:
+  // device/token lifecycle lives in the `devices` module, per-user opt-out in `notifications`.
+  { id: 'push_notifications.view_deliveries', title: 'View push delivery log', module: 'push_notifications' },
+  // Admin one-off custom push send (bypasses opt-out via the nonOptOut admin.custom_message type).
+  { id: 'push_notifications.send_custom', title: 'Send custom push notifications', module: 'push_notifications' },
+]
+
+export default features