@nlabs/reaktor 1.17.0 → 1.18.0

package/README.md

@@ -1454,6 +1454,166 @@ Reaktor is proprietary commercial software. A valid commercial agreement with
 Nitrogen Labs, Inc. is required to use, copy, modify, or distribute this
 package. See [LICENSE](./LICENSE) for the governing terms.
 
+## Durable conversations and messages (opt-in)
+
+The opt-in durable chat module extends Reaktor with persona-scoped direct/group conversations, invitations, role changes,
+member removal, ownership transfer, bounded membership epochs, idempotent mutation acknowledgements and ordered
+ID-only events. Existing conversation/message actions and GraphQL resolvers retain their legacy behavior but
+exclude durable schema-version-1 records; durable reads and writes require the new policy-aware engines. Community `groups`
+and posts remain separate from group conversations.
+
+### Conversation integration
+
+The following server-side outline assumes `context`, `verifiedIdentity`, and the three policy callbacks are
+provided by your application. `verifiedIdentity` has `{userId, personaId}` from verified authentication and current
+ownership checks; never accept either field as an authority supplied by a client.
+
+```ts
+import {
+  createDurableConversationActions,
+  createDurableConversationRepository
+} from '@nlabs/reaktor';
+
+const repository = createDurableConversationRepository(context, verifiedIdentity, {
+  audience: 'web', // Trusted server choice, never copied from an untrusted request.
+  authorizeIdentity, // async (transactionQuery, identity): fresh ownership and application eligibility.
+  classifyName,      // (name, contentVersion): application decision metadata.
+  projectName,       // (record, audience): authorized current name or undefined.
+  readCollections: ['applicationEligibility'] // Additional collections read by these hooks.
+});
+const actions = createDurableConversationActions(verifiedIdentity, repository);
+const conversation = await actions.getOrCreateDirect({participantPersonaId: 'peer-persona'});
+```
+
+The actions facade also exposes `createGroup`, `inviteMember`, `acceptInvite`, `declineInvite`,
+`changeMemberRole`, `removeMember`, `leaveConversation`, `transferOwnership`, `listConversations`,
+`listInvites`, and `getParticipants`. Existing-group mutations take the current `membershipRevision` as
+`expectedRevision`; accepting or declining an invite uses that invite's `revision` instead. Reuse the original
+idempotency key and exact payload when retrying a request; changing its payload raises `conflict`.
+
+Use the actions facade at public boundaries: it validates identifiers, revisions, list bounds, roles and group
+sizes. The repository handles canonical directs, seven-day invitations, group activation, role/owner transitions
+and replay receipts. Names are projected only on current reads; mutation receipts contain no name content.
+Groups initially invite 2–24 peers, become active at three accepted members, and cap active plus pending members
+at 25. A sole owner may leave and close the group; a nonempty group requires ownership transfer first.
+
+### Message integration
+
+`createDurableMessagePersistence(hooks)` provides validated send/edit/delete operations. Required hooks are
+`identity`, `run`, `authorizeIdentity`, `authorizeMembership`, `authorizeAttachment`, `authorizeMessageVisible`,
+`classifyContent` and `appendEvent` (normally `appendChatEvent`). Identity comes from verified server context.
+The engine owns exact payload replay/conflict checks, sequence allocation, immutable attachment version
+snapshots, reply references, 15-minute edit eligibility, revision CAS, deletion tombstones, rate limits and
+atomic event append. It accepts at most 4,000 Unicode characters and four distinct image references. The
+application owns content classification, current audience projection, original/derivative delivery and any
+retained-author policy; persistence records must not be returned directly as public message projections.
+The existing `mobileContentVersion`, `mobileDecision` and `mobilePlatformDisposition` storage names are retained
+for schema compatibility, with decision values supplied by the caller rather than a built-in platform policy.
+
+This outline builds on the conversation example. The application-provided `messagePolicy` contains
+`authorizeIdentity`, `authorizeAttachment`, `authorizeMessageVisible`, and `classifyContent`. Its reads use the
+transaction query passed into each authorization callback. Replace the example policy/media collection names
+with every collection your hooks actually read.
+
+```ts
+import {
+  appendChatEvent,
+  createDurableMessagePersistence,
+  createDurableTransaction,
+  createMembershipAuthorizer
+} from '@nlabs/reaktor';
+
+const messages = createDurableMessagePersistence({
+  ...messagePolicy,
+  appendEvent: appendChatEvent,
+  authorizeMembership: (read, identity, conversationId, purpose) =>
+    createMembershipAuthorizer(read)(identity, {conversationId, purpose}),
+  identity: verifiedIdentity,
+  run: createDurableTransaction(context, {
+    exclusive: ['chatMessageRequests', 'chatOutbox', 'chatRateLimits', 'conversations', 'messages'],
+    read: ['applicationEligibility', 'hasChatMembership', 'hasConnection', 'images', 'personas', 'users']
+  })
+});
+
+const acknowledgement = await messages.sendMessage({
+  attachmentIds: [],
+  clientMessageId: 'client-generated-request-id',
+  content: 'Hello',
+  conversationId: conversation.conversationId,
+  senderPersonaId: verifiedIdentity.personaId
+});
+```
+
+Persist the client-generated request ID before sending and keep it with the immutable retry payload. A successful
+send returns only `clientMessageId`, `messageId`, `revision`, and `sequence`. The `editMessage` and `deleteMessage`
+methods use `messageId`, `conversationId`, a new `idempotencyKey`, and the last acknowledged message revision as
+`expectedRevision`; editing also takes `content`. They return `messageId`, `revision`, and `sequence`.
+These are mutation/replay acknowledgements, not delivery or read receipts. Reading history, read receipts,
+reactions, socket transport, and event delivery remain application integrations. The exported
+`readDurableMessage` helper only verifies conversation/schema identity; callers still authorize membership,
+visibility, and the audience-specific projection before returning content.
+
+### Current defaults and limits
+
+These defaults are enforced by the durable chat engines; they are not configurable repository options.
+
+| Area | Behavior |
+| --- | --- |
+| Audience | Conversation name projection defaults to `mobile`; the server may explicitly choose `web`. |
+| Relationships | Direct creation and group invitations require active personas belonging to different users, mutual active follows, and no block in either direction. Invite acceptance rechecks the inviter relationship. Direct send/socket access rechecks the current relationship. |
+| Groups | Invite 2–24 distinct peers at creation. The group starts `forming`, activates at three accepted members including the owner, and caps active plus unexpired pending members at 25. |
+| Names and invitations | Group names must be nonblank and at most 200 UTF-16 code units. Invitations expire after seven days. |
+| Roles | Owners change roles and transfer ownership. Owners/admins invite; an admin may remove members but not an owner or another admin. An owner must transfer ownership before leaving other active members. |
+| Lists | Default page size 25; maximum 50. `after` is a document-key cursor, not a timestamp. |
+| Messages | At most 4,000 Unicode code points and four distinct image references. Sending requires nonblank text or an attachment. |
+| Edits and deletion | Only the current author may mutate an eligible message. Editing is allowed through 15 minutes after creation; deletion keeps a tombstone and clears text, attachments, and the reply reference. |
+| Rate limits | New direct/group creation and new invitations share a 50-per-hour user bucket. Sending, editing, and deleting each have a separate 60-per-minute user/persona bucket. |
+| Identifiers | IDs and idempotency keys use 1–128 ASCII letters, digits, underscores, or hyphens. Revisions are positive safe integers. |
+
+Applications decide eligibility, moderation/classification, attachment access and content retention. The built-in
+relationship rules and limits above still apply after those checks; products requiring different rules need an
+additive shared-library extension. `ChatError` (also exported as `DurableChatError`) exposes a `code` of
+`invalid_request`, `forbidden`, `conflict`, `rate_limited`, or `unavailable`; map these to your transport without
+serializing private persistence records or authorization details.
+
+### Transactions and schema prerequisites
+
+`createDurableTransaction(context, collections, query?)` returns an operation runner using Reaktor `useDb`,
+explicit collections, `allowImplicit: false`, five-second lock timeout and synchronous commit. Every policy hook
+must use its supplied transaction query for authoritative reads. Never call legacy actions that open their own
+connection from inside a hook. External provider calls belong outside the transaction.
+
+`classifyName` is synchronous. `classifyContent` may return a promise, but it runs inside the message transaction;
+use an already available deterministic policy/decision there and schedule external moderation work separately.
+`projectName` controls name disclosure on current list reads. The library does not install an approval policy.
+
+Conversation repositories lock `conversations`, `hasChatMembership`, `hasConversation`, `chatInvites`,
+`chatRequests`, `chatRateLimits` and `chatOutbox` exclusively; they read `users`, `personas`, `hasConnection`
+and declared hook collections. Message runners must exclusively lock `messages`, `chatMessageRequests`,
+`chatRateLimits`, `conversations` and `chatOutbox`, plus any mutation collections used by hooks. Declare all
+membership, identity, relationship, media and policy read collections. Both engines must share the conversation
+lock with membership changes so sends and removals have a defined order.
+
+Supplying an existing query transfers transaction/lock/commit ownership to the caller. It never opens a fallback
+connection, nests a transaction or commits independently. Commit failures are propagated without automatic
+retries: clients retry the exact original idempotency key and payload. `appendChatEvent` requires the caller's
+exclusive conversation/outbox locks and stores only IDs, revisions and sequence metadata.
+
+Provision document collections above and edge collections `hasChatMembership`, `hasConversation` and
+`hasConnection` before use. Required unique persistent indexes are:
+
+- `conversations.directPairKey` (sparse).
+- `hasChatMembership.currentKey` (sparse), and `(conversationId, personaId, epoch)`.
+- `chatInvites.currentKey` (sparse).
+- `messages.(conversationId, senderPersonaId, clientMessageId)` and `(conversationId, sequence)` (sparse).
+- `chatOutbox.(conversationId, eventSequence)` (sparse).
+
+Index membership state/role, invite recipient/state/expiry and outbox status/retry/lease fields for bounded reads.
+Receipt documents use deterministic primary keys. No migration runs automatically. Legacy message histories
+must be assigned validated sequences and compatible membership grants before enabling durable writes; the
+message engine rejects conversations containing unmigrated history. Delivery workers, schema migration and
+transport endpoints remain application integration responsibilities.
+
 ## Generation, sessions, and realtime
 
 See the [complete generation and sessions guide](docs/GENERATION.md) for the provider matrix, server configuration, results, storage, rejection handling, and release policy.
