From 23b071058efb775390ad04e619ea621f22d06ca5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 17:54:48 +0000 Subject: [PATCH 1/5] =?UTF-8?q?docs(spec):=20push=20vendor=20docblocks=20r?= =?UTF-8?q?ead=20ADR-0012=20=C2=A76.1,=20not=20alternate=20channel=20plugi?= =?UTF-8?q?ns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The push-config and push-device docblocks and the register-device-request test header still cited ADR-0012 §6 for "domestic vendors are alternate channel plugins". The amended ADR (§6.1) makes vendor a token type the hosted relay routes on, with the domestic vendors arriving behind the relay in phase 2. Comment text only. Claude-Session: https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa Co-authored-by: Claude --- .changeset/29960-push-vendor-docblocks.md | 10 ++++++++++ .../spec/src/api/register-device-request.test.ts | 5 +++-- packages/spec/src/system/push-config.zod.ts | 15 ++++++++++----- packages/spec/src/system/push-device.zod.ts | 5 +++-- 4 files changed, 26 insertions(+), 9 deletions(-) create mode 100644 .changeset/29960-push-vendor-docblocks.md diff --git a/.changeset/29960-push-vendor-docblocks.md b/.changeset/29960-push-vendor-docblocks.md new file mode 100644 index 00000000000..703058ee942 --- /dev/null +++ b/.changeset/29960-push-vendor-docblocks.md @@ -0,0 +1,10 @@ +--- +'@objectstack/spec': patch +--- + +docs(spec): the push vendor docblocks read ADR-0012 §6.1 as amended + +Clause-②: no +Metadata-protocol: none + +The `PushVendorSchema` docblock and the push transport and stored device docblocks (`system/push-config.zod.ts`, `system/push-device.zod.ts`) no longer say the domestic Android vendors plug in as alternate channel plugins. They now say what ADR-0012 §6.1 decides: `vendor` is the token type the hosted relay routes on, core ships `apns` and `fcm`, and phase 2 adds HMS / Honor, Xiaomi, OPPO and vivo behind the same relay, with no per-vendor plugin and no per-vendor channel. A new `PushVendorSchema` value is still a spec change made together with the relay's routing for that vendor. Comment text only: no schema, `.describe()`, export or default changes, and `PushVendorSchema` stays `apns | fcm`. diff --git a/packages/spec/src/api/register-device-request.test.ts b/packages/spec/src/api/register-device-request.test.ts index 634859e1675..54e1a06bcd6 100644 --- a/packages/spec/src/api/register-device-request.test.ts +++ b/packages/spec/src/api/register-device-request.test.ts @@ -4,8 +4,9 @@ // §6): it gains an optional `vendor`, `appId` and `locale`. Pure widening, so // the body every client sends today must keep parsing unchanged, and the new // members are optional. The one value the widening refuses is a vendor -// outside the pair core delivers through (`apns` / `fcm`); other vendors are -// alternate channel plugins (ADR-0012 §6), not values of this field. +// outside the pair core delivers through (`apns` / `fcm`); the domestic +// Android vendors arrive in phase 2 as further values of `PushVendorSchema`, +// routed by the hosted relay (ADR-0012 §6.1), not as channel plugins. import { describe, it, expect } from 'vitest'; import { diff --git a/packages/spec/src/system/push-config.zod.ts b/packages/spec/src/system/push-config.zod.ts index 662359ef7f4..c309a919195 100644 --- a/packages/spec/src/system/push-config.zod.ts +++ b/packages/spec/src/system/push-config.zod.ts @@ -82,16 +82,21 @@ import { strictObject } from '../shared/strict-object'; * it: the vendor blocks hold no secret to override, and each `credentialRef` * already names one. * - * Out of scope here: the other vendors ADR-0012 §6 routes to alternate - * channel plugins (HMS, Xiaomi, OPPO, vivo). + * Out of scope here: the domestic Android vendors (HMS / Honor, Xiaomi, OPPO, + * vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as further + * values of `vendor`, the token type the relay routes on; there is no + * per-vendor plugin and no per-vendor channel. */ /** * Push vendors core delivers through: `apns` (Apple) and `fcm` (Firebase). * - * Closed on purpose. ADR-0012 §6 plugs the domestic Android vendors in as - * alternate channel implementations, not as transports of this channel, so a - * new value here is a spec change made together with its transport. + * Closed on purpose. `vendor` is the token type the hosted relay routes on + * (ADR-0012 §6.1): phase 1 routes these two, and phase 2 adds the domestic + * Android vendors (HMS / Honor, Xiaomi, OPPO, vivo) behind the same relay, + * with no per-vendor plugin and no per-vendor channel. So a new value here is + * a spec change made together with its transport: the relay's routing for + * that vendor. */ export const PushVendorSchema = z.enum(['apns', 'fcm']) .describe('Push vendor core delivers through: apns (Apple Push Notification service) or fcm (Firebase Cloud Messaging HTTP v1)'); diff --git a/packages/spec/src/system/push-device.zod.ts b/packages/spec/src/system/push-device.zod.ts index 9fcde1a3b58..55f0c625e84 100644 --- a/packages/spec/src/system/push-device.zod.ts +++ b/packages/spec/src/system/push-device.zod.ts @@ -46,8 +46,9 @@ import { PUSH_SERVER_ORIGIN_MESSAGE, PUSH_SERVER_ORIGIN_PATTERN } from './push-s * row, and a later registration of the same device re-enables it and clears * `invalidatedAt`. * - * Narrowed from ADR-0012 §6: `vendor` is the core pair (`apns` | `fcm`; the - * domestic Android vendors plug in as alternate channel implementations) and + * Narrowed from the ADR-0012 §6 sketch: `vendor` is the core pair (`apns` | + * `fcm`; it is the token type the hosted relay routes on, and the domestic + * Android vendors join it in phase 2 behind the same relay, ADR-0012 §6.1) and * `platform` is the registration's own three (`ios` | `android` | `web`). */ export const UserDeviceSchema = lazySchema(() => z.object({ From 17d0a52118d1d153e68e5eccbca135251c5225c3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 17:59:35 +0000 Subject: [PATCH 2/5] docs(spec): regenerate the push-config reference page Claude-Session: https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa Co-authored-by: Claude --- content/docs/references/system/push-config.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/docs/references/system/push-config.mdx b/content/docs/references/system/push-config.mdx index 5ccd654f6eb..7fc6d449ab5 100644 --- a/content/docs/references/system/push-config.mdx +++ b/content/docs/references/system/push-config.mdx @@ -82,8 +82,10 @@ constructor instead. No `OS_PUSH_*` environment variable carries any of it: the vendor blocks hold no secret to override, and each `credentialRef` already names one. -Out of scope here: the other vendors ADR-0012 §6 routes to alternate -channel plugins (HMS, Xiaomi, OPPO, vivo). +Out of scope here: the domestic Android vendors (HMS / Honor, Xiaomi, OPPO, +vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as further +values of `vendor`, the token type the relay routes on; there is no +per-vendor plugin and no per-vendor channel. **Source:** `packages/spec/src/system/push-config.zod.ts` From 28f2cc1f737a2f1900429c761135023f4045fdba Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 18:58:37 +0000 Subject: [PATCH 3/5] docs(push): the push service page reads the domestic vendors as relay token types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page still said the other Android vendors plug in as separate channel implementations, the ADR-0012 §6 reading the amendment retired. Core ships apns and fcm; the domestic vendors are planned behind the hosted relay as further vendor values, not as plugins or channels. Claude-Session: https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa Co-authored-by: Claude --- content/docs/kernel/runtime-services/push-service.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/docs/kernel/runtime-services/push-service.mdx b/content/docs/kernel/runtime-services/push-service.mdx index 4c977e6d152..271a4fbc38f 100644 --- a/content/docs/kernel/runtime-services/push-service.mdx +++ b/content/docs/kernel/runtime-services/push-service.mdx @@ -85,8 +85,10 @@ service its server gets. Each vendor block is optional, and at least one is required. A vendor with no block is a vendor this deployment does not push to; devices registered on it are -skipped. Other Android vendors (HMS, Xiaomi, OPPO, vivo) are not transports of -this service: they plug in as separate channel implementations. +skipped. Only `apns` and `fcm` ship today. The other Android vendors (HMS / +Honor, Xiaomi, OPPO, vivo) are planned for a later phase behind the hosted relay +(below), as further values of `vendor`, the token type the relay routes on, and +not as plugins or channels of their own. ### Credential references From 86e42da79a31f432165acb58298cfc76d7394dfc Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 20:11:26 +0000 Subject: [PATCH 4/5] docs(spec): vendor is the token type the sender routes on; five-way vendor list Contract-review should-fixes: the direct transport routes on vendor today (PushService.send picks transports[message.vendor]); the hosted relay, the default, does once served. The domestic vendor list uses the ADR's separators, HMS / Honor / Xiaomi / OPPO / vivo. Claude-Session: https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa Co-authored-by: Claude --- .changeset/29960-push-vendor-docblocks.md | 2 +- .../kernel/runtime-services/push-service.mdx | 7 ++++--- packages/spec/src/system/push-config.zod.ts | 17 +++++++++-------- packages/spec/src/system/push-device.zod.ts | 6 ++++-- 4 files changed, 18 insertions(+), 14 deletions(-) diff --git a/.changeset/29960-push-vendor-docblocks.md b/.changeset/29960-push-vendor-docblocks.md index 703058ee942..3d5038e5c02 100644 --- a/.changeset/29960-push-vendor-docblocks.md +++ b/.changeset/29960-push-vendor-docblocks.md @@ -7,4 +7,4 @@ docs(spec): the push vendor docblocks read ADR-0012 §6.1 as amended Clause-②: no Metadata-protocol: none -The `PushVendorSchema` docblock and the push transport and stored device docblocks (`system/push-config.zod.ts`, `system/push-device.zod.ts`) no longer say the domestic Android vendors plug in as alternate channel plugins. They now say what ADR-0012 §6.1 decides: `vendor` is the token type the hosted relay routes on, core ships `apns` and `fcm`, and phase 2 adds HMS / Honor, Xiaomi, OPPO and vivo behind the same relay, with no per-vendor plugin and no per-vendor channel. A new `PushVendorSchema` value is still a spec change made together with the relay's routing for that vendor. Comment text only: no schema, `.describe()`, export or default changes, and `PushVendorSchema` stays `apns | fcm`. +The `PushVendorSchema` docblock and the push transport and stored device docblocks (`system/push-config.zod.ts`, `system/push-device.zod.ts`) no longer say the domestic Android vendors plug in as alternate channel plugins. They now say what ADR-0012 §6.1 decides: `vendor` is the token type the sender routes on (the direct transport today, the hosted relay, the default, once served), core ships `apns` and `fcm`, and phase 2 adds HMS / Honor / Xiaomi / OPPO / vivo behind the relay, with no per-vendor plugin and no per-vendor channel. A new `PushVendorSchema` value is still a spec change made together with the relay's routing for that vendor. Comment text only: no schema, `.describe()`, export or default changes, and `PushVendorSchema` stays `apns | fcm`. diff --git a/content/docs/kernel/runtime-services/push-service.mdx b/content/docs/kernel/runtime-services/push-service.mdx index 271a4fbc38f..c2833d010bd 100644 --- a/content/docs/kernel/runtime-services/push-service.mdx +++ b/content/docs/kernel/runtime-services/push-service.mdx @@ -86,9 +86,10 @@ service its server gets. Each vendor block is optional, and at least one is required. A vendor with no block is a vendor this deployment does not push to; devices registered on it are skipped. Only `apns` and `fcm` ship today. The other Android vendors (HMS / -Honor, Xiaomi, OPPO, vivo) are planned for a later phase behind the hosted relay -(below), as further values of `vendor`, the token type the relay routes on, and -not as plugins or channels of their own. +Honor / Xiaomi / OPPO / vivo) are planned for a later phase behind the hosted +relay (below), as further values of `vendor`, the token type the sender routes +on (this service's transports today, the relay once it is served), and not as +plugins or channels of their own. ### Credential references diff --git a/packages/spec/src/system/push-config.zod.ts b/packages/spec/src/system/push-config.zod.ts index c309a919195..cbda375977c 100644 --- a/packages/spec/src/system/push-config.zod.ts +++ b/packages/spec/src/system/push-config.zod.ts @@ -82,19 +82,20 @@ import { strictObject } from '../shared/strict-object'; * it: the vendor blocks hold no secret to override, and each `credentialRef` * already names one. * - * Out of scope here: the domestic Android vendors (HMS / Honor, Xiaomi, OPPO, - * vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as further - * values of `vendor`, the token type the relay routes on; there is no - * per-vendor plugin and no per-vendor channel. + * Out of scope here: the domestic Android vendors (HMS / Honor / Xiaomi / + * OPPO / vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as + * further values of `vendor`, the token type the sender routes on; there is + * no per-vendor plugin and no per-vendor channel. */ /** * Push vendors core delivers through: `apns` (Apple) and `fcm` (Firebase). * - * Closed on purpose. `vendor` is the token type the hosted relay routes on - * (ADR-0012 §6.1): phase 1 routes these two, and phase 2 adds the domestic - * Android vendors (HMS / Honor, Xiaomi, OPPO, vivo) behind the same relay, - * with no per-vendor plugin and no per-vendor channel. So a new value here is + * Closed on purpose. `vendor` is the token type the sender routes on: the + * direct transport today, the hosted relay (the default) once served (ADR-0012 + * §6.1). Phase 1 routes these two, and phase 2 adds the domestic Android + * vendors (HMS / Honor / Xiaomi / OPPO / vivo) behind the relay, with no + * per-vendor plugin and no per-vendor channel. So a new value here is * a spec change made together with its transport: the relay's routing for * that vendor. */ diff --git a/packages/spec/src/system/push-device.zod.ts b/packages/spec/src/system/push-device.zod.ts index 55f0c625e84..3e39a9d8c29 100644 --- a/packages/spec/src/system/push-device.zod.ts +++ b/packages/spec/src/system/push-device.zod.ts @@ -47,8 +47,10 @@ import { PUSH_SERVER_ORIGIN_MESSAGE, PUSH_SERVER_ORIGIN_PATTERN } from './push-s * `invalidatedAt`. * * Narrowed from the ADR-0012 §6 sketch: `vendor` is the core pair (`apns` | - * `fcm`; it is the token type the hosted relay routes on, and the domestic - * Android vendors join it in phase 2 behind the same relay, ADR-0012 §6.1) and + * `fcm`; it is the token type the sender routes on: the direct transport + * today, the hosted relay (the default) once served, and the domestic Android + * vendors (HMS / Honor / Xiaomi / OPPO / vivo) join it in phase 2 behind the + * relay, ADR-0012 §6.1) and * `platform` is the registration's own three (`ios` | `android` | `web`). */ export const UserDeviceSchema = lazySchema(() => z.object({ From 52082426b060c2f3420a3a01fb69baa60080b842 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 20:13:10 +0000 Subject: [PATCH 5/5] docs(spec): regenerate the push-config reference page Claude-Session: https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa Co-authored-by: Claude --- content/docs/references/system/push-config.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/references/system/push-config.mdx b/content/docs/references/system/push-config.mdx index 7fc6d449ab5..c79d137a31f 100644 --- a/content/docs/references/system/push-config.mdx +++ b/content/docs/references/system/push-config.mdx @@ -82,10 +82,10 @@ constructor instead. No `OS_PUSH_*` environment variable carries any of it: the vendor blocks hold no secret to override, and each `credentialRef` already names one. -Out of scope here: the domestic Android vendors (HMS / Honor, Xiaomi, OPPO, -vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as further -values of `vendor`, the token type the relay routes on; there is no -per-vendor plugin and no per-vendor channel. +Out of scope here: the domestic Android vendors (HMS / Honor / Xiaomi / +OPPO / vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as +further values of `vendor`, the token type the sender routes on; there is +no per-vendor plugin and no per-vendor channel. **Source:** `packages/spec/src/system/push-config.zod.ts`