pyric 0.0.1 → 0.1.0-alpha.10

package/dist/messaging/broker/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `pyric/src/messaging/broker` — the sandbox-side FCM broker (see
+ * `broker.ts` for the model and the documented worker-host seam).
+ *
+ * One broker per {@link Sandbox}, held in a WeakMap exactly like
+ * `pyric-admin/database`'s per-sandbox state: every plane that shares a
+ * Sandbox shares the broker, which is what closes the send→deliver loop
+ * in-process (admin `send` on the same sandbox reaches client `onMessage` /
+ * sw `onBackgroundMessage` handlers).
+ */
+import type { Sandbox } from '../../sandbox/types/service.js';
+import { MessagingBroker } from './broker.js';
+import type { MessagingBrokerConfig } from './types.js';
+export { MessagingBroker, DEFAULT_PROJECT_ID, DEFAULT_SENDER_ID, DEFAULT_CLIENT_ID, evaluateCondition, } from './broker.js';
+export { BrokerSendError, fcmErrorCodeOf, noTargetEnvelope, multipleTargetsEnvelope, invalidTokenEnvelope, invalidTopicNameEnvelope, invalidConditionEnvelope, oversizedPayloadEnvelope, invalidWebpushTtlEnvelope, unregisteredTokenEnvelope, } from './envelopes.js';
+export type { FcmErrorEnvelope, ErrorDetail, BadRequestDetail, FcmErrorDetail } from './envelopes.js';
+export { validateMessage, parseCondition, isValidTopicName, canonicalTopicName, TOPIC_NAME_RE, TOKEN_SHAPE_RE, EMPIRICAL_DATA_CAP_BYTES, } from './validate.js';
+export { mintToken, TOKEN_LENGTH, TOKEN_SUFFIX_PREFIX } from './tokens.js';
+export type { AcceptedSend, BrokerMessage, ClientVisibilityState, DeliveredPayload, DeliveryResult, DeliveryRoute, MessagingBrokerConfig, PayloadHandler, ResolvedTarget, TopicManagementOutcome, } from './types.js';
+/**
+ * The broker bound to `sandbox` — created on first access, then stable.
+ * `config` applies only on the creating call (subsequent callers share the
+ * already-configured instance; passing a different config later is a no-op
+ * by design, mirroring how per-sandbox service state behaves elsewhere).
+ */
+export declare function getMessagingBroker(sandbox: Sandbox, config?: MessagingBrokerConfig): MessagingBroker;
+//# sourceMappingURL=index.d.ts.map

package/dist/messaging/broker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/broker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtG,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EACV,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAIpB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAMpG"}

package/dist/messaging/broker/index.js

@@ -0,0 +1,21 @@
+import { MessagingBroker } from './broker.js';
+export { MessagingBroker, DEFAULT_PROJECT_ID, DEFAULT_SENDER_ID, DEFAULT_CLIENT_ID, evaluateCondition, } from './broker.js';
+export { BrokerSendError, fcmErrorCodeOf, noTargetEnvelope, multipleTargetsEnvelope, invalidTokenEnvelope, invalidTopicNameEnvelope, invalidConditionEnvelope, oversizedPayloadEnvelope, invalidWebpushTtlEnvelope, unregisteredTokenEnvelope, } from './envelopes.js';
+export { validateMessage, parseCondition, isValidTopicName, canonicalTopicName, TOPIC_NAME_RE, TOKEN_SHAPE_RE, EMPIRICAL_DATA_CAP_BYTES, } from './validate.js';
+export { mintToken, TOKEN_LENGTH, TOKEN_SUFFIX_PREFIX } from './tokens.js';
+const brokers = new WeakMap();
+/**
+ * The broker bound to `sandbox` — created on first access, then stable.
+ * `config` applies only on the creating call (subsequent callers share the
+ * already-configured instance; passing a different config later is a no-op
+ * by design, mirroring how per-sandbox service state behaves elsewhere).
+ */
+export function getMessagingBroker(sandbox, config) {
+    const existing = brokers.get(sandbox);
+    if (existing !== undefined)
+        return existing;
+    const broker = new MessagingBroker({ ...config, sandbox });
+    brokers.set(sandbox, broker);
+    return broker;
+}
+//# sourceMappingURL=index.js.map