@@ -1520,3 +1680,25 @@ Higgsfield generation includes a typed catalog of 80 verified image/video API va
 ### Grok text and media
 
 Text generation accepts `provider: "grok"`; Reaktor uses server-side `contentGeneration.grokKey` and optional `grokModel` (default `grok-4.7`) for the xAI Responses API. Owned image inputs can accompany a text prompt. Grok image/video models are available through the Higgsfield model catalog and its existing webhook transport; this integration does not add a direct xAI media polling adapter. Application code owns callback persistence, retention, and accounting.
+
+## Assistant backend
+
+Reaktor provides configurable grounded chat, durable support delivery and public FAQ processing. Alfred supplies the UI shell; MetropolisJS's assistant action calls the GraphQL API directly. NitrogenX uses JSON POST requests to `https://api.reaktor.io` (also accepted at `/api`).
+
+```graphql
+mutation Chat($input: JSONObject!) {
+  assistant { chat(input: $input) }
+}
+query Faqs($input: JSONObject!) {
+  assistant { faqs(input: $input) }
+}
+mutation SubmitSupport($input: JSONObject!) {
+  assistant { submitSupport(input: $input) }
+}
+```
+
+Each operation takes `input: JSONObject!` and returns JSON at `data.assistant.<operation>`; it does not take a nested result selection set. For chat, send `{input: {context: 'nitrogen', history: [], question: 'What does Nitrogen build?'}}`. Chat returns `answer`, `sources` and `supportSuggested`; FAQs return `items`; support returns `ticketNumber` or `queued: true`.
+
+Support requires user confirmation, valid contact details and a stable `web-UUID` request ID. Queued acceptance means durable storage for retry, not confirmed email delivery. Read GraphQL `errors` even for HTTP 200 responses. The server selects approved knowledge, origins, database and delivery configuration; caller metadata cannot grant access.
+
+The backend factories are exported from the server-only `@nlabs/reaktor/assistant` subpath in the release containing the extraction. See [assistant endpoint, configuration and rollout](docs/ASSISTANT.md) for complete requests/responses, validation, limits, adapters and publication/deployment status.

