test(service-messaging): pin the push device registry over sys_user_device (red)

Claude-Session: https://claude.ai/code/session_01ADHkmRD9KKqvTU3THnute6
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/services/service-messaging/src/device-registry.integration.test.ts

@@ -0,0 +1,228 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The push device registry (ADR-0012 §6): `MessagingService`'s four
+ * `INotificationService` device members over `sys_user_device`, pinned on a
+ * real `ObjectQL` over `SqlDriver` (better-sqlite3) with the real `sys_user`.
+ *
+ * What the contract (`@objectstack/spec/contracts` `INotificationService`)
+ * and spec's three rules (`system/push-device.zod.ts`) owe, one case each:
+ *
+ *  - register, then refresh the same `deviceId`: one row, token and
+ *    `last_seen_at` moved;
+ *  - a registration without `deviceId` mints one; the same user registering
+ *    the same token again without it gets the SAME id back, never a second row;
+ *  - a second user registering the token takes it over, and the first user's
+ *    row for it is removed (rule b);
+ *  - unregister by another user answers `NOT_FOUND` (404) and the row
+ *    survives; the owner's unregister removes it;
+ *  - `invalidateDeviceToken` keeps the row, disabled with its time (rule c);
+ *    a later registration of the same device re-enables it and clears the
+ *    time; a token nobody holds is a no-op;
+ *  - the vendor derives from the platform, and a `web` registration without
+ *    one is refused `VALIDATION_FAILED` at `vendor`, storing nothing;
+ *  - `listDevices` answers only the caller's devices, newest first;
+ *  - the database refuses a second holder of a token (the unique index), and
+ *    two concurrent registrations of one token end with one row.
+ *
+ * Refusals assert `code` AND `status` (ADR-0112).
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { SysUser } from '@objectstack/platform-objects';
+import { validationFailureDetails } from '@objectstack/types';
+import { UserDevice } from './objects/user-device.object.js';
+import { MessagingService } from './messaging-service.js';
+import { USER_DEVICE_OBJECT } from './device-registry.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
+
+const SYS = { context: { isSystem: true } } as any;
+const silent: any = { debug() {}, info() {}, warn() {}, error() {}, fatal() {}, child() { return silent; } };
+
+let engine: ObjectQL | undefined;
+
+afterEach(async () => {
+    try { await engine?.destroy(); } catch { /* noop */ }
+    engine = undefined;
+});
+
+/** A clock the test moves, so `last_seen_at` ordering is not a race. */
+function clock() {
+    let t = Date.parse('2026-11-02T10:00:00.000Z');
+    return { now: () => new Date(t).toISOString(), tick: (ms = 60_000) => { t += ms; } };
+}
+
+async function boot() {
+    const driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+    const ql = new ObjectQL({ logger: silent });
+    ql.registerDriver(driver, true);
+    await ql.init();
+    ql.registry.registerObject(SysUser as any, '@objectstack/plugin-auth');
+    ql.registry.registerObject(UserDevice as any, '@objectstack/service-messaging');
+    await ql.syncSchemas();
+    await installDefaultOrganization(ql as any);
+    engine = ql;
+    const time = clock();
+    const service = new MessagingService({ logger: silent, getData: () => ql as any, now: time.now });
+    const alice = String((await ql.insert('sys_user', { name: 'Alice', email: 'alice@device.test' }, SYS)).id);
+    const bob = String((await ql.insert('sys_user', { name: 'Bob', email: 'bob@device.test' }, SYS)).id);
+    const rows = async (where: Record<string, unknown> = {}) =>
+        (await ql.find(USER_DEVICE_OBJECT, { where }, SYS)) as Array<Record<string, any>>;
+    return { ql, service, time, alice, bob, rows };
+}
+
+async function thrown(p: Promise<unknown>): Promise<any> {
+    try {
+        await p;
+    } catch (e) {
+        return e;
+    }
+    throw new Error('the call resolved; a refusal was expected');
+}
+
+describe('push device registry: INotificationService device members over sys_user_device', () => {
+    it('register, then refresh the same deviceId: one row, token and last_seen_at updated', async () => {
+        const { service, time, alice, rows } = await boot();
+        const first = await service.registerDevice(alice, { token: 'tok-1', platform: 'ios', deviceId: 'dev-a', name: 'iPhone' });
+        expect(first).toEqual({ deviceId: 'dev-a', success: true });
+        const [before] = await rows({ user_id: alice });
+
+        time.tick();
+        const again = await service.registerDevice(alice, { token: 'tok-2', platform: 'ios', deviceId: 'dev-a', locale: 'zh-CN' });
+        expect(again).toEqual({ deviceId: 'dev-a', success: true });
+
+        const after = await rows({ user_id: alice });
+        expect(after).toHaveLength(1);
+        expect(after[0].id).toBe(before.id);
+        expect(after[0].token).toBe('tok-2');
+        expect(after[0].locale).toBe('zh-CN');
+        expect(new Date(after[0].last_seen_at).getTime()).toBeGreaterThan(new Date(before.last_seen_at).getTime());
+    });
+
+    it('mints a deviceId when absent, and answers the same id for the same token without one', async () => {
+        const { service, alice, rows } = await boot();
+        const minted = await service.registerDevice(alice, { token: 'tok-m', platform: 'android' });
+        expect(minted.success).toBe(true);
+        expect(minted.deviceId).toMatch(/\S/);
+
+        const cleared = await service.registerDevice(alice, { token: 'tok-m', platform: 'android' });
+        expect(cleared.deviceId).toBe(minted.deviceId);
+        expect(await rows({ token: 'tok-m' })).toHaveLength(1);
+    });
+
+    it('a second user registering the token takes it over; the first user\'s row for it is removed', async () => {
+        const { service, alice, bob, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-shared', platform: 'ios', deviceId: 'alice-phone' });
+        await service.registerDevice(alice, { token: 'tok-other', platform: 'ios', deviceId: 'alice-tablet' });
+
+        const taken = await service.registerDevice(bob, { token: 'tok-shared', platform: 'ios', deviceId: 'bob-phone' });
+        expect(taken).toEqual({ deviceId: 'bob-phone', success: true });
+
+        const holders = await rows({ token: 'tok-shared' });
+        expect(holders).toHaveLength(1);
+        expect(String(holders[0].user_id)).toBe(bob);
+        expect((await rows({ user_id: alice })).map((r) => r.device_id)).toEqual(['alice-tablet']);
+        expect((await service.listDevices(alice)).map((d) => d.deviceId)).toEqual(['alice-tablet']);
+    });
+
+    it('a token this user holds under another deviceId moves to the named device; the stale row goes', async () => {
+        const { service, alice, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-x', platform: 'ios', deviceId: 'old-install' });
+        await service.registerDevice(alice, { token: 'tok-x', platform: 'ios', deviceId: 'new-install' });
+        expect((await rows({ user_id: alice })).map((r) => r.device_id)).toEqual(['new-install']);
+    });
+
+    it('unregister by a non-owner is NOT_FOUND (404) and the row survives; the owner removes it', async () => {
+        const { service, alice, bob, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-u', platform: 'android', deviceId: 'alice-dev' });
+
+        const refused = await thrown(service.unregisterDevice(bob, 'alice-dev'));
+        expect(refused.code).toBe('NOT_FOUND');
+        expect(refused.status).toBe(404);
+        expect(await rows({ device_id: 'alice-dev' })).toHaveLength(1);
+
+        const unknown = await thrown(service.unregisterDevice(alice, 'no-such-device'));
+        expect(unknown.code).toBe('NOT_FOUND');
+        expect(unknown.status).toBe(404);
+
+        expect(await service.unregisterDevice(alice, 'alice-dev')).toEqual({ success: true });
+        expect(await rows({ device_id: 'alice-dev' })).toHaveLength(0);
+    });
+
+    it('invalidateDeviceToken keeps the row disabled with its time; re-registration re-enables and clears it', async () => {
+        const { service, time, alice, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-dead', platform: 'ios', deviceId: 'dev-d' });
+
+        time.tick();
+        await service.invalidateDeviceToken('tok-dead');
+        const [dead] = await rows({ device_id: 'dev-d' });
+        expect(dead.enabled).toBe(false);
+        expect(dead.invalidated_at).toBeTruthy();
+        const [listed] = await service.listDevices(alice);
+        expect(listed.enabled).toBe(false);
+        expect(listed.invalidatedAt).toBe(time.now());
+
+        // A token nobody holds is a no-op.
+        await expect(service.invalidateDeviceToken('tok-nobody')).resolves.toBeUndefined();
+
+        time.tick();
+        await service.registerDevice(alice, { token: 'tok-dead', platform: 'ios', deviceId: 'dev-d' });
+        const [revived] = await rows({ device_id: 'dev-d' });
+        expect(revived.id).toBe(dead.id);
+        expect(revived.enabled).toBe(true);
+        expect(revived.invalidated_at ?? null).toBeNull();
+        const [relisted] = await service.listDevices(alice);
+        expect(relisted.enabled).toBe(true);
+        expect(relisted).not.toHaveProperty('invalidatedAt');
+    });
+
+    it('derives the vendor from the platform, and refuses a web registration without one', async () => {
+        const { service, alice, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-ios', platform: 'ios' });
+        await service.registerDevice(alice, { token: 'tok-and', platform: 'android' });
+        await service.registerDevice(alice, { token: 'tok-web', platform: 'web', vendor: 'fcm' });
+        const vendorOf = async (token: string) => (await rows({ token }))[0]?.vendor;
+        expect(await vendorOf('tok-ios')).toBe('apns');
+        expect(await vendorOf('tok-and')).toBe('fcm');
+        expect(await vendorOf('tok-web')).toBe('fcm');
+
+        const refused = await thrown(service.registerDevice(alice, { token: 'tok-web-2', platform: 'web' }));
+        const details = validationFailureDetails(refused);
+        expect(details?.code).toBe('VALIDATION_FAILED');
+        expect(details?.fields).toEqual([expect.objectContaining({ field: 'vendor', code: 'required' })]);
+        expect(await rows({ token: 'tok-web-2' })).toHaveLength(0);
+    });
+
+    it('listDevices answers only the caller\'s devices, newest last_seen_at first', async () => {
+        const { service, time, alice, bob } = await boot();
+        await service.registerDevice(alice, { token: 't1', platform: 'ios', deviceId: 'older' });
+        time.tick();
+        await service.registerDevice(alice, { token: 't2', platform: 'android', deviceId: 'newer', appId: 'ai.objectos.app' });
+        await service.registerDevice(bob, { token: 't3', platform: 'ios', deviceId: 'bobs' });
+
+        const mine = await service.listDevices(alice);
+        expect(mine.map((d) => d.deviceId)).toEqual(['newer', 'older']);
+        expect(mine[0]).toMatchObject({ userId: alice, vendor: 'fcm', token: 't2', platform: 'android', appId: 'ai.objectos.app', enabled: true });
+        expect(mine.every((d) => d.userId === alice)).toBe(true);
+    });
+
+    it('the database refuses a second holder of a token, and concurrent registrations end with one row', async () => {
+        const { ql, service, alice, bob, rows } = await boot();
+        await service.registerDevice(alice, { token: 'tok-race', platform: 'ios', deviceId: 'a1' });
+
+        // The unique index itself: a direct second holder is refused.
+        const direct = await thrown(ql.insert(USER_DEVICE_OBJECT, {
+            id: 'manual', user_id: bob, device_id: 'b-manual', token: 'tok-race', vendor: 'apns', platform: 'ios', enabled: true,
+        }, SYS));
+        expect(String(direct?.message ?? direct)).toMatch(/unique|duplicate/i);
+
+        await Promise.all([
+            service.registerDevice(bob, { token: 'tok-race', platform: 'ios', deviceId: 'b1' }),
+            service.registerDevice(alice, { token: 'tok-race', platform: 'ios', deviceId: 'a2' }),
+            service.registerDevice(bob, { token: 'tok-race', platform: 'ios', deviceId: 'b2' }),
+        ]);
+        expect(await rows({ token: 'tok-race' })).toHaveLength(1);
+    });
+});

packages/services/service-messaging/src/objects/user-device.object.test.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `sys_user_device`'s declaration (ADR-0012 §6): system-owned and closed to
+ * the generic data API, no organization column (spec rule a), and the same
+ * platform vocabulary as the registration it stores.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { RegisterDeviceRequestSchema } from '@objectstack/spec/api';
+import { UserDeviceSchema } from '@objectstack/spec/system';
+import { UserDevice } from './user-device.object.js';
+
+describe('sys_user_device declaration', () => {
+    it('is closed to the generic data API: no method is exposed', () => {
+        expect(UserDevice.enable?.apiEnabled).toBe(false);
+        expect(UserDevice.enable?.apiMethods).toEqual([]);
+        expect(UserDevice.managedBy).toBe('engine-owned');
+    });
+
+    it('has no organization column and opts out of tenancy (a device belongs to a user)', () => {
+        expect(Object.keys(UserDevice.fields)).not.toContain('organization_id');
+        expect(UserDevice.tenancy).toEqual({ enabled: false });
+    });
+
+    it('stores the platform vocabulary the registration admits, no more and no less', () => {
+        const declared = (UserDevice.fields.platform as any).options.map((o: any) => (typeof o === 'string' ? o : o.value));
+        const admitted = (RegisterDeviceRequestSchema as any).shape.platform.options;
+        expect([...declared].sort()).toEqual([...admitted].sort());
+        expect((UserDeviceSchema as any).shape.platform.options.slice().sort()).toEqual([...admitted].sort());
+    });
+
+    it('carries the two unique indexes the registry relies on', () => {
+        expect(UserDevice.indexes).toEqual(expect.arrayContaining([
+            expect.objectContaining({ fields: ['user_id', 'device_id'], unique: 'global' }),
+            expect.objectContaining({ fields: ['token'], unique: 'global' }),
+        ]));
+    });
+});