package/dist/messaging/broker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/messaging/broker/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAc3E,MAAM,OAAO,GAAG,IAAI,OAAO,EAA4B,CAAC;AAExD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,MAA8B;IACjF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/messaging/broker/tokens.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Registration-token minting — the captured shape class, not captured
+ * values (token values are prod noise, dropped by the oracle).
+ *
+ * oracle: `messaging-web-token-shape` pins minted production tokens as
+ * 142 chars, colon-separated, URL-safe, with the post-colon suffix
+ * beginning `APA91b`. `messaging-web-token-stability` pins that a second
+ * `getToken` on the same service-worker registration returns the SAME
+ * token — stability is per registration, handled by the broker's
+ * registration map (`token lifecycle` in broker.ts), not here.
+ */
+/** Total minted length (oracle: messaging-web-token-shape `length: 142`). */
+export declare const TOKEN_LENGTH = 142;
+/** Captured suffix prefix: the segment after the colon begins `APA91b`. */
+export declare const TOKEN_SUFFIX_PREFIX = "APA91b";
+/**
+ * Mint a fresh registration token in the captured shape class:
+ * `<22 url-safe chars>:APA91b<113 url-safe chars>` — 142 chars total,
+ * exactly one colon, fully URL-safe.
+ */
+export declare function mintToken(): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/messaging/broker/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/messaging/broker/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,6EAA6E;AAC7E,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAY5C;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAIlC"}

package/dist/messaging/broker/tokens.js