package/docs/ASSISTANT.md

@@ -0,0 +1,138 @@
+# Shared assistant backend
+
+The assistant backend lives in Reaktor. Alfred supplies the UI shell; the host app uses the existing MetropolisJS `assistant` action. No changes to MetropolisJS are required.
+
+```text
+Alfred UI → MetropolisJS assistant action → Reaktor GraphQL → shared assistant service
+                                                        → Bedrock + approved knowledge
+                                                        → CRM / support notification
+                                                        → public FAQ actions
+```
+
+The GraphQL operations remain `assistant.chat`, `assistant.faqs` and `assistant.submitSupport`, each accepting `input: JSONObject!` and returning JSON. Public support submissions require explicit confirmation and an opaque `web-UUID` request ID. Keep that ID and the same details when retrying.
+
+## GraphQL endpoint and operations
+
+NitrogenX posts JSON `{query, variables}` to `https://api.reaktor.io` (the API also accepts `/api`). This is the GraphQL endpoint; no public `/api/assistant/*` REST endpoint is required. The frontend uses MetropolisJS's `createAction('assistant', flux)` with `app.api.public` set to the root URL.
+
+```graphql
+mutation Chat($input: JSONObject!) {
+  assistant { chat(input: $input) }
+}
+query Faqs($input: JSONObject!) {
+  assistant { faqs(input: $input) }
+}
+mutation SubmitSupport($input: JSONObject!) {
+  assistant { submitSupport(input: $input) }
+}
+```
+
+All operation inputs and results use the JSON scalar `JSONObject!`. Do not add a selection set inside `chat`, `faqs` or `submitSupport`; their result is JSON. Read `data.assistant.chat`, `data.assistant.faqs` or `data.assistant.submitSupport` respectively. Example chat variables:
+
+```json
+{
+  "input": {
+    "context": "nitrogen",
+    "history": [],
+    "language": "en-US",
+    "name": "Alfred",
+    "question": "What does Nitrogen build?"
+  }
+}
+```
+
+```jsonc
+// assistant.chat
+{
+  "answer": "An answer grounded in published documentation.",
+  "sources": [{"title": "About Nitrogen", "url": "https://nitrogenx.co/about"}],
+  "supportSuggested": false
+}
+// assistant.faqs
+{"items": [{"id": "topic-id", "question": "A public question?", "answer": "A grounded answer.", "sources": []}]}
+// assistant.submitSupport (confirmed delivery or durable queue)
+{"ticketNumber": "NX-..."}
+// or
+{"queued": true}
+```
+
+### Input contract
+
+- Chat: `question` is required (1–1,200 trimmed characters). `history` defaults to `[]`, allows six turns with `role: 'user' | 'assistant'` and `text` up to 2,500 characters. Optional `name` and `language` are bounded to 80 and 35 characters. Context must belong to the trusted profile; Nitrogen defaults to `nitrogen`.
+- FAQ: send `{context: 'nitrogen'}` or `{}`. The current Nitrogen profile lists public FAQ answers for the current corpus revision. Context/knowledge metadata do not select a tenant or guarantee product filtering.
+- Support: requires explicit `confirmed: true`, `firstName`, valid `email`, `message` up to 4,000 characters and a stable `requestId: 'web-UUID'`. Optional `company`, `lastName` and `phone` are bounded to 160, 160 and 24 characters. Context selects an approved product label; the server sets the support source.
+
+Example confirmed support variables (generate a fresh UUID for a new submission; keep it on retries):
+
+```json
+{"input":{"confirmed":true,"context":"nitrogen","email":"ada@example.com","firstName":"Ada","message":"Please help with my project.","requestId":"web-12345678-1234-1234-1234-123456789012"}}
+```
+
+`ticketNumber` confirms ticket creation and support notification delivery. `queued: true` confirms durable acceptance for retry, not email delivery. An identical retry returns the original receipt; different details under the same ID fail with `payload_conflict`.
+
+### Authorization and failures
+
+The managed handler checks an allowlisted browser origin and the API Gateway caller IP before servicing requests. A trusted server profile chooses corpus, database and delivery adapters. Client `knowledge`, `context`, name and language cannot grant permissions or choose storage. Never place provider/API credentials in browser code. Register a new origin/profile before connecting another host.
+
+Chat permits 30 requests per caller IP/hour and defaults to 20,000 requests/month for the profile. Support permits three submissions per caller IP/hour and 1,000/month. Visitor IDs are hashed; counters use conditional writes. Knowledge older than 14 days fails closed, and citations must refer to retrieved approved HTTPS sources.
+
+GraphQL failures use the standard `errors` array, potentially with HTTP 200. Controlled messages include `assistant_origin_not_allowed`, `assistant_request_too_large`, `invalid_request`, `confirmation_required`, `rate_limited`, `payload_conflict` and `assistant_unavailable`. Do not interpret HTTP success alone as a completed operation. The API bounds serialized input to 24,000 bytes and hides internal provider/storage diagnostics.
+
+The server-only `/assistant/faq` maintenance and `/crm/support/tickets/assistant` compatibility routes require Nitrogen's API key; they are not the browser assistant interface. The new GraphQL service calls the FAQ/CRM actions directly. See [MetropolisJS assistant actions](https://github.com/nitrogenlabs/metropolisjs/blob/main/docs/ASSISTANT.md) for client events and state.
+
+## Server configuration
+
+Import the backend factories from `@nlabs/reaktor/assistant` once the release containing this subpath is published. They require server AWS credentials; never bundle this module into a frontend.
+
+```ts
+import {createAssistantFaq, createAssistantService} from '@nlabs/reaktor/assistant';
+import {faqAction, submitPhoneSupportTicket} from '@nlabs/reaktor';
+
+const database = {databaseName: 'reaktor'};
+const profile = {
+  allowedHosts: ['nitrogenx.co', '*.nitrogenx.co', 'reaktor.io'],
+  bucket: 'my-assistant-bucket',
+  contexts: ['nitrogen', 'reaktor', 'alfred'],
+  defaultContext: 'nitrogen',
+  organization: 'Nitrogen'
+};
+const assistant = createAssistantService({
+  ...profile,
+  deliverSupport: (input) => submitPhoneSupportTicket(database, input),
+  modelId: 'amazon.nova-micro-v1:0',
+  monthlyRequests: 20000
+});
+const faqs = createAssistantFaq({
+  ...profile,
+  captureEnabled: true,
+  request: async <T>(operation: string, input?: unknown): Promise<T> =>
+    await faqAction(database, operation, input) as T
+});
+```
+
+NitrogenX's actual server profile is in `apps/api/src/assistant.ts`. It selects the corpus bucket and database on the server, calls the existing Reaktor CRM action directly, and uses the existing FAQ database action directly. The generic factories contain no Nitrogen domains, secret names, API URLs or support inbox. The current `submitPhoneSupportTicket` adapter is Nitrogen-specific; other hosts inject their own delivery adapter. That adapter must return `{notificationStatus: 'sent', ticketNumber}` only after its ticket and notification are confirmed.
+
+A frontend `knowledge` object remains application metadata. It cannot choose an S3 bucket, prefix, URL, secret or database. To add another application, register a trusted server profile and map its approved origin to that profile before calling the service. Do not choose profiles from an unauthenticated `appId` or `knowledge` payload.
+
+Use a separate bucket or a dedicated `prefix` (for example `customer-a/`) for every tenant. Configure the same bucket/prefix on both factories and enforce matching IAM access. Knowledge is JSON at `[prefix]knowledge/current.json`:
+
+```json
+{
+  "fetchedAt": "2026-10-02T12:00:00Z",
+  "pages": [{
+    "text": "Your published product documentation goes here.",
+    "title": "Product documentation",
+    "url": "https://nitrogenx.co/docs"
+  }]
+}
+```
+
+Retrieval allows only configured HTTPS hosts, bounds source text, and returns citations only from retrieved pages. Knowledge older than 14 days fails closed. Chat history is limited to six turns. The service honors bounded `name` and `language` metadata when constructing answers; these fields never change backend permissions. Nova Micro remains the default chat model and Titan v2 is used for FAQ embeddings.
+
+## Durable jobs and rollout
+
+The service writes encrypted pending submissions before reporting queued acceptance. Matching retries return the same receipt; changed payloads with the same ID are rejected. `assistant.retry()` drains support messages. `faqs.processFaqQueue()` groups sanitized public inquiries, quarantines repeated failures and refreshes grounded FAQ answers. Reaktor's scheduled worker runs both independently.
+
+Build and test Reaktor before deploying the API and its updated IAM policies. `AssistantBucketName` must name the existing Nitrogen corpus/queue bucket. The template defaults `AssistantWorkerEnabled` to `false` to avoid competing with legacy schedules. After verifying GraphQL chat, FAQ and confirmed support delivery, disable the old Nitrogen assistant delivery and FAQ worker schedules, then set `AssistantWorkerEnabled=true`. Keep the old Lambda versions for rollback. The Nitrogen knowledge crawler and phone IVR remain host integrations; the phone capture may continue writing the shared FAQ queue.
+
+This source change does not publish npm packages, deploy AWS resources or disable existing schedules. The legacy Nitrogen Lambda files are retained for rollback and phone compatibility until the shared package release is consumed by those integrations.

