feat(spec): push relay transport — transport: relay | direct on PushServiceConfigSchema, and the server-to-relay wire shape

.changeset/29816-push-relay-transport.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): the push channel's hosted relay transport — `PushServiceConfigSchema` becomes `transport: 'relay' | 'direct'`, with the relay as the default, and the server-to-relay wire shape is declared (`api/push-relay.zod.ts`)
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+Nothing here is read or served yet: every new or touched schema keeps or carries a `[PLANNED — not yet read]` or `[PLANNED — not yet served]` marker, and no stack key, route or reader is added. Every push configuration that parsed before still parses.
+
+- **`PushServiceConfigSchema`** is now a discriminated union on `transport`, built from two strict blocks:
+  - `PushRelayTransportConfigSchema`, `{ transport: 'relay', endpoint? }`, the default. The hosted relay holds the APNs and FCM credentials of the store-published app and authenticates the server by its cloud binding credential, so the block carries no credential. `endpoint` is an https URL for a staging relay; absent means the production relay. A vendor block or a credential key (`credentialRef`, `token`, `apiKey`, …) written into a relay block is refused by name, pointing at `transport: 'direct'`.
+  - `PushDirectTransportConfigSchema`, `{ transport: 'direct', apns?, fcm? }`: the shape this schema had, for a white-label build signed with the operator's own credentials. It needs at least one vendor block, so a direct block with no `credentialRef` is refused; `endpoint` on it is refused, pointing at the relay.
+  - A block without `transport` keeps parsing: `{}` reads as the relay, and a block with an `apns` or `fcm` block reads as direct, exactly the configuration it described before. Parsing fills `transport` in, so `PushServiceConfigParsed`, `PushRelayTransportConfigParsed` and `PushDirectTransportConfigParsed` are declared beside the author types.
+- **`PushRelayRequestSchema`** (new) is what a server POSTs to the relay: `{ deliveries: [{ token, vendor, payload, priority }] }`, at least one delivery, with the binding credential as the request's bearer and none in the body. `payload` (`PushRelayPayloadSchema`) is ID-only: `data` is the push delivery data (`PushDeliveryDataSchema`) and `text` is one generic visible line; `title`, `body`, `subtitle`, `message` and `content` are refused by name. `priority` is `high` or `normal` (`PushRelayPrioritySchema`).
+- **`PushRelayResponseSchema`** (new) answers one result per delivery, in request order: `{ token, status }` with `status` `ok`, `invalid` (the vendor reports the token dead; stop delivering to it) or `retry` (transient; send again later).
+- **`PushRelayErrorResponseSchema`** (new) is the house `ErrorResponseSchema` envelope around `PushRelayErrorSchema`, a union on `code` of the house `EnhancedApiErrorSchema`: `UNAUTHENTICATED` (401, with `details.reason` `binding_invalid` or `binding_revoked`), `RATE_LIMIT_EXCEEDED` (429, with `retryAfterSeconds`) and `QUOTA_EXCEEDED` (429). Each requires `helpText`, the next step. No new error code is added.

content/docs/references/api/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: API Protocol — complete schema reference
 navTitle: API Protocol
-description: "The ObjectStack API Protocol in 35 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
+description: "The ObjectStack API Protocol in 36 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -34,6 +34,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
   <Card href="/docs/references/api/plugin-rest-api" title="Plugin Rest Api" description="Source: packages/spec/src/api/plugin-rest-api.zod.ts" />
   <Card href="/docs/references/api/protocol" title="Protocol" description="Source: packages/spec/src/api/protocol.zod.ts" />
   <Card href="/docs/references/api/push-delivery" title="Push Delivery" description="Source: packages/spec/src/api/push-delivery.zod.ts" />
+  <Card href="/docs/references/api/push-relay" title="Push Relay" description="Source: packages/spec/src/api/push-relay.zod.ts" />
   <Card href="/docs/references/api/query-adapter" title="Query Adapter" description="Source: packages/spec/src/api/query-adapter.zod.ts" />
   <Card href="/docs/references/api/realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
   <Card href="/docs/references/api/realtime-shared" title="Realtime Shared" description="Source: packages/spec/src/api/realtime-shared.zod.ts" />

content/docs/references/api/meta.json

@@ -38,6 +38,7 @@
     "package-api-assembled",
     "package-lifecycle",
     "push-delivery",
+    "push-relay",
     "record-page",
     "sortability"
   ]