@@ -0,0 +1,37 @@
+/**
+ * Registration-token minting — the captured shape class, not captured
+ * values (token values are prod noise, dropped by the oracle).
+ *
+ * oracle: `messaging-web-token-shape` pins minted production tokens as
+ * 142 chars, colon-separated, URL-safe, with the post-colon suffix
+ * beginning `APA91b`. `messaging-web-token-stability` pins that a second
+ * `getToken` on the same service-worker registration returns the SAME
+ * token — stability is per registration, handled by the broker's
+ * registration map (`token lifecycle` in broker.ts), not here.
+ */
+const URL_SAFE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** Total minted length (oracle: messaging-web-token-shape `length: 142`). */
+export const TOKEN_LENGTH = 142;
+/** Captured suffix prefix: the segment after the colon begins `APA91b`. */
+export const TOKEN_SUFFIX_PREFIX = 'APA91b';
+/** Instance-id segment length before the colon (shape-class choice, not a captured constant). */
+const INSTANCE_SEGMENT_LENGTH = 22;
+function randomUrlSafe(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    let out = '';
+    for (let i = 0; i < length; i++)
+        out += URL_SAFE[bytes[i] % URL_SAFE.length];
+    return out;
+}
+/**
+ * Mint a fresh registration token in the captured shape class:
+ * `<22 url-safe chars>:APA91b<113 url-safe chars>` — 142 chars total,
+ * exactly one colon, fully URL-safe.
+ */
+export function mintToken() {
+    const instance = randomUrlSafe(INSTANCE_SEGMENT_LENGTH);
+    const suffixRandom = TOKEN_LENGTH - INSTANCE_SEGMENT_LENGTH - 1 - TOKEN_SUFFIX_PREFIX.length;
+    return `${instance}:${TOKEN_SUFFIX_PREFIX}${randomUrlSafe(suffixRandom)}`;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/messaging/broker/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../../src/messaging/broker/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,QAAQ,GAAG,kEAAkE,CAAC;AAEpF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAChC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAC5C,iGAAiG;AACjG,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9E,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,QAAQ,GAAG,aAAa,CAAC,uBAAuB,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,YAAY,GAAG,uBAAuB,GAAG,CAAC,GAAG,mBAAmB,CAAC,MAAM,CAAC;IAC7F,OAAO,GAAG,QAAQ,IAAI,mBAAmB,GAAG,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;AAC5E,CAAC"}

package/dist/messaging/broker/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Broker-side messaging types — the sandbox FCM model every plane consumes
+ * (client mirror, sw mirror, admin mirror, and later the worker host's
+ * `messaging.*` op handlers).
+ *
+ * These are intentionally the broker's OWN shapes, not re-exports of
+ * `firebase-admin/messaging` typings: the admin mirror maps its public
+ * `Message` union onto `BrokerMessage` at the boundary, and the client
+ * mirrors map `DeliveredPayload` onto their public `MessagePayload`.
+ */
+/**
+ * The intake shape the broker validates and routes. Structurally a
+ * permissive superset of `firebase-admin/messaging`'s `Message` union:
+ * exactly one of `token` / `topic` / `condition` must be set (enforced by
+ * `validateMessage`, per the captured no-target envelope).
+ */
+export interface BrokerMessage {
+    token?: string;
+    topic?: string;
+    condition?: string;
+    data?: Record<string, string>;
+    notification?: {
+        title?: string;
+        body?: string;
+        imageUrl?: string;
+    };
+    webpush?: {
+        headers?: Record<string, string>;
+        data?: Record<string, string>;
+        notification?: Record<string, unknown>;
+        fcmOptions?: {
+            link?: string;
+        };
+    };
+    android?: Record<string, unknown>;
+    apns?: Record<string, unknown>;
+    fcmOptions?: {
+        analyticsLabel?: string;
+    };
+}
+/** A validated send target. `condition.topics` is populated by the parser. */
+export type ResolvedTarget = {
+    kind: 'token';
+    token: string;
+} | {
+    kind: 'topic';
+    topic: string;
+} | {
+    kind: 'condition';
+    condition: string;
+    topics: string[];
+};
+/**
+ * An accepted send. `name` is the FCM message resource name:
+ * `projects/<projectId>/messages/<id>` where `<id>` is NUMERIC for topic and
+ * condition targets and UUID-form for token targets (per-target formats are
+ * part of the captured/spec'd contract). Shape-identical for dryRun — the
+ * capture pins that callers cannot distinguish validation from acceptance
+ * by shape (`dryRunSameShapeAsReal`).
+ */
+export interface AcceptedSend {
+    name: string;
+    messageId: string;
+    target: ResolvedTarget;
+    validateOnly: boolean;
+}
+/**
+ * The envelope delivered to a client plane handler — the mirror of the
+ * received `MessagePayload` captured in `messaging-web-onmessage-foreground`
+ * / `messaging-web-onbackgroundmessage`: top-level keys are exactly
+ * `data` / `from` / `messageId` (+ `notification` for notification
+ * messages). A data-only message carries NO `notification` key
+ * (`messaging-web-data-only-background`).
+ */
+export interface DeliveredPayload {
+    data?: Record<string, string>;
+    notification?: {
+        title?: string;
+        body?: string;
+        image?: string;
+    };
+    from: string;
+    messageId: string;
+}
+/** How a delivery was routed (the captured visibility rule). */
+export type DeliveryRoute = 'foreground' | 'background';
+export interface DeliveryResult {
+    route: DeliveryRoute;
+    /** Handlers actually invoked on the chosen route. */
+    handlerCount: number;
+    payload: DeliveredPayload;
+}
+/** Window-client visibility, the ONLY input to routing (never focus). */
+export type ClientVisibilityState = 'visible' | 'hidden';
+/** Result of a topic subscribe/unsubscribe batch (admin mirror shapes it). */
+export interface TopicManagementOutcome {
+    successCount: number;
+    failureCount: number;
+    errors: Array<{
+        index: number;
+        reason: 'invalid-token' | 'unregistered-token';
+    }>;
+}
+export interface MessagingBrokerConfig {
+    /** Project id minted into message resource names. */
+    projectId?: string;
+    /**
+     * Messaging sender id — the value delivered as `from` on every client
+     * payload (`fromEqualsSenderId` is pinned by the foreground/background
+     * captures). Defaults to a fixed 12-digit numeric string, matching the
+     * project-number shape production uses.
+     */
+    senderId?: string;
+}
+/** Handler registered on a client plane. */
+export type PayloadHandler = (payload: DeliveredPayload) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/messaging/broker/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/messaging/broker/types.ts"],"names":[],"mappings":"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"}

package/dist/messaging/broker/types.js

@@ -0,0 +1,12 @@
+/**
+ * Broker-side messaging types — the sandbox FCM model every plane consumes
+ * (client mirror, sw mirror, admin mirror, and later the worker host's
+ * `messaging.*` op handlers).
+ *
+ * These are intentionally the broker's OWN shapes, not re-exports of
+ * `firebase-admin/messaging` typings: the admin mirror maps its public
+ * `Message` union onto `BrokerMessage` at the boundary, and the client
+ * mirrors map `DeliveredPayload` onto their public `MessagePayload`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/messaging/broker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/messaging/broker/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/messaging/broker/validate.d.ts

@@ -0,0 +1,58 @@
+import type { BrokerMessage, ResolvedTarget } from './types.js';
+/**
+ * The documented FCM topic-name character set
+ * (oracle: `messaging-send-invalid-topic-name-error-envelope` pins the
+ * rejection of characters outside `[a-zA-Z0-9-_.~%]`).
+ */
+export declare const TOPIC_NAME_RE: RegExp;
+/**
+ * Registration-token shape class, as minted by production and captured in
+ * `messaging-web-token-shape`: colon-separated, URL-safe. The broker treats
+ * "two non-empty URL-safe segments around a single colon" as well-formed;
+ * anything else is the captured invalid-token rejection. UNOBSERVED nuance:
+ * production's exact syntactic acceptance set is unknown (only
+ * `'not-a-valid-fcm-token'` — no colon — was driven); this class is the
+ * broker's provisional model.
+ */
+export declare const TOKEN_SHAPE_RE: RegExp;
+/**
+ * The EMPIRICAL data-payload enforcement boundary.
+ *
+ * oracle: `messaging-send-oversized-payload-error-envelope` bisected a
+ * minimal single-entry topic message (`data: { p: 'x'.repeat(len) }`):
+ * len 4505 accepted, 4506 rejected. Under the broker's size model —
+ * summed UTF-8 bytes of every data key + value — the flip sits at
+ * 1 ('p') + 4505 = 4506 bytes accepted, 4507 rejected. The documented cap
+ * (4096, quoted in the error message) is NOT the enforcement constant;
+ * production enforces looser. The true production size function is
+ * unobserved beyond this one point — this model reproduces the captured
+ * boundary exactly for the captured probe shape and is a provisional
+ * design decision (see the broker report; informs the open payload-size
+ * ticket).
+ */
+export declare const EMPIRICAL_DATA_CAP_BYTES = 4506;
+/** Strip an optional `/topics/` prefix (accepted by the admin SDK) before charset validation. */
+export declare function canonicalTopicName(topic: string): string;
+export declare function isValidTopicName(topic: string): boolean;
+/**
+ * Condition grammar: boolean expressions over `'name' in topics` with
+ * `&&`, `||`, `!`, and parentheses. A dangling operator (the captured
+ * malformed case `"'a' in topics &&"`) fails the parse and produces the
+ * captured BARE envelope. UNOBSERVED: production's documented 5-topic
+ * limit per condition is not enforced here (no captured envelope for it).
+ *
+ * Returns the topic names referenced (for delivery routing) or `null`
+ * when the condition is malformed.
+ */
+export declare function parseCondition(condition: string): {
+    topics: string[];
+} | null;
+/**
+ * Validate an intake message against the captured contract and resolve its
+ * target. Throws {@link BrokerSendError} carrying the exact captured
+ * envelope for each fault; returns the resolved target on acceptance.
+ * `validate_only` (dryRun) runs this identical path — parity is pinned by
+ * every `realSendEnvelopeIdentical` capture.
+ */
+export declare function validateMessage(message: BrokerMessage): ResolvedTarget;
+//# sourceMappingURL=validate.d.ts.map

package/dist/messaging/broker/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/messaging/broker/validate.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAwB,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,QAAoC,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAa7C,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA0D7E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CA8CtE"}

package/dist/messaging/broker/validate.js

@@ -0,0 +1,196 @@
+/**
+ * Send-plane intake validation — the CAPTURED contract, in checking order.
+ *
+ * Each rule cites the observation that pins it. Rules with no observation
+ * are marked UNOBSERVED and stated at documentation strength (probe
+ * candidates before they can be trusted as prod-faithful).
+ *
+ * CHECK ORDER (provisional — every captured case is single-fault, so
+ * production's precedence among simultaneous faults is unobserved):
+ *   1. target exclusivity (exactly one of token / topic / condition)
+ *   2. per-target syntax (token shape, topic charset, condition grammar)
+ *   3. webpush headers.TTL
+ *   4. data payload size boundary
+ */
+import { BrokerSendError, invalidConditionEnvelope, invalidTokenEnvelope, invalidTopicNameEnvelope, invalidWebpushTtlEnvelope, multipleTargetsEnvelope, noTargetEnvelope, oversizedPayloadEnvelope, } from './envelopes.js';
+/**
+ * The documented FCM topic-name character set
+ * (oracle: `messaging-send-invalid-topic-name-error-envelope` pins the
+ * rejection of characters outside `[a-zA-Z0-9-_.~%]`).
+ */
+export const TOPIC_NAME_RE = /^[a-zA-Z0-9-_.~%]+$/;
+/**
+ * Registration-token shape class, as minted by production and captured in
+ * `messaging-web-token-shape`: colon-separated, URL-safe. The broker treats
+ * "two non-empty URL-safe segments around a single colon" as well-formed;
+ * anything else is the captured invalid-token rejection. UNOBSERVED nuance:
+ * production's exact syntactic acceptance set is unknown (only
+ * `'not-a-valid-fcm-token'` — no colon — was driven); this class is the
+ * broker's provisional model.
+ */
+export const TOKEN_SHAPE_RE = /^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$/;
+/**
+ * The EMPIRICAL data-payload enforcement boundary.
+ *
+ * oracle: `messaging-send-oversized-payload-error-envelope` bisected a
+ * minimal single-entry topic message (`data: { p: 'x'.repeat(len) }`):
+ * len 4505 accepted, 4506 rejected. Under the broker's size model —
+ * summed UTF-8 bytes of every data key + value — the flip sits at
+ * 1 ('p') + 4505 = 4506 bytes accepted, 4507 rejected. The documented cap
+ * (4096, quoted in the error message) is NOT the enforcement constant;
+ * production enforces looser. The true production size function is
+ * unobserved beyond this one point — this model reproduces the captured
+ * boundary exactly for the captured probe shape and is a provisional
+ * design decision (see the broker report; informs the open payload-size
+ * ticket).
+ */
+export const EMPIRICAL_DATA_CAP_BYTES = 4506;
+const utf8 = new TextEncoder();
+function dataBytes(data) {
+    if (data === undefined)
+        return 0;
+    let total = 0;
+    for (const [key, value] of Object.entries(data)) {
+        total += utf8.encode(key).length + utf8.encode(String(value)).length;
+    }
+    return total;
+}
+/** Strip an optional `/topics/` prefix (accepted by the admin SDK) before charset validation. */
+export function canonicalTopicName(topic) {
+    return topic.startsWith('/topics/') ? topic.slice('/topics/'.length) : topic;
+}
+export function isValidTopicName(topic) {
+    const name = canonicalTopicName(topic);
+    return name.length > 0 && TOPIC_NAME_RE.test(name);
+}
+/**
+ * Condition grammar: boolean expressions over `'name' in topics` with
+ * `&&`, `||`, `!`, and parentheses. A dangling operator (the captured
+ * malformed case `"'a' in topics &&"`) fails the parse and produces the
+ * captured BARE envelope. UNOBSERVED: production's documented 5-topic
+ * limit per condition is not enforced here (no captured envelope for it).
+ *
+ * Returns the topic names referenced (for delivery routing) or `null`
+ * when the condition is malformed.
+ */
+export function parseCondition(condition) {
+    const src = condition;
+    let pos = 0;
+    const topics = [];
+    function ws() {
+        while (pos < src.length && /\s/.test(src[pos]))
+            pos++;
+    }
+    function expectLiteral(lit) {
+        ws();
+        if (src.startsWith(lit, pos)) {
+            pos += lit.length;
+            return true;
+        }
+        return false;
+    }
+    // primary := "'" name "' in topics" | "(" expr ")" | "!" primary
+    function primary() {
+        ws();
+        if (expectLiteral('!'))
+            return primary();
+        if (expectLiteral('(')) {
+            if (!expr())
+                return false;
+            return expectLiteral(')');
+        }
+        ws();
+        if (src[pos] !== "'")
+            return false;
+        pos++;
+        const start = pos;
+        while (pos < src.length && src[pos] !== "'")
+            pos++;
+        if (pos >= src.length)
+            return false;
+        const name = src.slice(start, pos);
+        pos++; // closing quote
+        if (!expectLiteral('in'))
+            return false;
+        if (!expectLiteral('topics'))
+            return false;
+        if (!isValidTopicName(name))
+            return false;
+        topics.push(name);
+        return true;
+    }
+    // expr := primary (('&&' | '||') primary)*
+    function expr() {
+        if (!primary())
+            return false;
+        for (;;) {
+            ws();
+            if (expectLiteral('&&') || expectLiteral('||')) {
+                if (!primary())
+                    return false;
+                continue;
+            }
+            return true;
+        }
+    }
+    if (!expr())
+        return null;
+    ws();
+    if (pos !== src.length)
+        return null;
+    return { topics };
+}
+/**
+ * Validate an intake message against the captured contract and resolve its
+ * target. Throws {@link BrokerSendError} carrying the exact captured
+ * envelope for each fault; returns the resolved target on acceptance.
+ * `validate_only` (dryRun) runs this identical path — parity is pinned by
+ * every `realSendEnvelopeIdentical` capture.
+ */
+export function validateMessage(message) {
+    if (typeof message !== 'object' || message === null) {
+        throw new BrokerSendError(noTargetEnvelope());
+    }
+    // 1. Target exclusivity (oracle: messaging-send-no-target-error-envelope).
+    const targets = [];
+    if (typeof message.token === 'string')
+        targets.push({ kind: 'token', token: message.token });
+    if (typeof message.topic === 'string') {
+        targets.push({ kind: 'topic', topic: canonicalTopicName(message.topic) });
+    }
+    if (typeof message.condition === 'string') {
+        targets.push({ kind: 'condition', condition: message.condition, topics: [] });
+    }
+    if (targets.length === 0)
+        throw new BrokerSendError(noTargetEnvelope());
+    if (targets.length > 1)
+        throw new BrokerSendError(multipleTargetsEnvelope());
+    const target = targets[0];
+    // 2. Per-target syntax.
+    if (target.kind === 'token' && !TOKEN_SHAPE_RE.test(target.token)) {
+        // oracle: messaging-send-invalid-token-error-envelope
+        throw new BrokerSendError(invalidTokenEnvelope());
+    }
+    if (target.kind === 'topic' && !isValidTopicName(target.topic)) {
+        // oracle: messaging-send-invalid-topic-name-error-envelope
+        throw new BrokerSendError(invalidTopicNameEnvelope());
+    }
+    if (target.kind === 'condition') {
+        // oracle: messaging-send-invalid-condition-error-envelope (bare envelope)
+        const parsed = parseCondition(target.condition);
+        if (parsed === null)
+            throw new BrokerSendError(invalidConditionEnvelope());
+        target.topics = parsed.topics;
+    }
+    // 3. webpush headers.TTL (oracle: messaging-send-webpush-invalid-ttl-error-envelope).
+    const ttl = message.webpush?.headers?.TTL;
+    if (ttl !== undefined && !/^\d+$/.test(String(ttl))) {
+        throw new BrokerSendError(invalidWebpushTtlEnvelope());
+    }
+    // 4. Data payload boundary (oracle: messaging-send-oversized-payload-error-envelope).
+    if (dataBytes(message.data) > EMPIRICAL_DATA_CAP_BYTES) {
+        throw new BrokerSendError(oversizedPayloadEnvelope());
+    }
+    return target;
+}
+//# sourceMappingURL=validate.js.map

package/dist/messaging/broker/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/messaging/broker/validate.ts"],"names":[],"mappings":"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"}

package/dist/messaging/client.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Window-client implementation for the `firebase/messaging` mirror over
+ * the sandbox {@link MessagingBroker}. Surface `messaging`, rows
+ * `messaging#1`–`messaging#12` in `packages/conformance/registry/messaging.ts`.
+ *
+ * MODULE BOUNDARY (row messaging#17): this entry exports `getToken` /
+ * `deleteToken` / `onMessage` and does NOT export `onBackgroundMessage` or
+ * the BigQuery metrics toggle — those live in `pyric/messaging/sw`, the
+ * mirror image. The client `ErrorCode` enum is `@internal` upstream and is
+ * deliberately NOT exported here (row messaging#12).
+ *
+ * The `sandbox` namespace is the pyric-only headless driver (delivery
+ * injection + the simulated service-worker registration); it has no
+ * upstream counterpart and is additive to the mirrored surface.
+ */
+import type { FirebaseApp } from '../app/types.js';
+import { type DeliverSpec, type Messaging, type SimulatedServiceWorkerRegistration } from './instance.js';
+import type { DeliveryResult } from './broker/index.js';
+export type { Messaging };
+/** Display-notification block inside a {@link MessagePayload}. */
+export interface NotificationPayload {
+    title?: string;
+    body?: string;
+    image?: string;
+    icon?: string;
+}
+/** Options carried on a client {@link MessagePayload}. */
+export interface FcmOptions {
+    link?: string;
+    analyticsLabel?: string;
+}
+/**
+ * Received message envelope delivered to `onMessage` / `onBackgroundMessage`.
+ * `from` / `collapseKey` / `messageId` are typed required (upstream parity);
+ * captured production deliveries carry top-level keys
+ * `data` / `from` / `messageId` (+ `notification`) — `collapseKey` was not
+ * observed on the wire and the sandbox likewise omits it at runtime.
+ */
+export interface MessagePayload {
+    notification?: NotificationPayload;
+    data?: {
+        [key: string]: string;
+    };
+    fcmOptions?: FcmOptions;
+    from: string;
+    collapseKey: string;
+    messageId: string;
+}
+/**
+ * Callback / observer / teardown shapes — structurally identical to the
+ * `@firebase/util` types the upstream entry re-exports (declared locally
+ * because `@firebase/util` is not a direct dependency of `pyric`; the
+ * tier-2 assignability census closes exact type parity).
+ */
+export type NextFn<T> = (value: T) => void;
+export interface Observer<T> {
+    next: NextFn<T>;
+    error: (error: Error) => void;
+    complete: () => void;
+}
+export type Unsubscribe = () => void;
+/** Options for {@link getToken}. */
+export interface GetTokenOptions {
+    vapidKey?: string;
+    /** A (simulated) service-worker registration; token stability keys on its identity. */
+    serviceWorkerRegistration?: object;
+}
+/**
+ * Return the FCM `Messaging` instance for the given (or default) app —
+ * window-client plane (upstream component name `messaging`).
+ */
+export declare function getMessaging(app?: FirebaseApp): Messaging;
+/**
+ * Subscribe the instance to push and resolve its registration token.
+ * Sandbox semantics per the captured contract: the minted token matches the
+ * production shape class (142 chars, colon-separated, URL-safe, `APA91b`
+ * suffix class) and is STABLE across repeated calls on the same
+ * (simulated) service-worker registration — no per-call rotation.
+ * Notification permission is modeled as granted in the sandbox.
+ */
+export declare function getToken(messaging: Messaging, options?: GetTokenOptions): Promise<string>;
+/**
+ * Delete the active registration token. Resolves truthy; afterwards no
+ * message reaches the client on either route and a send to the dead token
+ * surfaces the captured UNREGISTERED envelope on the send plane
+ * (oracle: `messaging-web-deletetoken-unregistered`).
+ */
+export declare function deleteToken(messaging: Messaging): Promise<boolean>;
+/**
+ * Listen for messages delivered while a window client is VISIBLE — routing
+ * keys on visibility, never focus (oracle: `messaging-web-visibility-routing`).
+ */
+export declare function onMessage(messaging: Messaging, nextOrObserver: NextFn<MessagePayload> | Observer<MessagePayload>): Unsubscribe;
+/** Whether every API FCM requires exists here — always true in the sandbox. */
+export declare function isSupported(): Promise<boolean>;
+export declare const sandbox: {
+    /**
+     * Inject a delivery into the client plane, optionally setting the
+     * simulated window client's visibility first. Routes through the broker's
+     * captured visibility rule, so a `visible` spec lands on `onMessage`
+     * handlers and a `hidden` spec on `onBackgroundMessage` handlers.
+     */
+    deliver(messaging: Messaging, spec: DeliverSpec): Promise<DeliveryResult>;
+    /** The module-default simulated service-worker registration. */
+    registration(): SimulatedServiceWorkerRegistration;
+};
+export type { DeliverSpec, DeliveryResult, SimulatedServiceWorkerRegistration };
+//# sourceMappingURL=client.d.ts.map

package/dist/messaging/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/messaging/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,kCAAkC,EACxC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,IAAI,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAC3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAChB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AACD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,SAAS,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/F;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC,GAAG,QAAQ,CAAC,cAAc,CAAC,GAChE,WAAW,CAMb;AAED,+EAA+E;AAC/E,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAEpD;AAID,eAAO,MAAM,OAAO;IAClB;;;;;OAKG;uBACgB,SAAS,QAAQ,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IAGzE,gEAAgE;oBAChD,kCAAkC;CAGnD,CAAC;AAEF,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,kCAAkC,EAAE,CAAC"}