pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/messaging/broker/broker.ts

@@ -11,32 +11,19 @@
  *     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.
+ * Hosted and SharedWorker transports use the same broker. Token ownership,
+ * window visibility, and observers are grouped by recipient (installation,
+ * Firebase app, and Service Worker scope). Headless mirrors use one default
+ * recipient; transports supply explicit recipient identities.
  */
 import type { Sandbox } from '../../sandbox/types/service.js';
 import type { AuthState } from '../../sandbox/types/auth-state.js';
 import { emitSandboxEvent, makeServiceMutationEvent } from '../../sandbox/internal/sandbox-impl.js';
+import type { MessagingEventOperation } from '../events.js';
+import { deliveryHistory } from './delivery-history.js';
+import { getClock } from '../../sandbox/clock.js';
 import { BrokerSendError, unregisteredTokenEnvelope, invalidTopicNameEnvelope } from './envelopes.js';
+import { isMessagingSnapshot, type MessagingSnapshot, type TokenRecord } from './persistence.js';
 import { mintToken } from './tokens.js';
 import { validateMessage, isValidTopicName, canonicalTopicName, TOKEN_SHAPE_RE } from './validate.js';
 import type {
@@ -44,10 +31,13 @@ import type {
   BrokerMessage,
   ClientVisibilityState,
   DeliveredPayload,
+  DeliveryLogEntry,
+  DeliveryStage,
   DeliveryResult,
   DeliveryRoute,
   MessagingBrokerConfig,
   PayloadHandler,
+  RegisteredToken,
   ResolvedTarget,
   TopicManagementOutcome,
 } from './types.js';
@@ -64,10 +54,7 @@ export const DEFAULT_SENDER_ID = '999999999999';
 /** The id the mirrors use for the single simulated window client. */
 export const DEFAULT_CLIENT_ID = 'window-default';
 
-interface TokenRecord {
-  registrationId: string;
-  state: 'active' | 'unregistered';
-}
+const DEFAULT_RECIPIENT = 'sandbox-default';
 
 /** Ops run on the admin/send plane or the SDK control plane — never a rules identity. */
 const ADMIN_AUTH: AuthState = null;
@@ -80,14 +67,15 @@ export class MessagingBroker {
   /** registrationId → active token (stability per registration is the captured contract). */
   private readonly registrations = new Map<string, string>();
   /** token → record. Deleted tokens stay, flipped to `unregistered`, so dead sends 404. */
-  private readonly tokens = new Map<string, TokenRecord>();
+  private readonly tokenRecords = new Map<string, TokenRecord>();
   /** topic → subscribed tokens. */
   private readonly subscriptions = new Map<string, Set<string>>();
   /** Window clients and their visibility — THE routing input (never focus). */
-  private readonly clients = new Map<string, ClientVisibilityState>();
-  private readonly foregroundHandlers = new Set<PayloadHandler>();
-  private readonly backgroundHandlers = new Set<PayloadHandler>();
+  private readonly clients = new Map<string, { state: ClientVisibilityState; recipientId: string }>();
+  private readonly foregroundHandlers = new Map<PayloadHandler, string>();
+  private readonly backgroundHandlers = new Map<PayloadHandler, string>();
   private numericIdCounter = 0;
+  private readonly changeListeners = new Set<() => void>();
 
   constructor(options: MessagingBrokerConfig & { sandbox?: Sandbox } = {}) {
     this.projectId = options.projectId ?? DEFAULT_PROJECT_ID;
@@ -95,6 +83,44 @@ export class MessagingBroker {
     this.sandbox = options.sandbox;
   }
 
+  /** Durable token state only; live browser connections are restored by their clients. */
+  snapshot(): MessagingSnapshot {
+    return {
+      version: 1,
+      tokens: [...this.tokenRecords].map(([token, record]) => [token, { ...record }]),
+      topics: [...this.subscriptions].map(([topic, tokens]) => [topic, [...tokens]]),
+    };
+  }
+
+  restore(data: unknown): void {
+    if (!isMessagingSnapshot(data)) throw new Error('Invalid Messaging persistence snapshot.');
+    this.registrations.clear();
+    this.tokenRecords.clear();
+    this.subscriptions.clear();
+    for (const [token, record] of data.tokens) {
+      this.tokenRecords.set(token, { ...record });
+      const isActive = record.state === 'active';
+      if (isActive) this.registrations.set(record.registrationId, token);
+    }
+    for (const [topic, tokens] of data.topics) this.subscriptions.set(topic, new Set(tokens));
+  }
+
+  reset(): void {
+    this.registrations.clear();
+    this.tokenRecords.clear();
+    this.subscriptions.clear();
+    this.changed();
+  }
+
+  onChange(listener: () => void): () => void {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+
+  private changed(): void {
+    for (const listener of this.changeListeners) listener();
+  }
+
   // ── Token lifecycle ───────────────────────────────────────────────────────
 
   /**
@@ -102,12 +128,13 @@ export class MessagingBroker {
    * calls for the same registration (oracle: `messaging-web-token-stability`);
    * shape class per `mintToken` (oracle: `messaging-web-token-shape`).
    */
-  getTokenFor(registrationId: string): string {
+  getTokenFor(registrationId: string, recipientId = DEFAULT_RECIPIENT): string {
     const existing = this.registrations.get(registrationId);
     if (existing !== undefined) return existing;
     const token = mintToken();
     this.registrations.set(registrationId, token);
-    this.tokens.set(token, { registrationId, state: 'active' });
+    this.tokenRecords.set(token, { registrationId, recipientId, state: 'active' });
+    this.changed();
     this.emit('token_minted', { path: token, detail: { registrationId } });
     return token;
   }
@@ -127,15 +154,16 @@ export class MessagingBroker {
     const token = this.registrations.get(registrationId);
     if (token === undefined) return true;
     this.registrations.delete(registrationId);
-    const record = this.tokens.get(token);
+    const record = this.tokenRecords.get(token);
     if (record !== undefined) record.state = 'unregistered';
+    this.changed();
     this.emit('token_deleted', { path: token, detail: { registrationId } });
     return true;
   }
 
   /** `active` | `unregistered` (minted then deleted) | `unknown` (never minted here). */
   tokenState(token: string): 'active' | 'unregistered' | 'unknown' {
-    return this.tokens.get(token)?.state ?? 'unknown';
+    return this.tokenRecords.get(token)?.state ?? 'unknown';
   }
 
   // ── Topic / condition subscriptions ──────────────────────────────────────
@@ -189,6 +217,7 @@ export class MessagingBroker {
       outcome.successCount++;
     });
 
+    this.changed();
     this.emit('subscription_changed', {
       path: name,
       detail: {
@@ -210,6 +239,28 @@ export class MessagingBroker {
     return topics;
   }
 
+  /**
+   * Every device token the broker knows about, minted or merely subscribed,
+   * and the topics each is subscribed to (the `tokens` service-tool method's
+   * read). A token stays listed after `deleteTokenFor` invalidates it,
+   * reported `unregistered`, the same dead-is-dead-immediately contract
+   * {@link tokenState} already carries. A token this sandbox never minted but
+   * that `subscribeToTopic` accepted anyway is listed `unknown`, because it
+   * is genuinely part of the sandbox's subscription state even though this
+   * sandbox never issued it.
+   */
+  tokens(): RegisteredToken[] {
+    const known = new Set(this.tokenRecords.keys());
+    for (const set of this.subscriptions.values()) {
+      for (const token of set) known.add(token);
+    }
+    return [...known].sort().map((token) => ({
+      token,
+      state: this.tokenState(token),
+      topics: [...this.topicsOf(token)].sort(),
+    }));
+  }
+
   // ── Message intake (the admin mirror / future op-channel entry point) ────
 
   /**
@@ -264,8 +315,9 @@ export class MessagingBroker {
       detail: { target: target.kind, name: accepted.name, messageId, validateOnly },
     });
 
-    if (!validateOnly && this.matchesAnyRecipient(target)) {
-      this.route(this.toPayload(message, messageId));
+    if (!validateOnly) {
+      const payload = this.toPayload(message, messageId);
+      for (const recipientId of this.matchingRecipients(target)) this.route(payload, recipientId);
     }
     return accepted;
   }
@@ -276,20 +328,20 @@ export class MessagingBroker {
     return `${Date.now()}${String(this.numericIdCounter).padStart(6, '0')}`;
   }
 
-  private matchesAnyRecipient(target: ResolvedTarget): boolean {
-    if (target.kind === 'token') return this.tokenState(target.token) === 'active';
-    if (target.kind === 'topic') {
-      const set = this.subscriptions.get(target.topic);
-      if (set === undefined) return false;
-      for (const token of set) if (this.tokenState(token) === 'active') return true;
-      return false;
-    }
-    // Condition: re-evaluate the parsed expression per active token's topic set.
-    for (const [token, record] of this.tokens) {
-      if (record.state !== 'active') continue;
-      if (evaluateCondition(target.condition, this.topicsOf(token))) return true;
+  private matchingRecipients(target: ResolvedTarget): Set<string> {
+    const recipients = new Set<string>();
+    for (const [token, record] of this.tokenRecords) {
+      const isActive = record.state === 'active';
+      if (!isActive) continue;
+      let matches: boolean;
+      switch (target.kind) {
+        case 'token': matches = token === target.token; break;
+        case 'topic': matches = this.subscriptions.get(target.topic)?.has(token) === true; break;
+        case 'condition': matches = evaluateCondition(target.condition, this.topicsOf(token)); break;
+      }
+      if (matches) recipients.add(record.recipientId);
     }
-    return false;
+    return recipients;
   }
 
   private toPayload(message: BrokerMessage, messageId: string): DeliveredPayload {
@@ -313,8 +365,8 @@ export class MessagingBroker {
    * one simulated client in the degenerate case) so headless tests can
    * drive both routes.
    */
-  setClientVisibility(clientId: string, state: ClientVisibilityState): void {
-    this.clients.set(clientId, state);
+  setClientVisibility(clientId: string, state: ClientVisibilityState, recipientId = DEFAULT_RECIPIENT): void {
+    this.clients.set(clientId, { state, recipientId });
   }
 
   removeClient(clientId: string): void {
@@ -322,14 +374,14 @@ export class MessagingBroker {
   }
 
   /** Foreground (`onMessage`) handler. Returns an unsubscribe function. */
-  onForegroundMessage(handler: PayloadHandler): () => void {
-    this.foregroundHandlers.add(handler);
+  onForegroundMessage(handler: PayloadHandler, recipientId = DEFAULT_RECIPIENT): () => void {
+    this.foregroundHandlers.set(handler, recipientId);
     return () => this.foregroundHandlers.delete(handler);
   }
 
   /** Background (`onBackgroundMessage`) handler. Returns an unsubscribe function. */
-  onBackgroundMessage(handler: PayloadHandler): () => void {
-    this.backgroundHandlers.add(handler);
+  onBackgroundMessage(handler: PayloadHandler, recipientId = DEFAULT_RECIPIENT): () => void {
+    this.backgroundHandlers.set(handler, recipientId);
     return () => this.backgroundHandlers.delete(handler);
   }
 
@@ -345,26 +397,27 @@ export class MessagingBroker {
     notification?: { title?: string; body?: string; image?: string };
     from?: string;
     messageId?: string;
-  }): DeliveryResult {
+  }, recipientId = DEFAULT_RECIPIENT): DeliveryResult {
     const payload: DeliveredPayload = {
       from: spec.from ?? this.senderId,
       messageId: spec.messageId ?? crypto.randomUUID(),
     };
     if (spec.data !== undefined) payload.data = { ...spec.data };
     if (spec.notification !== undefined) payload.notification = { ...spec.notification };
-    return this.route(payload);
+    return this.route(payload, recipientId);
   }
 
   /**
    * THE captured routing rule (oracle: `messaging-web-visibility-routing`):
-   * foreground handlers iff ANY window client reports `visible`; otherwise
+   * foreground handlers iff a window of THIS recipient reports `visible`; otherwise
    * background handlers. Visibility, never focus. Routing is exclusive —
    * one route per delivery.
    */
-  private route(payload: DeliveredPayload): DeliveryResult {
+  private route(payload: DeliveredPayload, recipientId: string): DeliveryResult {
     let anyVisible = false;
-    for (const state of this.clients.values()) {
-      if (state === 'visible') {
+    for (const client of this.clients.values()) {
+      const isVisibleRecipient = client.recipientId === recipientId && client.state === 'visible';
+      if (isVisibleRecipient) {
         anyVisible = true;
         break;
       }
@@ -373,11 +426,13 @@ export class MessagingBroker {
     const handlers = route === 'foreground' ? this.foregroundHandlers : this.backgroundHandlers;
 
     this.emit('delivery_routed', {
-      detail: { route, visibleClient: anyVisible, messageId: payload.messageId },
+      detail: { route, recipientId, visibleClient: anyVisible, messageId: payload.messageId },
     });
 
     let handlerCount = 0;
-    for (const handler of [...handlers]) {
+    for (const [handler, handlerRecipient] of [...handlers]) {
+      const isRecipient = handlerRecipient === recipientId;
+      if (!isRecipient) continue;
       handlerCount++;
       // Each handler gets its own copy so a mutating consumer can't corrupt
       // its siblings' view of the captured envelope. A throwing handler must
@@ -390,12 +445,38 @@ export class MessagingBroker {
       }
     }
 
+    // The delivery history IS this event. `deliveries` folds the stream back
+    // into entries, so everything an entry reports has to ride here.
     this.emit('message_delivered', {
-      detail: { route, handlerCount, messageId: payload.messageId },
+      detail: {
+        recipientId,
+        route,
+        handlerCount,
+        handled: handlerCount > 0,
+        messageId: payload.messageId,
+        payload: structuredClone(payload),
+      },
     });
     return { route, handlerCount, payload };
   }
 
+  /**
+   * What was delivered, in delivery order: foreground or background, handled
+   * or not (the `deliveries` service-tool method's read). Folded out of the
+   * sandbox event stream's `message_delivered` events, which are the delivery
+   * history; the broker keeps no second copy. `since` is a clock timestamp
+   * cursor; entries at or after it are returned. A `send` with no matching
+   * recipient never calls {@link route}, so it emits nothing here. Only an
+   * actual routing decision does.
+   */
+  acknowledge(messageId: string, recipientId: string, observerId: string, stage: DeliveryStage): void {
+    this.emit('delivery_acknowledged', { detail: { messageId, recipientId, observerId, stage } });
+  }
+
+  deliveries(since?: number): DeliveryLogEntry[] {
+    return deliveryHistory(this.sandbox?.history() ?? [], since);
+  }
+
   // ── Event emission (Studio stream consumer seam) ──────────────────────────
 
   /**
@@ -403,12 +484,18 @@ export class MessagingBroker {
    * Best-effort, storage-precedent: a throw from the emit path must never
    * fail the messaging operation the caller just completed.
    */
-  private emit(op: string, fields: { path?: string; detail?: Record<string, unknown> }): void {
+  private emit(op: MessagingEventOperation, fields: { path?: string; detail?: Record<string, unknown> }): void {
     if (this.sandbox === undefined) return;
     try {
       emitSandboxEvent(
         this.sandbox,
-        makeServiceMutationEvent({ service: 'messaging', op, auth: ADMIN_AUTH, ...fields }),
+        makeServiceMutationEvent({
+          at: getClock(this.sandbox).now(),
+          service: 'messaging',
+          op,
+          auth: ADMIN_AUTH,
+          ...fields,
+        }),
         { service: 'messaging' },
       );
     } catch {

package/src/messaging/broker/delivery-history.ts

@@ -0,0 +1,49 @@
+import type { Sandbox } from '../../sandbox/types/service.js';
+import type { ServiceMutationEvent } from '../../sandbox/types/events.js';
+import type { DeliveredPayload, DeliveryLogEntry, DeliveryRoute, DeliveryStage, DeliveryAcknowledgment } from './types.js';
+
+/**
+ * Rebuild one delivery entry from the event that reported the delivery. The
+ * event carries everything the entry reports, so this reads fields rather than
+ * recomputing any of them.
+ */
+function toDeliveryLogEntry(event: ServiceMutationEvent): DeliveryLogEntry {
+  const detail = event.detail ?? {};
+  return {
+    messageId: String(detail.messageId),
+    recipientId: String(detail.recipientId ?? 'sandbox-default'),
+    receipt: 'unconfirmed',
+    acknowledgments: [],
+    route: detail.route as DeliveryRoute,
+    handled: detail.handled === true,
+    at: event.at,
+    payload: detail.payload as DeliveredPayload,
+  };
+}
+
+/** Reuse the retained event stream; acknowledgments have no separate persistent store. */
+export function deliveryHistory(history: ReturnType<Sandbox['history']>, since?: number): DeliveryLogEntry[] {
+  const events = history.filter((event): event is ServiceMutationEvent =>
+    event.kind === 'service_mutation' && event.service === 'messaging');
+  const evidence = new Map<string, DeliveryAcknowledgment[]>();
+  const key = (messageId: unknown, recipientId: unknown) => JSON.stringify([messageId, recipientId]);
+  for (const event of events) {
+    const unrelated = event.op !== 'delivery_acknowledged';
+    if (unrelated) continue;
+    const detail = event.detail ?? {};
+    const id = key(detail.messageId, detail.recipientId);
+    const acknowledgments = evidence.get(id) ?? [];
+    acknowledgments.push({ observerId: String(detail.observerId), stage: detail.stage as DeliveryStage, at: event.at });
+    evidence.set(id, acknowledgments);
+  }
+  const entries = events.filter(event => event.op === 'message_delivered').map(event => {
+    const entry = toDeliveryLogEntry(event);
+    entry.acknowledgments = evidence.get(key(entry.messageId, entry.recipientId)) ?? [];
+    const received = entry.acknowledgments.some(ack => ack.stage === 'received');
+    entry.receipt = received ? 'received' : 'unconfirmed';
+    return entry;
+  });
+  const allRetained = since === undefined;
+  if (allRetained) return entries;
+  return entries.filter(entry => entry.at >= since);
+}

package/src/messaging/broker/index.ts

@@ -42,15 +42,20 @@ export {
   EMPIRICAL_DATA_CAP_BYTES,
 } from './validate.js';
 export { mintToken, TOKEN_LENGTH, TOKEN_SUFFIX_PREFIX } from './tokens.js';
+export { DELIVERY_STAGES } from './types.js';
 export type {
+  DeliveryStage,
+  DeliveryAcknowledgment,
   AcceptedSend,
   BrokerMessage,
   ClientVisibilityState,
   DeliveredPayload,
+  DeliveryLogEntry,
   DeliveryResult,
   DeliveryRoute,
   MessagingBrokerConfig,
   PayloadHandler,
+  RegisteredToken,
   ResolvedTarget,
   TopicManagementOutcome,
 } from './types.js';
@@ -68,5 +73,11 @@ export function getMessagingBroker(sandbox: Sandbox, config?: MessagingBrokerCon
   if (existing !== undefined) return existing;
   const broker = new MessagingBroker({ ...config, sandbox });
   brokers.set(sandbox, broker);
+  sandbox.registerPersistableService('messaging', {
+    snapshot: () => broker.snapshot(),
+    restore: data => broker.restore(data),
+    reset: () => broker.reset(),
+    subscribe: listener => broker.onChange(listener),
+  });
   return broker;
 }

package/src/messaging/broker/persistence.ts

@@ -0,0 +1,54 @@
+import { TOKEN_SHAPE_RE, isValidTopicName } from './validate.js';
+
+export interface TokenRecord {
+  registrationId: string;
+  recipientId: string;
+  state: 'active' | 'unregistered';
+}
+
+export interface MessagingSnapshot {
+  version: 1;
+  tokens: Array<[string, TokenRecord]>;
+  topics: Array<[string, string[]]>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  const isObjectRecord = typeof value === 'object' && value !== null && !Array.isArray(value);
+  return isObjectRecord;
+}
+
+function isTokenEntry(value: unknown): value is [string, TokenRecord] {
+  const isPair = Array.isArray(value) && value.length === 2;
+  if (!isPair) return false;
+  const [token, record] = value;
+  const hasToken = typeof token === 'string' && TOKEN_SHAPE_RE.test(token);
+  const hasRecord = isRecord(record);
+  const isValidEntry = hasToken && hasRecord;
+  if (!isValidEntry) return false;
+  const hasRegistration = typeof record.registrationId === 'string' && record.registrationId.length > 0;
+  const hasRecipient = typeof record.recipientId === 'string' && record.recipientId.length > 0;
+  const hasState = record.state === 'active' || record.state === 'unregistered';
+  return hasRegistration && hasRecipient && hasState;
+}
+
+function isToken(value: unknown): value is string {
+  const hasTokenShape = typeof value === 'string' && TOKEN_SHAPE_RE.test(value);
+  return hasTokenShape;
+}
+
+function isTopicEntry(value: unknown): value is [string, string[]] {
+  const isPair = Array.isArray(value) && value.length === 2;
+  if (!isPair) return false;
+  const [topic, tokens] = value;
+  const hasTopic = typeof topic === 'string' && isValidTopicName(topic);
+  const hasTokens = Array.isArray(tokens) && tokens.every(isToken);
+  return hasTopic && hasTokens;
+}
+
+export function isMessagingSnapshot(value: unknown): value is MessagingSnapshot {
+  if (!isRecord(value)) return false;
+  const hasVersion = value.version === 1;
+  const hasTokens = Array.isArray(value.tokens) && value.tokens.every(isTokenEntry);
+  const hasTopics = Array.isArray(value.topics) && value.topics.every(isTopicEntry);
+  return hasVersion && hasTokens && hasTopics;
+}

package/src/messaging/broker/types.ts

@@ -88,6 +88,56 @@ export interface TopicManagementOutcome {
   errors: Array<{ index: number; reason: 'invalid-token' | 'unregistered-token' }>;
 }
 
+/**
+ * One token {@link MessagingBroker.tokens} reports: its state and the topics
+ * it is currently subscribed to. This is the seam the `tokens` service-tool
+ * method reads (`0014-service-tools-with-sdk-methods.md`); the broker already
+ * tracked this state privately for routing, and this is its first public
+ * read.
+ *
+ * `state` is `unknown` for a token that was never minted through
+ * {@link MessagingBroker.getTokenFor} in this sandbox but does appear in a
+ * topic's subscription set. `subscribeToTopic` accepts such a token, the
+ * captured contract for cross-sandbox fixture composition, so a listing that
+ * omitted it would under-report what the sandbox actually holds.
+ */
+export interface RegisteredToken {
+  token: string;
+  state: 'active' | 'unregistered' | 'unknown';
+  topics: string[];
+}
+
+/**
+ * One past delivery, as {@link MessagingBroker.deliveries} reports it. The
+ * broker computed a {@link DeliveryResult} on every `route()` call but never
+ * retained it; this is the retained form the `deliveries` service-tool method
+ * reads.
+ */
+export const DELIVERY_STAGES = [
+  'received', 'handler-completed', 'handler-rejected',
+  'display-requested', 'display-accepted', 'display-rejected',
+] as const;
+export type DeliveryStage = typeof DELIVERY_STAGES[number];
+export interface DeliveryAcknowledgment {
+  observerId: string;
+  stage: DeliveryStage;
+  at: number;
+}
+
+export interface DeliveryLogEntry {
+  recipientId: string;
+  /** Browser-reported evidence, not proof of OS display. */
+  receipt: 'unconfirmed' | 'received';
+  acknowledgments: DeliveryAcknowledgment[];
+  messageId: string;
+  route: DeliveryRoute;
+  /** Whether any handler on the chosen route ran (`handlerCount > 0`). */
+  handled: boolean;
+  /** Sandbox clock time the delivery was routed. */
+  at: number;
+  payload: DeliveredPayload;
+}
+
 export interface MessagingBrokerConfig {
   /** Project id minted into message resource names. */
   projectId?: string;

package/src/messaging/events.ts

@@ -0,0 +1,29 @@
+/**
+ * What the messaging surface puts on the sandbox event stream.
+ *
+ * The broker emits one event per token, subscription, and routing decision, so
+ * the stream carries the whole delivery history and no private log has to.
+ */
+import type { ServiceEventRecord } from '../sandbox/types/service-event-record.js';
+
+export const MESSAGING_EVENT_RECORD = {
+  service: 'messaging',
+  operations: [
+    'token_minted',
+    'token_deleted',
+    'subscription_changed',
+    'message_accepted',
+    'message_rejected',
+    'delivery_routed',
+    'message_delivered',
+    'delivery_acknowledged',
+  ],
+  target: {
+    name: 'token',
+    description: 'The registration token a token or subscription operation addressed.',
+    always: false,
+  },
+} as const satisfies ServiceEventRecord;
+
+/** Every operation the messaging surface emits. */
+export type MessagingEventOperation = (typeof MESSAGING_EVENT_RECORD)['operations'][number];

package/src/rules/api/case-types.ts

@@ -122,6 +122,13 @@ export interface RtdbCase {
   data?: Record<string, unknown>;
   /** Proposed write value (`newData`), for write/validate cases. */
   newData?: unknown;
+  /**
+   * The instant `now` reports in this case, in epoch milliseconds. A caller
+   * hosting a sandbox passes its sandbox clock so a `now`-gated rule moves
+   * with the sandbox rather than the wall clock. Omit to evaluate at the
+   * real current instant.
+   */
+  now?: number;
 }
 
 /** The outcome of running one RTDB case through `simulate`. */

package/src/rules/api/rtdb.ts

@@ -84,13 +84,19 @@ class DocumentRtdbRuleset implements RtdbRuleset {
   }
 
   private runOne(c: RtdbCase): RtdbCaseResult {
-    const result = this.doc.simulate({
+    // Assembled with explicit branches rather than conditional spreads: `data`,
+    // `newData`, and `now` each mean something different when absent, and an
+    // absent `now` in particular is the difference between "evaluate at this
+    // instant" and "evaluate at whatever the simulator decides".
+    const input: RtdbRulesSimulationInput = {
       operation: c.operation,
       path: c.path,
       auth: c.auth ?? null,
-      ...(c.data !== undefined ? { data: c.data } : {}),
-      ...(c.newData !== undefined ? { newData: c.newData } : {}),
-    });
+    };
+    if (c.data !== undefined) input.data = c.data;
+    if (c.newData !== undefined) input.newData = c.newData;
+    if (c.now !== undefined) input.now = c.now;
+    const result = this.doc.simulate(input);
     if (!result.success) {
       // Could not evaluate — report as unsupported rather than throw.
       return {
@@ -188,13 +194,15 @@ class CompiledRtdbRulesDocument implements RtdbRulesDocumentInternal {
   }
 
   simulate(input: RtdbRulesSimulationInput): SimulateResult {
-    return simulateRtdbRules(this.compiled, {
+    const simulation: SimulationInput = {
       operation: input.operation,
       path: input.path,
       auth: normalizeAuth(input.auth),
       mockData: input.mockData ?? input.data ?? {},
-      ...(input.newData !== undefined ? { newData: input.newData } : {}),
-    });
+    };
+    if (input.newData !== undefined) simulation.newData = input.newData;
+    if (input.now !== undefined) simulation.now = input.now;
+    return simulateRtdbRules(this.compiled, simulation);
   }
 }