package/docs/GENERATION.md

@@ -304,3 +304,18 @@ it as `generationConfig.topP`. Values must be finite numbers from 0 through 1,
 including zero. Omission leaves the provider default untouched. Image requests
 and unsupported providers reject it before submission. Model-specific sampling
 policy belongs to callers; Reaktor adds no defaults or application prompts.
+
+## Output whitespace
+
+The server-side `generateContent` action accepts `outputTextMode: 'preserve'`
+for Claude Messages and OpenAI/Grok Responses calls. Preserve mode concatenates
+text blocks exactly, adding no separators and keeping surrounding whitespace.
+Claude thinking/redacted-thinking blocks are excluded; unsupported blocks or
+malformed text are rejected in preserve mode. A normally completed, nonblank
+text response is still required.
+
+Omit the option or use `'trim'` to keep existing behavior: OpenAI/Grok trim their
+concatenated text; Claude inserts newlines between text blocks before trimming.
+Other providers reject the option before submission. It is local output policy
+and is never sent to a provider; GraphQL input does not expose it. The option does
+not enable or select Claude thinking settings or alter provider request bodies.

package/docs/NATIVE_PUSH.md

@@ -0,0 +1,56 @@
+# Native push through AWS SNS
+
+Import `createNativePushService`, `createArangoNativePushRepository`,
+`migrateNativePushRegistry`, and `createNativePushGraphql` from
+`@nlabs/reaktor/native-push`. Existing direct APNs actions are unchanged.
+
+```ts
+const scope = {appId: 'your-app', environment: 'dev'};
+const repository = createArangoNativePushRepository({databaseName: 'your-app-dev'});
+// Explicit rollout operation, never run at import/startup:
+await migrateNativePushRegistry({databaseName: 'your-app-dev'});
+const service = createNativePushService({
+  scope, repository, sns: new SNSClient({region: 'us-east-1'}),
+  platformApplicationArns: {android: androidArn, iosSandbox: sandboxArn, iosProduction: productionArn},
+  isSessionEligible: async (scope, actor) => verifyPersistedLiveSession(scope, actor),
+  canDeliver: async (registration, notification) => recheckBusinessAccess(registration.userId, notification)
+});
+const graphql = createNativePushGraphql({service, resolveActor: context => verifiedActor(context)});
+// Mount graphql.mutationFields.nativePush under the app's existing schema.
+```
+
+Actor comes only from verified server context; scope and ARNs come only from
+server configuration. Registration receives installationId/platform/native token
+and (for iOS) sandbox/production APNs environment. Public GraphQL results exclude
+tokens, hashes, endpoint ARNs and session identity. Unregister is actor/revision
+fenced, so delayed old-account cleanup cannot disable a replacement. Session
+revocation remains essential if the client is offline. The registry uses Reaktor
+`useDb`, with explicit unique scope+installation and lookup indexes.
+
+Send one stable server-generated notificationId across transports. Version is 1;
+title/body stay generic for private content. Put only non-sensitive navigation
+identifiers in JSON data, never chat text, precise location, tokens or credentials.
+`send` returns per-registration ACCEPTED/SKIPPED/INVALID_ENDPOINT/TRANSIENT_FAILURE/
+PERMANENT_FAILURE. ACCEPTED means provider acceptance, not device display. Native
+and WebSocket clients deduplicate the same envelope by ID. SNS transient retries
+are bounded; invalid registrations are disabled, and authenticated registration
+can reconcile/re-enable endpoints. No durable outbox or delivery guarantees.
+
+## Rollout
+
+Each app/environment needs distinct SNS platform applications and bundle/package
+IDs. APNs sandbox versus production must match signed build entitlements. Upload
+APNs credentials and FCM HTTP-v1 service account credentials to AWS/backend secrets,
+not the app repository. FCM is Android transport only; Firebase auth/database is
+not required. Restrict CreatePlatformEndpoint/GetEndpointAttributes/
+SetEndpointAttributes/Publish IAM permissions to configured SNS resources.
+
+Apply migrations explicitly; do not trust legacy unauthenticated device rows.
+Rollback by disabling registration/delivery without deleting inbox/registry data.
+Keep reconnect/backfill and recipient authorization in the app. Check physical
+iOS/Android foreground/background/terminated launch, permission denial, token
+rotation, offline logout and account switching before production rollout.
+
+See MetropolisJS `docs/NATIVE_NOTIFICATIONS.md` for the optional Expo integration.
+Cloud provisioning, deployment, migrations and npm publication require separate
+approval; unit tests and bundles do not prove live native push.

