pyric 0.0.1 → 0.1.0-alpha.10

package/dist/firestore-values/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Firestore value codec — the marker-based serialize/rehydrate of
+ * Firestore special scalar types (Timestamp, Bytes, LatLng/GeoPoint,
+ * Duration, Reference, Path, Vector).
+ *
+ * WHY THIS MODULE EXISTS (and why it is a LEAF)
+ * ---------------------------------------------
+ * Two very different consumers need this codec:
+ *
+ *   1. The sandbox persistence serializer (`sandbox/persistence/serialize.ts`)
+ *      — server-side, already pulls the whole engine, doesn't care about size.
+ *   2. The SharedWorker CLIENT (`@pyric/cli/.../worker/client.ts` via
+ *      `protocol.ts`) — runs in EVERY page that opens a serve session. It only
+ *      needs to reconstruct Timestamp/Bytes/LatLng instances from the JSON
+ *      markers the worker host wrote; it must NOT drag the rules engine,
+ *      simulator, parser, or sandbox into the per-page bundle.
+ *
+ * Importing the wrapper CLASSES from the `pyric/rules` BARREL would execute the
+ * entire rules index (parser + linter + simulator + evaluator → ~10 MB). The
+ * wrapper modules themselves are leaf — each depends only on `wrappers/base.js`
+ * which has zero imports — so this codec imports them by their DIRECT leaf
+ * paths. The result: importing this module pulls ONLY the seven small wrapper
+ * classes + their `base.js`, nothing heavy.
+ *
+ * Real types, not structural stand-ins: because the wrapper constructors are
+ * already leaf-cheap, the codec reconstructs the SAME real `Timestamp`/`Bytes`/
+ * `LatLng`/etc. classes the in-page (`pyric/firestore`) path yields. This keeps
+ * `instanceof` checks and method calls (`.toDate()`, `.toMillis()`, byte
+ * access, `.lat`/`.lng`) identical on both sides of the MessagePort and in IDB
+ * persistence — there is ONE codec, not two that can drift.
+ *
+ * Marker formats handled (must stay in sync with each wrapper's `toJSON()`):
+ *
+ * 1. `pyric/rules` wrapper markers (from `Timestamp.toJSON()` etc.):
+ *   { __type: 'timestamp', seconds, nanos }   → Timestamp
+ *   { __type: 'bytes', base64 }               → Bytes   (base64url)
+ *   { __type: 'latlng', lat, lng }            → LatLng
+ *   { __type: 'duration', seconds, nanos }    → Duration
+ *   { __type: 'reference', path }             → Reference
+ *   { __type: 'path', segments }              → Path
+ *   { __type__: '__vector__', value }         → Vector
+ *
+ * 2. `firebase/firestore` SDK markers (from fb.Timestamp.toJSON() etc.),
+ *    produced when `pyric/firestore`'s `getDoc` returns `firebase/firestore`
+ *    class instances that are then serialized via JSON.stringify:
+ *   { type: 'firestore/timestamp/1.0', seconds, nanoseconds } → Timestamp
+ *   { type: 'firestore/bytes/1.0', bytes }                    → Bytes (std b64)
+ *   { type: 'firestore/geoPoint/1.0', latitude, longitude }   → LatLng
+ *
+ * Unknown `__type`/`type` values pass through as plain objects rather than
+ * throwing — the rest of the doc still restores cleanly.
+ */
+/**
+ * Walk a parsed JSON tree and re-wrap any marker shape back into its real
+ * wrapper-class instance. Visits arrays and plain objects recursively. Plain
+ * values (and plain objects without a recognized discriminator) pass through.
+ *
+ * This is the canonical rehydrate used by BOTH the sandbox persistence
+ * serializer and the SharedWorker wire protocol, so the IDB format and the
+ * MessagePort wire format are guaranteed identical.
+ */
+export declare function rehydrateDocValue(value: unknown): unknown;
+//# sourceMappingURL=index.d.ts.map

package/dist/firestore-values/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/firestore-values/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAqCH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAqDzD"}

package/dist/firestore-values/index.js

@@ -0,0 +1,148 @@
+/**
+ * Firestore value codec — the marker-based serialize/rehydrate of
+ * Firestore special scalar types (Timestamp, Bytes, LatLng/GeoPoint,
+ * Duration, Reference, Path, Vector).
+ *
+ * WHY THIS MODULE EXISTS (and why it is a LEAF)
+ * ---------------------------------------------
+ * Two very different consumers need this codec:
+ *
+ *   1. The sandbox persistence serializer (`sandbox/persistence/serialize.ts`)
+ *      — server-side, already pulls the whole engine, doesn't care about size.
+ *   2. The SharedWorker CLIENT (`@pyric/cli/.../worker/client.ts` via
+ *      `protocol.ts`) — runs in EVERY page that opens a serve session. It only
+ *      needs to reconstruct Timestamp/Bytes/LatLng instances from the JSON
+ *      markers the worker host wrote; it must NOT drag the rules engine,
+ *      simulator, parser, or sandbox into the per-page bundle.
+ *
+ * Importing the wrapper CLASSES from the `pyric/rules` BARREL would execute the
+ * entire rules index (parser + linter + simulator + evaluator → ~10 MB). The
+ * wrapper modules themselves are leaf — each depends only on `wrappers/base.js`
+ * which has zero imports — so this codec imports them by their DIRECT leaf
+ * paths. The result: importing this module pulls ONLY the seven small wrapper
+ * classes + their `base.js`, nothing heavy.
+ *
+ * Real types, not structural stand-ins: because the wrapper constructors are
+ * already leaf-cheap, the codec reconstructs the SAME real `Timestamp`/`Bytes`/
+ * `LatLng`/etc. classes the in-page (`pyric/firestore`) path yields. This keeps
+ * `instanceof` checks and method calls (`.toDate()`, `.toMillis()`, byte
+ * access, `.lat`/`.lng`) identical on both sides of the MessagePort and in IDB
+ * persistence — there is ONE codec, not two that can drift.
+ *
+ * Marker formats handled (must stay in sync with each wrapper's `toJSON()`):
+ *
+ * 1. `pyric/rules` wrapper markers (from `Timestamp.toJSON()` etc.):
+ *   { __type: 'timestamp', seconds, nanos }   → Timestamp
+ *   { __type: 'bytes', base64 }               → Bytes   (base64url)
+ *   { __type: 'latlng', lat, lng }            → LatLng
+ *   { __type: 'duration', seconds, nanos }    → Duration
+ *   { __type: 'reference', path }             → Reference
+ *   { __type: 'path', segments }              → Path
+ *   { __type__: '__vector__', value }         → Vector
+ *
+ * 2. `firebase/firestore` SDK markers (from fb.Timestamp.toJSON() etc.),
+ *    produced when `pyric/firestore`'s `getDoc` returns `firebase/firestore`
+ *    class instances that are then serialized via JSON.stringify:
+ *   { type: 'firestore/timestamp/1.0', seconds, nanoseconds } → Timestamp
+ *   { type: 'firestore/bytes/1.0', bytes }                    → Bytes (std b64)
+ *   { type: 'firestore/geoPoint/1.0', latitude, longitude }   → LatLng
+ *
+ * Unknown `__type`/`type` values pass through as plain objects rather than
+ * throwing — the rest of the doc still restores cleanly.
+ */
+// Direct leaf imports — NOT the `pyric/rules` barrel. Each of these modules
+// depends only on `./base.js` (no imports), so this stays engine-free.
+import { Bytes } from '../rules/simulator/wrappers/bytes.js';
+import { Duration } from '../rules/simulator/wrappers/duration.js';
+import { LatLng } from '../rules/simulator/wrappers/latlng.js';
+import { Path } from '../rules/simulator/wrappers/path.js';
+import { Reference } from '../rules/simulator/wrappers/reference.js';
+import { Timestamp } from '../rules/simulator/wrappers/timestamp.js';
+import { Vector } from '../rules/simulator/wrappers/vector.js';
+/**
+ * Decode a base64url string (`-`/`_` alphabet, no padding) back into a
+ * Uint8Array. Mirrors the encode path in `Bytes.toBase64` (RFC 4648 section 5).
+ */
+function base64UrlDecode(s) {
+    const std = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
+    const bin = atob(std + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Decode a standard base64 string (`+`/`/` alphabet, possibly `=`-padded)
+ * back to a Uint8Array. Used for `firebase/firestore` Bytes which encode in
+ * standard base64 (unlike pyric/rules Bytes which use base64url).
+ */
+function base64StdDecode(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Walk a parsed JSON tree and re-wrap any marker shape back into its real
+ * wrapper-class instance. Visits arrays and plain objects recursively. Plain
+ * values (and plain objects without a recognized discriminator) pass through.
+ *
+ * This is the canonical rehydrate used by BOTH the sandbox persistence
+ * serializer and the SharedWorker wire protocol, so the IDB format and the
+ * MessagePort wire format are guaranteed identical.
+ */
+export function rehydrateDocValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(rehydrateDocValue);
+    const obj = value;
+    if (obj.__type__ === '__vector__' && Array.isArray(obj.value)) {
+        return new Vector(obj.value);
+    }
+    // pyric/rules wrapper marker form (used for IDB persistence + wire).
+    if (typeof obj.__type === 'string') {
+        switch (obj.__type) {
+            case 'timestamp':
+                return new Timestamp(obj.seconds, obj.nanos);
+            case 'bytes':
+                return new Bytes(base64UrlDecode(obj.base64));
+            case 'latlng':
+                return new LatLng(obj.lat, obj.lng);
+            case 'duration':
+                return new Duration(obj.seconds, obj.nanos);
+            case 'reference':
+                return new Reference(obj.path);
+            case 'path':
+                return new Path(obj.segments);
+        }
+    }
+    // firebase/firestore SDK marker form (produced when pyric/firestore's
+    // getDoc returns fb-SDK class instances and JSON.stringify is called).
+    if (typeof obj.type === 'string') {
+        switch (obj.type) {
+            case 'firestore/timestamp/1.0': {
+                // fb.Timestamp.toJSON() emits { type, seconds, nanoseconds }.
+                // The rules Timestamp uses nanos (not nanoseconds) — same value.
+                const seconds = obj.seconds;
+                const nanoseconds = obj.nanoseconds;
+                return new Timestamp(seconds, nanoseconds);
+            }
+            case 'firestore/bytes/1.0': {
+                // fb.Bytes.toJSON() emits { type, bytes } where bytes is standard base64.
+                return new Bytes(base64StdDecode(obj.bytes));
+            }
+            case 'firestore/geoPoint/1.0': {
+                // fb.GeoPoint.toJSON() emits { latitude, longitude, type }.
+                return new LatLng(obj.latitude, obj.longitude);
+            }
+        }
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        out[k] = rehydrateDocValue(v);
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/firestore-values/index.js.map

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

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

@@ -0,0 +1,171 @@
+/**
+ * The sandbox messaging broker — the ONE in-process FCM model every plane
+ * consumes:
+ *
+ *   - the client mirror (`pyric/messaging`) mints/deletes tokens and
+ *     registers FOREGROUND handlers;
+ *   - the sw mirror (`pyric/messaging/sw`) registers BACKGROUND handlers;
+ *   - the admin mirror (`pyric-admin/messaging`) drives message intake
+ *     (send / sendEach / topic management) via `pyric/messaging/internal`;
+ *   - Pyric Studio & tracing consume the typed `service_mutation` events
+ *     the broker emits onto the sandbox's unified `onEvent` stream —
+ *     tracing is a CONSUMER of the stream, never a parallel log.
+ *
+ * ── The worker-host seam (documented, deliberately NOT wired) ──────────────
+ * This broker is the in-process degenerate case (the transport research
+ * doc's "pure Node" arm). When `pyric dev`'s SharedWorker host adopts
+ * messaging, each public method below becomes one `messaging.*` op in
+ * `serve/worker/protocol.ts`'s `OpMessage` union, exactly like `rtdb.set` /
+ * `auth.signInEmail`:
+ *
+ *   send(message, {validateOnly})        → { method: 'messaging.send', message, validateOnly }
+ *   getTokenFor(registrationId)          → { method: 'messaging.getToken', registrationId }
+ *   deleteTokenFor(registrationId)       → { method: 'messaging.deleteToken', registrationId }
+ *   subscribeToTopic(tokens, topic)      → { method: 'messaging.subscribeToTopic', tokens, topic }
+ *   unsubscribeFromTopic(tokens, topic)  → { method: 'messaging.unsubscribeFromTopic', tokens, topic }
+ *   deliver(spec)                        → { method: 'messaging.deliver', spec }   (test/Studio driver)
+ *
+ * Client visibility maps onto the host's per-port sessions: each connected
+ * tab is one entry in `clients` (`setClientVisibility(portId, state)` on
+ * visibilitychange), so the captured routing rule — foreground iff ANY
+ * visible same-origin client — falls out of the same state machine that
+ * headless tests drive with a single simulated client. Rejections cross the
+ * wire as the `BrokerSendError.envelope` value (plain JSON, structured-
+ * clone-safe). No `serve/worker` file is touched by this slice.
+ */
+import type { Sandbox } from '../../sandbox/types/service.js';
+import type { AcceptedSend, BrokerMessage, ClientVisibilityState, DeliveryResult, MessagingBrokerConfig, PayloadHandler, TopicManagementOutcome } from './types.js';
+/** Default project id for sandbox-minted message resource names. */
+export declare const DEFAULT_PROJECT_ID = "pyric-sandbox";
+/**
+ * Default sender id (the `from` value on delivered payloads). A fixed
+ * 12-digit numeric string in the project-number shape production uses;
+ * `fromEqualsSenderId` is pinned by the receive-plane captures.
+ */
+export declare const DEFAULT_SENDER_ID = "999999999999";
+/** The id the mirrors use for the single simulated window client. */
+export declare const DEFAULT_CLIENT_ID = "window-default";
+export declare class MessagingBroker {
+    readonly projectId: string;
+    readonly senderId: string;
+    private readonly sandbox;
+    /** registrationId → active token (stability per registration is the captured contract). */
+    private readonly registrations;
+    /** token → record. Deleted tokens stay, flipped to `unregistered`, so dead sends 404. */
+    private readonly tokens;
+    /** topic → subscribed tokens. */
+    private readonly subscriptions;
+    /** Window clients and their visibility — THE routing input (never focus). */
+    private readonly clients;
+    private readonly foregroundHandlers;
+    private readonly backgroundHandlers;
+    private numericIdCounter;
+    constructor(options?: MessagingBrokerConfig & {
+        sandbox?: Sandbox;
+    });
+    /**
+     * Return the registration's token, minting on first call. Stable across
+     * calls for the same registration (oracle: `messaging-web-token-stability`);
+     * shape class per `mintToken` (oracle: `messaging-web-token-shape`).
+     */
+    getTokenFor(registrationId: string): string;
+    /**
+     * Invalidate the registration's token. Resolves truthy whether or not a
+     * token existed (oracle: `messaging-web-deletetoken-unregistered`
+     * `deleteTokenResolvedTruthy`). After deletion the token routes NO client
+     * delivery and the send plane answers with the captured UNREGISTERED
+     * envelope. Deliberate divergence from production's TIMING nuance: prod
+     * propagates unregistration asynchronously (a first send after delete was
+     * observed accepted once); the broker is deterministic — dead is dead
+     * immediately. The observation pins that nuance as environment-dependent
+     * and NOT contractual.
+     */
+    deleteTokenFor(registrationId: string): boolean;
+    /** `active` | `unregistered` (minted then deleted) | `unknown` (never minted here). */
+    tokenState(token: string): 'active' | 'unregistered' | 'unknown';
+    /**
+     * Subscribe tokens to a topic. Topic names validate against the captured
+     * `[a-zA-Z0-9-_.~%]` charset (a `/topics/` prefix is accepted and
+     * stripped, mirroring the admin SDK). Per-token outcomes:
+     *   - shape-invalid token       → error entry `invalid-token`
+     *   - minted-then-deleted token → error entry `unregistered-token`
+     *   - well-formed unknown token → SUCCESS (UNOBSERVED: production accepts
+     *     tokens it did not mint in this project only until IID rejects them;
+     *     the broker accepts them so cross-sandbox fixtures compose. Probe
+     *     candidate.)
+     */
+    subscribeToTopic(tokens: readonly string[], topic: string): TopicManagementOutcome;
+    /** Unsubscribe tokens from a topic. Same validation/outcome model as subscribe. */
+    unsubscribeFromTopic(tokens: readonly string[], topic: string): TopicManagementOutcome;
+    private mutateSubscriptions;
+    /** Topics an active token is currently subscribed to (routing input). */
+    private topicsOf;
+    /**
+     * Validate and accept a message — the send plane. Throws
+     * {@link BrokerSendError} with the exact captured envelope on every
+     * rejection; resolves an {@link AcceptedSend} whose `name` is the FCM
+     * resource name (`projects/<projectId>/messages/<id>`, numeric id for
+     * topic/condition targets, UUID-form for token targets).
+     *
+     * `validateOnly` (the admin SDK's `dryRun`) runs the IDENTICAL validation
+     * path and returns the SAME shape with a fake id (captured:
+     * `dryRunSameShapeAsReal` on every accept observation,
+     * `realSendEnvelopeIdentical` on every rejection observation). It skips
+     * only the delivery side effects.
+     */
+    send(message: BrokerMessage, options?: {
+        validateOnly?: boolean;
+    }): AcceptedSend;
+    /** Numeric message-id mint for topic/condition targets (prod shape: long numeric string). */
+    private mintNumericId;
+    private matchesAnyRecipient;
+    private toPayload;
+    /**
+     * Record a window client's visibility. Mirrors set this (per tab later,
+     * one simulated client in the degenerate case) so headless tests can
+     * drive both routes.
+     */
+    setClientVisibility(clientId: string, state: ClientVisibilityState): void;
+    removeClient(clientId: string): void;
+    /** Foreground (`onMessage`) handler. Returns an unsubscribe function. */
+    onForegroundMessage(handler: PayloadHandler): () => void;
+    /** Background (`onBackgroundMessage`) handler. Returns an unsubscribe function. */
+    onBackgroundMessage(handler: PayloadHandler): () => void;
+    /**
+     * Inject a delivery directly into the client plane (the mirrors'
+     * `sandbox.deliver` driver; later the host's `messaging.deliver` op).
+     * Builds the captured envelope shape — top-level keys exactly
+     * `data`/`from`/`messageId` (+ `notification` unless data-only) — and
+     * routes it by the visibility rule.
+     */
+    deliver(spec: {
+        data?: Record<string, string>;
+        notification?: {
+            title?: string;
+            body?: string;
+            image?: string;
+        };
+        from?: string;
+        messageId?: string;
+    }): DeliveryResult;
+    /**
+     * THE captured routing rule (oracle: `messaging-web-visibility-routing`):
+     * foreground handlers iff ANY window client reports `visible`; otherwise
+     * background handlers. Visibility, never focus. Routing is exclusive —
+     * one route per delivery.
+     */
+    private route;
+    /**
+     * Land a broker operation on the sandbox's unified event stream.
+     * Best-effort, storage-precedent: a throw from the emit path must never
+     * fail the messaging operation the caller just completed.
+     */
+    private emit;
+}
+/**
+ * Evaluate a (pre-validated) condition against a token's topic set. Re-uses
+ * the same grammar as `parseCondition`; kept here because evaluation is a
+ * routing concern, not a validation concern.
+ */
+export declare function evaluateCondition(condition: string, topics: ReadonlySet<string>): boolean;
+//# sourceMappingURL=broker.d.ts.map

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

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