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

package/src/sandbox/replay/index.ts

@@ -1,3 +1,4 @@
+import { assertCompleteHistory } from '../internal/history-integrity.js';
 /**
  * Replay — capture a session via `sandbox.history()` and re-issue
  * every write against a fresh sandbox; the engine classifies any
@@ -38,7 +39,7 @@
  *                          subtree differs.
  *   - `time-drift`      — like `sentinel-drift` but specifically a
  *                          captured `serverTimestamp`. Surfaces when
- *                          `pinRequestTime: false` and the wall clock
+ *                          `pinRequestTime: false` and the sandbox clock
  *                          advanced between capture and replay.
  *   - `real-divergence` — anything else. If the captured metadata
  *                          doesn't license drift at this exact leaf,
@@ -112,6 +113,7 @@ export function replay(
   options: ReplayOptions = {},
   originalState?: Record<string, DocData>,
 ): ReplayResult {
+  assertCompleteHistory(events);
   const pinRequestTime = options.pinRequestTime !== false; // default true
   const sandbox = initializeSandbox();
   const env = getInternalEnv(sandbox);
@@ -132,7 +134,8 @@ export function replay(
       ? new Timestamp(wEv.requestTime.seconds, wEv.requestTime.nanoseconds)
       : undefined;
 
-    if (wEv.autoId) {
+    const hasAutoId = Boolean(wEv.autoId);
+    if (hasAutoId) {
       // Auto-id create: split path, mint a fresh id, record the alias.
       const collection = wEv.path.slice(0, wEv.path.lastIndexOf('/'));
       const { path: mintedPath } = env.createWithAutoId(
@@ -146,14 +149,17 @@ export function replay(
     }
 
     try {
-      env.execute({
+      const operation: Parameters<typeof env.execute>[0] = {
         method: wEv.method,
         path: wEv.path,
         auth: wEv.auth,
-        ...(data !== undefined ? { data: data as DocData } : {}),
-        ...(requestTime ? { requestTime } : {}),
-        ...(bypassRules ? { bypassRules: true } : {}),
-      });
+      };
+      const hasData = data !== undefined;
+      const hasRequestTime = requestTime !== undefined;
+      if (hasData) operation.data = data as DocData;
+      if (hasRequestTime) operation.requestTime = requestTime;
+      if (bypassRules) operation.bypassRules = true;
+      env.execute(operation);
     } catch {
       // Replay denials surface as state divergence below; keep going
       // to surface as much as possible in one pass.
@@ -161,7 +167,8 @@ export function replay(
   }
 
   const replayedState = getInternalEnv(sandbox).snapshot();
-  const divergences = originalState
+  const hasOriginalState = originalState !== undefined;
+  const divergences = hasOriginalState
     ? computeDivergences(writes, originalState, replayedState, pathAliases)
     : [];
 

package/src/sandbox/types/errors.ts

@@ -2,6 +2,7 @@
  * Sandbox-layer error types: the error code union, the structured
  * denial-context payload, and the `SandboxError` class itself.
  */
+import type { QueryProofDiagnostic } from './query-proof.js';
 
 import type { AuthState } from './auth-state.js';
 