package/lib/actions/alfredFaq.d.ts

@@ -0,0 +1,80 @@
+import type { ApiContext } from '../types/auth.types.js';
+interface FaqSource {
+    title: string;
+    url: string;
+}
+interface Topic {
+    _key: string;
+    answer?: string;
+    answerExpires?: number;
+    appId: string;
+    embedding?: number[];
+    kind: string;
+    lastAsked: number;
+    product?: string;
+    question: string;
+    sources?: FaqSource[];
+    weight: number;
+}
+interface FaqInput {
+    channel: 'website' | 'phone';
+    embedding: number[];
+    eventId: string;
+    product: string;
+    question: string;
+    revision: number;
+    topicId: string;
+}
+export declare const validateFaqInput: (value: unknown) => FaqInput;
+export declare const publicFaq: (topics: Topic[], now: number) => {
+    answer: string;
+    id: string;
+    question: string;
+    sources: FaqSource[];
+}[];
+export declare const faqAction: (context: ApiContext, operation: string, value?: unknown) => Promise<{
+    items: {
+        answer: string;
+        id: string;
+        question: string;
+        sources: FaqSource[];
+    }[];
+    ok?: undefined;
+    candidates?: undefined;
+    revision?: undefined;
+    duplicate?: undefined;
+    topicId?: undefined;
+} | {
+    items: Topic[];
+    ok?: undefined;
+    candidates?: undefined;
+    revision?: undefined;
+    duplicate?: undefined;
+    topicId?: undefined;
+} | {
+    items?: undefined;
+    ok: boolean;
+    candidates?: undefined;
+    revision?: undefined;
+    duplicate?: undefined;
+    topicId?: undefined;
+} | {
+    items?: undefined;
+    ok?: undefined;
+    candidates: {
+        id: string;
+        question: string;
+        score: number;
+    }[];
+    revision: number;
+    duplicate?: undefined;
+    topicId?: undefined;
+} | {
+    items?: undefined;
+    ok?: undefined;
+    candidates?: undefined;
+    revision?: undefined;
+    duplicate: boolean;
+    topicId: string;
+}>;
+export {};