@@ -41,6 +42,7 @@ export type SandboxErrorCode =
  * reference traces.
  */
 export interface DenialContext {
+  queryProof?: QueryProofDiagnostic;
   /** The rule whose evaluation produced the denial (#370). */
   rule?: { line?: number; col?: number; column?: number; file?: string; citation?: string; expression?: string };
 
@@ -93,7 +95,7 @@ export interface DenialContext {
     readonly where?: readonly {
       readonly field: string;
       readonly op: string;
-      readonly value: string | number | boolean | null;
+      readonly value: string | number | boolean | null | readonly (string | number | boolean | null)[];
     }[];
     readonly limit?: number | null;
     readonly offset?: number | null;

package/src/sandbox/types/events.ts

@@ -1,3 +1,6 @@
+export type { RulesEvidence } from './rules-evidence.js';
+import type { QueryProofDiagnostic } from './query-proof.js';
+import type { ServiceMutationEvent } from './service-mutation-event.js';
 /**
  * The sandbox event surface: every discriminated event variant the
  * sandbox can emit, the shared provenance/service/actor/lens types that
@@ -11,6 +14,16 @@ import type {
   OperationContext,
   RulesDisposition,
 } from './operation.js';
+export type { MutationEventService, ServiceEventOperation } from './service-event-records.js';
+export type {
+  ServiceMutationEvent,
+  ServiceMutationEventFields,
+  ServiceMutationEventOf,
+} from './service-mutation-event.js';
+export type {
+  ServiceEventRecord,
+  ServiceEventTarget,
+} from './service-event-record.js';
 export type {
   ActivityEventProvenance,
   AuthLens,
@@ -110,6 +123,10 @@ export interface SnapshotErrorEvent {
  * @see traffic-monitor-decision.md for the field-by-field rationale.
  */
 export interface RequestEvent {
+  rulesEvidence?: import('./rules-evidence.js').RulesEvidence;
+  rulesEvidenceExpired?: boolean;
+  /** Primary static-proof explanation; evaluatedRule is secondary when present. */
+  queryProof?: QueryProofDiagnostic;
   /** Discriminator. */
   kind: 'request';
   /** Unique within a sandbox process. Useful for React list keys. */
@@ -125,6 +142,7 @@ export interface RequestEvent {
    *  and the sandbox upgraded it (today: thrown as SimulatorUnsupportedError,
    *  surfaced here as a discrete result so the panel can show it distinctly
    *  from a real denial). */
+  /** Local operational outcome. A proof-limited deny does not establish Firebase denial. */
   result: 'allow' | 'deny' | 'unsupported';
   /** Simulator debug messages — the per-rule trace (`Rule #0 (read) → ALLOW`).
    *  Same shape as `DenialEvent.reasons` so consumer code can share rendering. */
@@ -151,7 +169,8 @@ export interface RequestEvent {
   /** Parsed from the simulator's "Rule #N → …" debug line. Absent when no
    *  rule matched (e.g. no allow rules at the path — implicit deny). */
   matchedRule?: { ruleIndex: number; operations: string[] };
-  /** The DECIDING rule's verdict + 1-indexed source line + full sub-expression
+  /** For query-proof failures this is the actual residual evaluation, not the
+   * primary explanation; consult queryProof. Otherwise, the deciding rule's verdict + 1-indexed source line + full sub-expression
    *  trace, projected from the simulator's structured `RuleEvaluation`
    *  (additive: present on `result: 'allow' | 'deny'` Firestore events when the
    *  simulator produced a per-rule trace — the allowing rule on an allow, the
@@ -241,6 +260,79 @@ export interface WriteSandboxEvent {
   detail?: { admin?: boolean } & Record<string, unknown>;
 }
 
+/**
+ * Who owns a listener: the diagnostic attribution pyric records alongside
+ * its own listener events. This is pyric's own surface, not a Firebase one.
+ *
+ * Three kinds, each answering a different question about the same listener:
+ *
+ * - `frame`, where the listener was created. The first stack frame outside
+ *   pyric's own files at the moment the listener attached: the application
+ *   file, line, optional column, and the enclosing function name when the
+ *   runtime reported one. Captured once per attach, and only while listener
+ *   attribution is enabled, which a production build never is.
+ * - `tag`, what the application says owns the listener. Supplied by the
+ *   caller through the `owner` listen option, either as a name or as a DOM
+ *   element. For an element, `name` is the element's lower-case tag name and
+ *   `element` is a selector that identifies it again later.
+ * - `regions`, what the delivery changed. The selectors of the elements a
+ *   snapshot callback mutated during its own synchronous run. Present only in
+ *   a browser, and only on a delivery event.
+ * - `component`, the framework component that owns the listener, captured
+ *   during render. Unlike `frame`, which reads the call stack at the moment
+ *   the listener attaches, `component` reads the render-phase call stack of
+ *   the component that will go on to attach it. `@pyric/ui`'s framework
+ *   bindings capture this once per component instance and thread it through
+ *   the `owner` listen option.
+ *
+ * One listener can have more than one owner at once: an attach usually
+ * carries a frame and, when the caller supplied one, a tag or a component.
+ * Events therefore carry `owners` as an array rather than a single field. An
+ * event with no attribution omits the array entirely rather than carrying an
+ * empty one.
+ */
+export type ListenerOwner =
+  | {
+      kind: 'frame';
+      /** Path or URL of the application file that created the listener. */
+      file: string;
+      /** 1-based line number within {@link file}. */
+      line: number;
+      /** 1-based column, when the runtime's stack format carried one. */
+      column?: number;
+      /** Enclosing function name, when the runtime's stack format named one. */
+      function?: string;
+    }
+  | {
+      kind: 'tag';
+      /** Caller-supplied name, or the element's lower-case tag name. */
+      name: string;
+      /** Selector that re-identifies the element the caller named. */
+      element?: string;
+    }
+  | {
+      kind: 'regions';
+      /** Selectors of the elements the snapshot callback mutated. */
+      selectors: string[];
+    }
+  | {
+      kind: 'component';
+      /** The component function's name, read from the render-phase stack. A
+       *  minified production build mangles this like any other identifier;
+       *  the consuming UI states that rather than guessing at the original
+       *  name. */
+      name: string;
+      /** The chain of enclosing component frames, outermost first, best
+       *  effort. Absent when only one component frame was found. */
+      path?: string[];
+      /** Selector that re-identifies the component's root DOM element, once
+       *  the consumer has attached the returned `ref` to it. */
+      element?: string;
+      /** The root element's tag name, lower case, so a consumer can show the
+       *  element as `nav#conversations` when the selector is id-only. */
+      tag?: string;
+    };
+
 /**
  * Snapshot delivered to a `onSnapshot` listener's user callback.
  *
@@ -275,6 +367,11 @@ export interface SnapshotDeliveryEvent {
   /** The user op that triggered this re-eval. Absent on initial fire
    *  and on `deployRules`-driven re-evals. */
   triggeredBy?: { method: string; path: string };
+  /** Attribution for this delivery: the `regions` owner naming the elements
+   *  the callback mutated during its own synchronous run. The `frame` and
+   *  `tag` owners live on the matching `listener_attach` event; correlate on
+   *  `listenerId` rather than repeating them on every delivery. */
+  owners?: ListenerOwner[];
 }
 
 /**
@@ -320,6 +417,9 @@ export interface ListenerLifecycleEvent {
     message: string;
     reasons?: string[];
   };
+  /** Attribution recorded on `listener_attach`: the creation `frame` and,
+   *  when the caller supplied one, the `tag`. */
+  owners?: ListenerOwner[];
 }
 
 /**
@@ -337,80 +437,6 @@ export interface SessionBoundaryEvent {
   priorOpCount: number;
 }
 
-/**
- * Cross-service mutation event — the unified envelope the NON-Firestore
- * services (`auth` / `storage` / `rtdb`) emit into the single
- * `onEvent`/`history()` stream (Pyric Studio keystone, track T1).
- *
- * **Why a new variant rather than reusing `request`/`write`.** Firestore's
- * existing kinds are tightly coupled to the rules-simulator: `RequestEvent`
- * carries `result: 'allow'|'deny'`, `evalMs`, the simulator's `reasons[]`,
- * and `matchedRule`; `WriteSandboxEvent` carries Firestore-specific
- * `sentinels`, `autoId`, and a Firestore `requestTime` Timestamp. Auth user-
- * DB mutations (no path, no rule eval), Storage object puts, and RTDB tree
- * writes don't have those concepts, and bending them into the Firestore
- * shapes would either lie (synthesize a fake `result`/`requestTime`) or
- * pollute the Firestore consumer contract. So this is ONE small, additive
- * variant the three services share — Firestore consumers filter on their
- * existing `kind`s and never see it. See the design rationale.
- *
- * It is intentionally generic: `op` is a free-ish string discriminated by
- * `service`, and `before`/`after` are best-effort serializable snapshots
- * (omitted when not meaningful — e.g. a sign-out has no `after`). Studio's
- * data grids / Action Center render `service` + `op` + `path` directly and
- * diff `before`→`after` when both are present.
- */
-export interface ServiceMutationEvent {
-  kind: 'service_mutation';
-  id: string;
-  at: number;
-  /**
-   * Which service performed the mutation. Always one of the non-Firestore
-   * services — Firestore rides its own `request`/`write` path. (The
-   * provenance `service` field on the stamped event mirrors this; it is set
-   * redundantly here so a consumer matching purely on `kind` still gets the
-   * discriminator without reaching into provenance.)
-   */
-  service: 'auth' | 'storage' | 'rtdb' | 'messaging' | 'ai';
-  /**
-   * Service-scoped operation name. Stable, lowercase, snake/kebab-free:
-   *   - auth:    `user_create` | `user_update` | `user_delete` |
-   *              `users_clear` | `sign_in` | `sign_out`
-   *   - storage: `object_put` | `object_delete` | `metadata_update`
-   *   - rtdb:    `set` | `update` | `remove` | `transaction`
-   *   - ai:      `generate_content` | `stream_generate_content` |
-   *              `count_tokens` | `request_rejected` | `response_blocked` |
-   *              `model_substituted`
-   * New ops can be added without a breaking change (consumers switch with a
-   * default branch).
-   */
-  op: string;
-  /**
-   * The thing mutated, in the service's own addressing scheme:
-   *   - auth:    the user `uid` (or `'*'` for a clear-all). Absent for a
-   *              sign-out with no prior user.
-   *   - storage: the object `fullPath` (e.g. `avatars/alice.png`).
-   *   - rtdb:    the database path (e.g. `/rooms/r1/messages`), or for a
-   *              multi-path `update` the ref path the call targeted.
-   */
-  path?: string;
-  /** Identity in effect when the op ran (the service's `request.auth`
-   *  equivalent). `null` for admin/anonymous-driven mutations (e.g.
-   *  `sandbox.createUser`, an unauthenticated RTDB write). */
-  auth: AuthState;
-  /** Best-effort serializable snapshot of the state BEFORE the mutation.
-   *  Absent when there was no prior state (a create) or it isn't cheap to
-   *  capture. */
-  before?: unknown;
-  /** Best-effort serializable snapshot of the state AFTER the mutation.
-   *  Absent on deletes / sign-outs (nothing remains). */
-  after?: unknown;
-  /** Free-form, service-specific extras a consumer may surface without
-   *  re-deriving (e.g. storage `{ size, contentType }`, rtdb
-   *  `{ committed }` for a transaction). Kept loose on purpose — it's a
-   *  display hint, not a contract. */
-  detail?: Record<string, unknown>;
-}
 
 /**
  * Canonical service operation event. This is the service-neutral successor to
@@ -424,6 +450,7 @@ export interface ServiceMutationEvent {
  * their state is a Firestore document.
  */
 export interface SandboxOperationEvent {
+  observation?: import('./request-observation.js').RequestObservation;
   kind: 'operation';
   id: string;
   at: number;
@@ -526,6 +553,10 @@ export interface SandboxListenerEvent {
   reasons?: string[];
   rules?: SandboxOperationEvent['rules'];
   rulesDisposition?: RulesDisposition;
+  /** Attribution for this listener. `attach` carries the creation `frame`
+   *  and any caller-supplied `tag`; `delivery` carries the `regions` the
+   *  callback mutated. */
+  owners?: ListenerOwner[];
 }
 
 /** Canonical non-rules operational failure. */
@@ -544,6 +575,17 @@ export interface SandboxRuntimeErrorEvent {
   detail?: Record<string, unknown>;
 }
 
+/** A delivery failure, not a failed sandbox operation. Source IDs delimit the omitted batch. */
+export interface SandboxObservationGapEvent {
+  kind: 'observation_gap';
+  id: string;
+  at: number;
+  reason: 'frame-limit' | 'history-limit';
+  omittedCount: number;
+  firstEventId: string;
+  lastEventId: string;
+}
+
 /**
  * Discriminated union of every event the sandbox emits to
  * {@link Sandbox.onEvent} subscribers.
@@ -570,5 +612,6 @@ export type SandboxEvent = (
   | SandboxCommitEvent
   | SandboxListenerEvent
   | SandboxRuntimeErrorEvent
+  | SandboxObservationGapEvent
 ) &
   EventProvenance;

package/src/sandbox/types/index.ts

@@ -25,16 +25,28 @@ export { SandboxError } from './errors.js';
 
 export type { PersistableService, SandboxSnapshot } from './persistence.js';
 
+export {
+  MUTATION_EVENT_SERVICES,
+  SERVICE_EVENT_RECORDS,
+} from './service-event-records.js';
+
 export type {
   DenialEvent,
   ListenerLifecycleEvent,
+  ListenerOwner,
+  MutationEventService,
   RequestEvent,
   SandboxCommitEvent,
   SandboxEvent,
   SandboxListenerEvent,
   SandboxOperationEvent,
+  SandboxObservationGapEvent,
   SandboxRuntimeErrorEvent,
+  ServiceEventOperation,
+  ServiceEventRecord,
+  ServiceEventTarget,
   ServiceMutationEvent,
+  ServiceMutationEventFields,
   SessionBoundaryEvent,
   SnapshotDeliveryEvent,
   SnapshotErrorEvent,

package/src/sandbox/types/operation.ts

@@ -1,7 +1,12 @@
 /** Cross-service operation identity and Security Rules disposition. */
 
-/** Which sandbox service emitted an event. */
-export type EventService = 'firestore' | 'auth' | 'storage' | 'rtdb' | 'messaging' | 'ai';
+import type { MutationEventService } from './service-event-records.js';
+
+/** Which sandbox service emitted an event. Firestore is named directly because
+ * it rides its own rule-eval-shaped `request`/`write` path rather than the
+ * cross-service mutation envelope; every other service reaches this union by
+ * declaring an event record beside its own code. */
+export type EventService = 'firestore' | 'runtime' | MutationEventService;
 
 /** Who initiated the operation behind an event. Missing source is represented
  * explicitly as `unattributed`; it is never silently promoted to app traffic. */
@@ -28,14 +33,17 @@ export interface OperationContext {
   readonly planId?: string;
 }
 
-/** What happened at the Security Rules seam. Admin is a lens; `bypassed` is
+/** An evaluated/deny disposition records a local rejection, not proof completeness
+ * or Firebase parity. Consumers must also inspect accompanying queryProof.
+ * What happened at the Security Rules seam. Admin is a lens; `bypassed` is
  * the rules disposition. */
 export type RulesDisposition =
   | { kind: 'evaluated'; verdict: 'allow' | 'deny' }
   | { kind: 'bypassed'; reason: 'admin' }
   | {
       kind: 'not-evaluated';
-      reason: 'no-rules' | 'unsupported' | 'not-a-rules-operation' | 'runtime-error';
+      /** External execution supplies an SDK outcome, without a local rules evaluation. */
+      reason: 'no-rules' | 'unsupported' | 'not-a-rules-operation' | 'runtime-error' | 'external-execution';
     };
 
 /** Provenance consumed only by the firestore activity diagnostics. Bundled in
@@ -53,6 +61,8 @@ export interface ActivityEventProvenance {
 /** Compatibility provenance carried by sandbox events while producers and
  * consumers migrate to the canonical `operationContext`. */
 export interface EventProvenance {
+  /** Wall-clock observation time, independent of the simulated service clock. */
+  observedAt?: number;
   service?: EventService;
   actor?: EventActor;
   authLens?: AuthLens;

package/src/sandbox/types/persistence.ts

@@ -20,8 +20,8 @@
 export interface PersistableService {
   /**
    * Return a plain-JSON-serializable snapshot of this service's state.
-   * Called by the persistence controller on every flush. The return
-   * value is stored under the service's registered name in the
+   * Called when the service changes, or on every flush when `subscribe`
+   * is omitted. The return value is stored under the service's registered name in the
    * `services` map of the persisted blob.
    */
   snapshot(): unknown;

package/src/sandbox/types/query-proof.ts

@@ -0,0 +1,26 @@
+import type { QueryProofResidual } from '../../rules/simulator/query-proof.js';
+
+/** Local proof evidence. These categories do not claim a Firebase decision. */
+export interface QueryProofFailure {
+  kind: 'unsupported-predicate' | 'unsupported-path' | 'constraints-not-satisfied';
+  reason: string;
+  residual: QueryProofResidual;
+  /** Location of the rejected predicate, which may be inside a helper. */
+  predicate?: QueryProofFailure['rule'];
+  rule?: {
+    line?: number;
+    col?: number;
+    column?: number;
+    file?: string;
+    citation?: string;
+    expression?: string;
+  };
+}
+
+export interface QueryProofDiagnostic {
+  kind: QueryProofFailure['kind'] | 'residual-denied' | 'no-rule';
+  /** Rejected rules, in source order. None were evaluated against stored rows. */
+  failures: QueryProofFailure[];
+  /** Complete query identity, separate from the conservative proof projection. */
+  query?: unknown;
+}

package/src/sandbox/types/request-observation.ts

@@ -0,0 +1,25 @@
+import type { AiEvidence } from '../internal/ai-evidence.js';
+
+/** A cumulative execution snapshot. Its request ID survives lifecycle updates. */
+export interface RequestObservation {
+  readonly id: string;
+  readonly startedAt: number;
+  readonly endedAt?: number;
+  readonly status: 'pending' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+  readonly ai?: AiEvidence;
+  readonly response?: { readonly text: string; readonly truncated: boolean };
+  readonly error?: { readonly code: string };
+}
+
+/** Consistent execution labels for retained host and page observations. */
+export function requestStatusLabel(status: string): string {
+  switch (status) {
+    case 'pending': return 'In progress';
+    case 'completed': return 'Completed';
+    case 'failed': return 'Failed';
+    case 'cancelled': return 'Cancelled';
+    case 'interrupted': return 'Interrupted';
+    case 'closed': return 'Closed';
+    default: return 'Not recorded';
+  }
+}

package/src/sandbox/types/rules-evidence.ts

@@ -0,0 +1,37 @@
+export type RuleScalar = string | number | boolean | null;
+
+interface RuleCheckLocation {
+  expression: string;
+  parent: number | null;
+  operator?: string;
+  kind?: string;
+  helper?: string;
+  binding?: string;
+}
+
+export type RuleCheck = RuleCheckLocation & (
+  | { state: 'value'; value: RuleScalar }
+  | { state: 'error'; error: string }
+  | { state: 'skipped' | 'unavailable' }
+);
+
+/** Bounded evidence from the evaluation that handled a request; never a replay. */
+export interface RulesEvidence {
+  version: string;
+  scope: 'request' | 'query-residual';
+  decision: 'ALLOW' | 'DENY' | 'UNSUPPORTED';
+  truncated: boolean;
+  rules: Array<{
+    expression: string;
+    verdict: 'ALLOW' | 'DENY' | 'ERROR' | 'UNSUPPORTED';
+    line?: number;
+    path?: string;
+    error?: string;
+    checks: RuleCheck[];
+  }>;
+  paths: Array<{ path: string; matched: boolean; line?: number }>;
+  queryProof?: {
+    kind: string;
+    failures: Array<{ reason: string; expression?: string; line?: number }>;
+  };
+}

package/src/sandbox/types/service-event-record.ts

@@ -0,0 +1,34 @@
+/**
+ * The shape one service declares so the sandbox core knows what that service
+ * puts on the event stream.
+ *
+ * A record is authored next to the service it describes
+ * (`packages/pyric/src/<surface>/events.ts`), the way one tool method is one
+ * record file. The sandbox core derives the service union and each service's
+ * operation enum from those declarations rather than restating them, so a
+ * service cannot emit an operation it never declared and cannot be added to
+ * the stream vocabulary without declaring one.
+ */
+
+/** What a service event's `path` addresses, in that service's own scheme. */
+export interface ServiceEventTarget {
+  /** The addressing scheme's own name for the target, e.g. `uid`, `fullPath`. */
+  readonly name: string;
+  /** What the target names, for a consumer rendering the event. */
+  readonly description: string;
+  /** Whether every operation this service emits carries a target. */
+  readonly always: boolean;
+}
+
+/** One service's declaration of its slice of the event stream. */
+export interface ServiceEventRecord<
+  Service extends string = string,
+  Operation extends string = string,
+> {
+  /** The service name that appears on the event and in its provenance. */
+  readonly service: Service;
+  /** Every operation this service emits, in no significant order. */
+  readonly operations: readonly Operation[];
+  /** What the event's `path` addresses. */
+  readonly target: ServiceEventTarget;
+}

package/src/sandbox/types/service-event-records.ts

@@ -0,0 +1,42 @@
+/**
+ * Every service's event declaration, in one place, so the sandbox core can
+ * derive the stream's vocabulary instead of restating it.
+ *
+ * Why static imports rather than a registry the capabilities register into.
+ * The operation enums have to exist as types: `ServiceMutationEvent.op` is
+ * derived from them, and a value pushed into a registry at module load carries
+ * no type a `.d.ts` can name. A registry would also make the vocabulary depend
+ * on which surfaces a bundle happened to load, so the same event would be
+ * well-typed in one entry point and untyped in another. These imports reach
+ * six leaf files that declare data and import nothing but the record type, so
+ * the edge costs the central runtime no capability code.
+ */
+import { AI_EVENT_RECORD } from '../../ai/events.js';
+import { AUTH_EVENT_RECORD } from '../../auth/events.js';
+import { RTDB_EVENT_RECORD } from '../../database/events.js';
+import { FUNCTIONS_EVENT_RECORD } from '../../functions/events.js';
+import { MESSAGING_EVENT_RECORD } from '../../messaging/events.js';
+import { STORAGE_EVENT_RECORD } from '../../storage/events.js';
+import type { ServiceEventRecord } from './service-event-record.js';
+
+/** Keyed by the service name each record declares. */
+export const SERVICE_EVENT_RECORDS = {
+  auth: AUTH_EVENT_RECORD,
+  storage: STORAGE_EVENT_RECORD,
+  rtdb: RTDB_EVENT_RECORD,
+  messaging: MESSAGING_EVENT_RECORD,
+  ai: AI_EVENT_RECORD,
+  functions: FUNCTIONS_EVENT_RECORD,
+} as const satisfies Record<string, ServiceEventRecord>;
+
+/** Every service that emits the cross-service mutation envelope. */
+export type MutationEventService = keyof typeof SERVICE_EVENT_RECORDS;
+
+/** The operations one service declared. */
+export type ServiceEventOperation<Service extends MutationEventService> =
+  (typeof SERVICE_EVENT_RECORDS)[Service]['operations'][number];
+
+/** Every declared service name, as a runtime list. */
+export const MUTATION_EVENT_SERVICES = Object.keys(
+  SERVICE_EVENT_RECORDS,
+) as MutationEventService[];