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

package/src/sandbox/internal/sdk-observation.ts

@@ -0,0 +1,62 @@
+import type { UsageEvidence } from './usage-evidence.js';
+import type { EventService } from '../types/operation.js';
+import type { SdkActivityEvent, SdkActivityRecord } from './sdk-activity.js';
+
+/** SDK adapters use `database`; sandbox operation records use `rtdb`. */
+export function observationService(service: EventService | 'database'): EventService {
+  if (service === 'database') return 'rtdb';
+  return service;
+}
+
+/** Public SDK evidence only. No results, credentials, query values or DOM owners. */
+export interface SdkObservation {
+  readonly ai?: SdkActivityRecord['ai'];
+  /** Numeric usage evidence; never the result payload. */
+  readonly usage?: UsageEvidence;
+  /** Journal-local delivery order, used to reject replay without retaining IDs. */
+  readonly sequence: number;
+  /** Unique within this journal session, including repeated listener deliveries. */
+  readonly id: string;
+  readonly activityId: string;
+  readonly appId: string;
+  /** A retained source identity, not a permanent metric-series identifier. */
+  readonly sourceId: string;
+  readonly service: EventService;
+  readonly method: string;
+  readonly kind: SdkActivityRecord['kind'];
+  readonly status: SdkActivityRecord['status'];
+  /** `remove` releases retained state. It is never a call or delivery. */
+  readonly phase: Exclude<SdkActivityEvent['phase'], 'progress'>;
+  readonly deliveryNumber: number;
+  /** Wall-clock observation time for display. */
+  readonly at: number;
+  /** Monotonic observation time for rate windows, local to this realm. */
+  readonly monotonicAt: number;
+}
+
+export function sdkObservation(
+  event: SdkActivityEvent,
+  at: number,
+  monotonicAt: number,
+  sequence: number,
+): SdkObservation | undefined {
+  if (event.phase === 'progress' || (event.phase === 'transport' && !event.record.ai)) return undefined;
+  const { record, phase } = event;
+  return Object.freeze({
+    ...(event.usage ? { usage: Object.freeze({ ...event.usage }) } : {}),
+    ...(record.ai ? { ai: record.ai } : {}),
+    sequence,
+    id: `${record.id}/${phase}/${record.deliveryCount}`,
+    activityId: record.id,
+    appId: record.appId,
+    sourceId: record.sourceId,
+    service: observationService(record.service),
+    method: record.method,
+    kind: record.kind,
+    status: record.status,
+    phase,
+    deliveryNumber: record.deliveryCount,
+    at,
+    monotonicAt,
+  });
+}

package/src/sandbox/internal/sdk-rates.ts

@@ -0,0 +1,240 @@
+import type { UsageEvidence } from './usage-evidence.js';
+import { sdkActivity, type SdkActivityRecord, type createSdkActivityJournal } from './sdk-activity.js';
+import type { EventService } from '../types/operation.js';
+import { observationService, type SdkObservation } from './sdk-observation.js';
+import { sdkMethodCoverage, sdkUntrackedMethods, type SdkMethodCategory } from './sdk-coverage.js';
+
+const RETAINED_SECONDS = 60;
+const WINDOW_SECONDS = 5;
+function ringSlot(second: number): number {
+  return ((second % RETAINED_SECONDS) + RETAINED_SECONDS) % RETAINED_SECONDS;
+}
+interface Bucket { second: number; calls: number; deliveries: number }
+interface UsageBucket { aiCompleted: number; aiInputTokens: number; aiOutputTokens: number; aiEstimatedTokens: number; aiUnknownUsage: number; aiFailures: number;  second: number; documentReads: number; documentWrites: number; documentDeletes: number; payloadBytes: number; uploadedBytes: number; downloadedBytes: number; unmeasured: number }
+export interface ServiceUsageRate {
+  readonly aiCompleted?: number;
+  readonly aiInputTokens?: number;
+  readonly aiOutputTokens?: number;
+  readonly aiEstimatedTokens?: number;
+  readonly aiUnknownUsage?: number;
+  readonly aiFailures?: number;
+
+  readonly uploadedBytes?: number;
+  readonly downloadedBytes?: number;
+  readonly documentReads: number;
+  readonly documentWrites: number;
+  readonly documentDeletes: number;
+  readonly payloadBytes: number;
+  readonly unmeasured: number;
+}
+const usageKeys = ['aiCompleted', 'aiInputTokens', 'aiOutputTokens', 'aiEstimatedTokens', 'aiUnknownUsage', 'aiFailures', 'documentReads', 'documentWrites', 'documentDeletes', 'payloadBytes', 'uploadedBytes', 'downloadedBytes', 'unmeasured'] as const;
+function emptyUsage(second: number): UsageBucket {
+  return { second, aiCompleted: 0, aiInputTokens: 0, aiOutputTokens: 0, aiEstimatedTokens: 0, aiUnknownUsage: 0, aiFailures: 0, documentReads: 0, documentWrites: 0, documentDeletes: 0, payloadBytes: 0, uploadedBytes: 0, downloadedBytes: 0, unmeasured: 0 };
+}
+interface Series {
+  service: EventService;
+  method: string;
+  category: SdkMethodCategory;
+  buckets: Bucket[];
+  activeListeners: number;
+  observed: boolean;
+}
+export interface SdkRateBucket {
+  readonly second: number;
+  readonly calls: number;
+  readonly deliveries: number;
+}
+export interface SdkMethodRate {
+  readonly method: string;
+  readonly category: SdkMethodCategory;
+  readonly callsPerSecond: number;
+  readonly deliveriesPerSecond: number;
+  readonly activeListeners: number;
+  readonly observed: boolean;
+  readonly buckets: readonly SdkRateBucket[];
+}
+export interface AiRequestObservation { readonly response?: SdkActivityRecord['response']; readonly id: string; readonly startedAt?: number; readonly startedSecond?: number; readonly at: number; readonly second: number; readonly method: string; readonly status: string; readonly detail: NonNullable<SdkActivityRecord['ai']> }
+export interface SdkServiceRate {
+  readonly aiInProgress?: number;
+  readonly aiRequests?: readonly AiRequestObservation[];
+  readonly service: EventService;
+  readonly usage?: ServiceUsageRate;
+  readonly lastActivityAt?: number;
+  readonly usageBuckets?: readonly (ServiceUsageRate & { readonly second: number })[];
+  /** Latest activity window survives idle time; bounded to 60 one-second buckets. */
+  readonly history?: { readonly endSecond: number; readonly startedSecond: number; readonly methods: readonly SdkMethodRate[]; readonly usageBuckets?: readonly (ServiceUsageRate & { readonly second: number })[] };
+  /** Unsupported services have no methods or numeric totals to imply zero usage. */
+  readonly coverage: 'partial' | 'unsupported';
+  readonly untrackedMethods: readonly string[];
+  readonly observed: boolean;
+  readonly methods: readonly SdkMethodRate[];
+}
+export interface SdkRateSnapshot {
+  readonly monotonicAt: number;
+  readonly windowSeconds: number;
+  readonly services: readonly SdkServiceRate[];
+}
+
+/**
+ * One accumulator per ordered journal observer stream. Sequence watermarks discard
+ * replay without retaining completed activities. Only live listener IDs are held.
+ * Fixed method coverage bounds series count; fixed rings bound event storage.
+ */
+export function createSdkRates(options: { monotonicNow?: () => number; activeListeners?: readonly SdkActivityRecord[] } = {}) {
+  const now = options.monotonicNow ?? (() => performance.now());
+  const series = new Map<string, Series>();
+  const startedSecond = Math.floor(now() / 1000);
+  const lastActivity = new Map<EventService, { second: number; at: number }>();
+  const active = new Map<string, Series>();
+  const usage = new Map<EventService, UsageBucket[]>();
+  function recordUsage(service: EventService, second: number, evidence: UsageEvidence): void {
+    let ring = usage.get(service);
+    if (!ring) { ring = Array.from({ length: RETAINED_SECONDS }, () => emptyUsage(-Infinity)); usage.set(service, ring); }
+    const slot = ringSlot(second);
+    if (ring[slot]!.second !== second) ring[slot] = emptyUsage(second);
+    for (const key of usageKeys) {
+      const value = evidence[key];
+      if (value !== undefined && Number.isFinite(value) && value >= 0) ring[slot]![key] += value;
+    }
+  }
+  const aiRequests: AiRequestObservation[] = [];
+  const aiActive = new Map<string, { at: number; second: number }>();
+  let sequence = 0;
+  for (const service of ['firestore', 'rtdb', 'storage', 'ai'] as const) {
+    for (const entry of sdkMethodCoverage(service)) {
+      series.set(`${service}/${entry.method}`, {
+        service, ...entry, observed: false, activeListeners: 0,
+        buckets: Array.from({ length: RETAINED_SECONDS }, () => ({ second: -Infinity, calls: 0, deliveries: 0 })),
+      });
+    }
+  }
+  // A late subscriber can seed the live gauge without inventing historical calls.
+  for (const listener of options.activeListeners ?? []) {
+    if (listener.kind !== 'subscription' || listener.endedAt !== undefined) continue;
+    const service = observationService(listener.service);
+    const row = series.get(`${service}/${listener.method}`);
+    if (row && !active.has(listener.id)) {
+      active.set(listener.id, row);
+      ++row.activeListeners;
+      row.observed = true;
+    }
+  }
+  function record(event: SdkObservation, response?: SdkActivityRecord['response']): void {
+    if (event.sequence <= sequence) return;
+    sequence = event.sequence;
+    const row = series.get(`${event.service}/${event.method}`);
+    if (!row) return;
+    if (event.service === 'ai' && event.phase === 'start') aiActive.set(event.activityId, { at: event.at, second: Math.floor(event.monotonicAt / 1000) });
+    if (event.usage) {
+      recordUsage(event.service, Math.floor(event.monotonicAt / 1000), event.usage);
+      lastActivity.set(event.service, { second: Math.floor(event.monotonicAt / 1000), at: event.at });
+    }
+    if (event.ai && event.phase !== 'remove') {
+      const index = aiRequests.findIndex(request => request.id === event.activityId);
+      const previous = aiRequests[index];
+      const request = Object.freeze({ id: event.activityId, startedAt: previous?.startedAt ?? aiActive.get(event.activityId)?.at ?? event.at,
+        startedSecond: previous?.startedSecond ?? aiActive.get(event.activityId)?.second ?? Math.floor(event.monotonicAt / 1000),
+        at: event.at, second: Math.floor(event.monotonicAt / 1000), method: event.method, status: event.status, response, detail: event.ai });
+      if (index < 0) aiRequests.push(request); else aiRequests[index] = request;
+      if (aiRequests.length > 100) aiRequests.shift();
+    }
+    if (event.phase === 'transport') return;
+    if (event.phase === 'end' || event.phase === 'remove') {
+      aiActive.delete(event.activityId);
+      const listener = active.get(event.activityId);
+      if (listener) {
+        --listener.activeListeners;
+        active.delete(event.activityId);
+      }
+      return;
+    }
+    row.observed = true;
+    const second = Math.floor(event.monotonicAt / 1000);
+    if ((event.phase === 'start' && row.category !== 'listener') || (event.phase === 'delivery' && row.category === 'listener')) {
+      lastActivity.set(event.service, { second, at: event.at });
+    }
+    const slot = ringSlot(second);
+    let bucket = row.buckets[slot]!;
+    if (bucket.second !== second) {
+      bucket = { second, calls: 0, deliveries: 0 };
+      row.buckets[slot] = bucket;
+    }
+    if (event.phase === 'start') {
+      ++bucket.calls;
+      if (event.kind === 'subscription' && !active.has(event.activityId)) {
+        ++row.activeListeners;
+        active.set(event.activityId, row);
+      }
+    } else if (event.phase === 'delivery') {
+      ++bucket.deliveries;
+    }
+  }
+  function snapshot(): SdkRateSnapshot {
+    const monotonicAt = now();
+    const second = Math.floor(monotonicAt / 1000);
+    const services = (['firestore', 'rtdb', 'storage', 'ai'] as const).map(service => {
+      const methods = [...series.values()].filter(row => row.service === service).map(row => {
+        const buckets = Array.from({ length: RETAINED_SECONDS }, (_, index) => {
+          const stamp = second - RETAINED_SECONDS + 1 + index;
+          const slot = ringSlot(stamp);
+          const bucket = row.buckets[slot]!;
+          return Object.freeze({ second: stamp, calls: bucket.second === stamp ? bucket.calls : 0,
+            deliveries: bucket.second === stamp ? bucket.deliveries : 0 });
+        });
+        const recent = buckets.slice(-WINDOW_SECONDS);
+        return Object.freeze({ method: row.method, category: row.category,
+          callsPerSecond: recent.reduce((sum, bucket) => sum + bucket.calls, 0) / WINDOW_SECONDS,
+          deliveriesPerSecond: recent.reduce((sum, bucket) => sum + bucket.deliveries, 0) / WINDOW_SECONDS,
+          activeListeners: row.activeListeners, observed: row.observed, buckets: Object.freeze(buckets) });
+      });
+      const last = lastActivity.get(service);
+      const historyEnd = last ? Math.min(second, last.second + 2) : second;
+      const historyMethods = methods.map(method => {
+        const row = series.get(`${service}/${method.method}`)!;
+        const buckets = Array.from({ length: RETAINED_SECONDS }, (_, index) => {
+          const stamp = historyEnd - RETAINED_SECONDS + 1 + index;
+          const bucket = row.buckets[ringSlot(stamp)]!;
+          return Object.freeze({ second: stamp, calls: bucket.second === stamp ? bucket.calls : 0,
+            deliveries: bucket.second === stamp ? bucket.deliveries : 0 });
+        });
+        return Object.freeze({ ...method, buckets: Object.freeze(buckets) });
+      });
+      const usageWindow = (end: number) => Object.freeze(Array.from({ length: RETAINED_SECONDS }, (_, index) => {
+        const stamp = end - RETAINED_SECONDS + 1 + index;
+        const bucket = usage.get(service)?.[ringSlot(stamp)];
+        return Object.freeze(bucket?.second === stamp ? { ...bucket } : emptyUsage(stamp));
+      }));
+      const totals = emptyUsage(second);
+      for (const bucket of usage.get(service) ?? []) {
+        if (bucket.second <= second && bucket.second > second - WINDOW_SECONDS) {
+          for (const key of usageKeys) totals[key] += bucket[key];
+        }
+      }
+      const measurement = Object.freeze({ ...(service === 'ai' ? { aiCompleted: totals.aiCompleted / WINDOW_SECONDS, aiInputTokens: totals.aiInputTokens / WINDOW_SECONDS, aiOutputTokens: totals.aiOutputTokens / WINDOW_SECONDS, aiEstimatedTokens: totals.aiEstimatedTokens / WINDOW_SECONDS, aiUnknownUsage: totals.aiUnknownUsage / WINDOW_SECONDS, aiFailures: totals.aiFailures / WINDOW_SECONDS } : {}), documentReads: totals.documentReads / WINDOW_SECONDS,
+        documentWrites: totals.documentWrites / WINDOW_SECONDS, documentDeletes: totals.documentDeletes / WINDOW_SECONDS,
+        payloadBytes: totals.payloadBytes / WINDOW_SECONDS, uploadedBytes: totals.uploadedBytes / WINDOW_SECONDS, downloadedBytes: totals.downloadedBytes / WINDOW_SECONDS, unmeasured: totals.unmeasured });
+      return Object.freeze({ service, ...(service === 'ai' ? { aiRequests: Object.freeze([...aiRequests]), aiInProgress: aiActive.size } : {}), usage: measurement, usageBuckets: usageWindow(second),
+        ...(last ? { lastActivityAt: last.at } : {}),
+        history: Object.freeze({ endSecond: historyEnd, startedSecond, methods: Object.freeze(historyMethods), usageBuckets: usageWindow(historyEnd) }), coverage: methods.length ? 'partial' as const : 'unsupported' as const,
+        untrackedMethods: sdkUntrackedMethods(service),
+        observed: methods.some(method => method.observed), methods: Object.freeze(methods) });
+    });
+    return Object.freeze({ monotonicAt, windowSeconds: WINDOW_SECONDS, services: Object.freeze(services) });
+  }
+  return Object.freeze({ record, snapshot });
+}
+
+/** Install independently of any UI; disposing a view must not dispose its monitor. */
+export function createSdkRateMonitor(
+  journal: ReturnType<typeof createSdkActivityJournal> = sdkActivity,
+  options: { monotonicNow?: () => number } = {},
+) {
+  const rates = createSdkRates({ ...options, activeListeners: journal.records() });
+  const dispose = journal.observe(event => rates.record(event, event.ai ? journal.records().find(record => record.id === event.activityId)?.response : undefined));
+  return Object.freeze({ snapshot: rates.snapshot, dispose });
+}
+
+// Separate source/dist runtime bundles share one observer and one accumulation.
+const RATES_KEY = Symbol.for('pyric.sdk-rates');
+const globalStore = globalThis as { [RATES_KEY]?: ReturnType<typeof createSdkRateMonitor> };
+export const sdkRates = globalStore[RATES_KEY] ?? (globalStore[RATES_KEY] = createSdkRateMonitor());

package/src/sandbox/internal/sdk-write-activity.ts

@@ -0,0 +1,14 @@
+import type { UsageEvidence } from './usage-evidence.js';
+import type { SdkActivityHandle } from './sdk-activity.js';
+
+/** A write acknowledgment is not a data delivery. Preserve the operation's error. */
+export async function runSdkWrite<T>(activity: SdkActivityHandle, write: () => T | PromiseLike<T>, usage?: () => UsageEvidence): Promise<T> {
+  try {
+    const result = await write();
+    activity.complete(usage?.());
+    return result;
+  } catch (error) {
+    activity.fail();
+    throw error;
+  }
+}

package/src/sandbox/internal/state-schemas.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { SeedUser } from '../../auth/seed-user.js';
+import type { StoredMetadata } from '../../storage/persistence.js';
+
+// Keep every exported account field in the file codec. Extra fields are
+// retained so reading a fixture does not silently discard its contents.
+const userFields = {
+  uid: z.string(),
+  createdAt: z.string().optional(),
+  lastLoginAt: z.string().nullable().optional(),
+  email: z.string().optional(),
+  password: z.string().optional(),
+  displayName: z.string().optional(),
+  customClaims: z.record(z.unknown()).optional(),
+  photoUrl: z.string().optional(),
+  phoneNumber: z.string().optional(),
+  emailVerified: z.boolean().optional(),
+  disabled: z.boolean().optional(),
+  tenantId: z.string().optional(),
+  providerId: z.string().optional(),
+  providerUserInfo: z.array(z.object({ providerId: z.string() })).optional(),
+} satisfies Record<keyof SeedUser, z.ZodType<unknown>>;
+
+const storageMetadataFields = {
+  fullPath: z.string(),
+  name: z.string(),
+  bucket: z.string(),
+  generation: z.string(),
+  metageneration: z.string(),
+  timeCreated: z.string(),
+  updated: z.string(),
+  size: z.number().int().nonnegative(),
+  contentType: z.string().optional(),
+  cacheControl: z.string().optional(),
+  contentDisposition: z.string().optional(),
+  contentEncoding: z.string().optional(),
+  contentLanguage: z.string().optional(),
+  customMetadata: z.record(z.string()).optional(),
+  downloadTokens: z.string().optional(),
+  md5Hash: z.string().optional(),
+} satisfies Record<keyof StoredMetadata, z.ZodType<unknown>>;
+
+/** Shared account file shape used by checkpoints and host state. */
+export const seedUserSchema = z.object(userFields).passthrough();
+
+/** Complete stored object metadata shared by state readers. */
+export const storedMetadataSchema = z.object(storageMetadataFields).passthrough();

package/src/sandbox/internal/state-values.ts

@@ -0,0 +1,20 @@
+import { assertEncodedDocValueDepth, encodeDocValue, rehydrateEncodedDocValue, requireDocumentData,
+  type DocValueEncoding } from '../../firestore/internal/value-codec.js';
+
+/** Preserve SDK values and escape ordinary marker-shaped maps before JSON removes their identity. */
+export function encodeStateDocument(document: Record<string, unknown>): Record<string, unknown> {
+  return requireDocumentData(JSON.parse(JSON.stringify(encodeDocValue(document))));
+}
+
+/** Decode declared encodings, preserving literal maps in legacy full states. */
+export function decodeStateDocument(
+  document: Record<string, unknown>,
+  encoding: DocValueEncoding | undefined,
+): Record<string, unknown> {
+  const isLegacyState = encoding === undefined;
+  if (isLegacyState) {
+    assertEncodedDocValueDepth(document);
+    return structuredClone(document);
+  }
+  return requireDocumentData(rehydrateEncodedDocValue(document, encoding));
+}

package/src/sandbox/internal/storage-activity.ts

@@ -0,0 +1,43 @@
+import { sdkActivity, type SdkActivityHandle } from './sdk-activity.js';
+import type { UsageEvidence } from './usage-evidence.js';
+
+interface StorageSource { readonly storage?: object; readonly port?: object; readonly bucket: string; readonly fullPath: string }
+const tasks = new WeakMap<object, SdkActivityHandle>();
+/** Called immediately before a real application observer; no payload is retained. */
+export function storageTaskProgress(task: object): void { tasks.get(task)?.progress(); }
+export function storageTaskResult(task: object): void {
+  const activity = tasks.get(task);
+  activity?.delivered(undefined, {});
+  // Each callback gets its own render window, but the result is counted once.
+  activity?.progress();
+}
+/** Preserve promises and UploadTask handles; observe completion without wrapping them. */
+export function observeStorageOperation<S extends StorageSource, A extends unknown[], R extends PromiseLike<unknown>>(
+  method: string, operation: (ref: S, ...args: A) => R,
+): (ref: S, ...args: A) => R {
+  return (ref, ...args) => {
+    const activity = sdkActivity.begin({ app: ref.storage ?? ref.port ?? ref, method, kind: 'operation',
+      source: { service: 'storage', target: `${ref.bucket}/${ref.fullPath}`, key: `storage:${ref.bucket}/${ref.fullPath}` } });
+    try {
+      const result = operation(ref, ...args);
+      if (method === 'uploadBytesResumable') tasks.set(result, activity);
+      void result.then(value => {
+        const usage: UsageEvidence = storageUsage(method, value);
+        // Results open a render window; byte usage is recorded once at its original boundary.
+        activity.delivered(undefined, method.startsWith('get') || method === 'listAll' ? usage : {});
+        if (method === 'uploadBytesResumable') activity.progress();
+        activity.complete(method.startsWith('get') || method === 'listAll' ? undefined : usage);
+      }, () => { activity.fail(); tasks.delete(result); });
+      return result;
+    } catch (error) { activity.fail(); throw error; }
+  };
+}
+function storageUsage(method: string, value: unknown): UsageEvidence {
+  if (method === 'getBytes' && value instanceof ArrayBuffer) return { downloadedBytes: value.byteLength };
+  if (method === 'getBlob' && value && typeof value === 'object' && 'size' in value && typeof value.size === 'number') return { downloadedBytes: value.size };
+  if (method.startsWith('upload') && value && typeof value === 'object' && 'metadata' in value) {
+    const metadata = value.metadata as { size?: number };
+    if (typeof metadata.size === 'number') return { uploadedBytes: metadata.size };
+  }
+  return {};
+}

package/src/sandbox/internal/usage-evidence.ts

@@ -0,0 +1,77 @@
+/** Numeric evidence only. Never retain documents, tokens, or serialized payloads. */
+export interface UsageEvidence {
+  readonly aiInputTokens?: number;
+  readonly aiOutputTokens?: number;
+  readonly aiEstimatedTokens?: number;
+  readonly aiUnknownUsage?: number;
+  readonly aiCompleted?: number;
+  readonly aiFailures?: number;
+
+  readonly uploadedBytes?: number;
+  readonly downloadedBytes?: number;
+  readonly documentReads?: number;
+  readonly documentWrites?: number;
+  readonly documentDeletes?: number;
+  readonly payloadBytes?: number;
+  readonly unmeasured?: number;
+}
+
+interface ReadSnapshot {
+  readonly size?: number;
+  readonly docs?: readonly unknown[];
+  readonly metadata?: { fromCache?: boolean; hasPendingWrites?: boolean };
+  exists?: boolean | (() => boolean);
+  docChanges?: () => readonly { type: string }[];
+  val?: () => unknown;
+}
+
+/** Query removals cannot distinguish deletion from leaving a query here. */
+export function firestoreReadUsage(value: unknown, listener = false, initial = true): UsageEvidence {
+  if (!value || typeof value !== 'object') return { unmeasured: 1 };
+  const snapshot = value as ReadSnapshot;
+  if (snapshot.metadata?.fromCache) return { documentReads: 0 };
+  if (Array.isArray(snapshot.docs)) {
+    if (!listener || initial) return { documentReads: Math.max(1, snapshot.docs.length) };
+    if (!snapshot.docChanges) return { unmeasured: 1 };
+    const changes = snapshot.docChanges();
+    return {
+      documentReads: changes.filter(change => change.type === 'added' || change.type === 'modified').length,
+      ...(changes.some(change => change.type === 'removed') ? { unmeasured: 1 } : {}),
+    };
+  }
+  if (snapshot.exists !== undefined) {
+    const exists = typeof snapshot.exists === 'function' ? snapshot.exists() : snapshot.exists;
+    return { documentReads: !listener || initial || exists ? 1 : 0 };
+  }
+  // Aggregation/index-entry scans have no document-result billing equivalent.
+  return { unmeasured: 1 };
+}
+
+/** Full callback JSON, not transport deltas, protocol overhead, or billed bytes. */
+export function databaseReadUsage(value: unknown): UsageEvidence {
+  if (!value || typeof value !== 'object' || !('val' in value) || typeof value.val !== 'function') {
+    return { unmeasured: 1 };
+  }
+  const json = JSON.stringify(value.val());
+  return json === undefined ? { unmeasured: 1 } : { payloadBytes: new TextEncoder().encode(json).byteLength };
+}
+
+export function firestoreWriteUsage(method: string): UsageEvidence | undefined {
+  if (['setDoc', 'updateDoc', 'addDoc'].includes(method)) return { documentWrites: 1 };
+  if (method === 'deleteDoc') return { documentDeletes: 1 };
+  if (method === 'writeBatch.commit' || method === 'runTransaction') return { unmeasured: 1 };
+  return undefined;
+}
+
+/** Shared page/host accounting: synthetic and estimated tokens are never backend usage. */
+export function aiCompletionUsage(detail: import('./ai-evidence.js').AiEvidence, method: string): UsageEvidence {
+  if (method === 'countTokens') return { aiCompleted: 1 };
+  const backend = detail.usageSource === 'backend';
+  const estimated = detail.usageSource === 'estimated' || detail.usageSource === 'scripted';
+  const incomplete = detail.inputTokens === undefined || detail.outputTokens === undefined || detail.usageSource === 'unknown';
+  return { aiCompleted: 1,
+    ...(backend ? { aiInputTokens: detail.inputTokens, aiOutputTokens: detail.outputTokens } : {}),
+    ...(estimated ? { aiEstimatedTokens: detail.totalTokens } : {}),
+    aiUnknownUsage: incomplete ? 1 : 0,
+  };
+}

package/src/sandbox/operation-record.ts

@@ -1,3 +1,4 @@
+import { observationPayload } from './internal/observation-payload.js';
 /**
  * Canonical operation records.
  *
@@ -22,6 +23,7 @@ import type {
 } from './types/events.js';
 
 export interface OperationRecord {
+  readonly observation?: import('./types/request-observation.js').RequestObservation;
   readonly id: string;
   readonly at: number;
   readonly eventKind: 'request' | 'operation' | 'listener';
@@ -32,6 +34,7 @@ export interface OperationRecord {
   readonly result?: RequestEvent['result'] | SandboxOperationEvent['result'] | SandboxListenerEvent['result'];
   readonly context: OperationContext;
   readonly rules: RulesDisposition;
+  readonly queryProof?: RequestEvent['queryProof'];
 }
 
 type OperationEvent = (RequestEvent | SandboxOperationEvent | SandboxListenerEvent) & EventProvenance;
@@ -213,9 +216,31 @@ function immutableValue(value: unknown): unknown {
   return value;
 }
 
+/** Auth changes have no rules seam; normalize their recorded outcome alongside data operations. */
+export function trafficOperationEvent(event: SandboxEvent): OperationEvent | null {
+  if (isOperationEvent(event)) return event;
+  const isAuthChange = event.kind === 'service_mutation' && event.service === 'auth';
+  if (!isAuthChange) return null;
+  const safe = (value: unknown): unknown => {
+    const preview = observationPayload(value);
+    if (!preview || preview.truncated) return undefined;
+    return JSON.parse(preview.text);
+  };
+  return {
+    kind: 'operation', id: event.id, at: event.at, service: 'auth', method: event.op,
+    path: event.path, auth: event.auth, origin: 'user', result: 'not-applicable',
+    rulesDisposition: { kind: 'not-evaluated', reason: 'not-a-rules-operation' },
+    operationContext: operationContextFor(event),
+    detail: { transition: event.op, evidence: safe(event.detail) },
+    resourceBefore: event.before === undefined ? undefined : { data: safe(event.before), exists: true },
+    resourceAfter: event.after === undefined ? undefined : { data: safe(event.after), exists: true },
+  };
+}
+
 /** Project either traffic event family into the canonical record. */
-export function toOperationRecord(event: SandboxEvent): OperationRecord | null {
-  if (!isOperationEvent(event)) return null;
+export function toOperationRecord(input: SandboxEvent): OperationRecord | null {
+  const event = trafficOperationEvent(input);
+  if (!event) return null;
   let methodVal = 'listen';
   let pathVal: string | undefined = undefined;
   if (event.kind === 'request' || event.kind === 'operation') {
@@ -233,9 +258,14 @@ export function toOperationRecord(event: SandboxEvent): OperationRecord | null {
   if (event.service !== undefined) {
     serviceVal = event.service;
   }
+  let queryProof: RequestEvent['queryProof'];
+  if ('queryProof' in event && event.queryProof) {
+    queryProof = immutableValue(event.queryProof) as RequestEvent['queryProof'];
+  }
   return Object.freeze({
-    id: event.id,
-    at: event.at,
+    id: event.kind === 'operation' ? event.observation?.id ?? event.id : event.id,
+    at: event.kind === 'operation' ? event.observation?.startedAt ?? event.at : event.at,
+    ...(event.kind === 'operation' && event.observation ? { observation: event.observation } : {}),
     eventKind: event.kind,
     service: serviceVal,
     method: methodVal,
@@ -244,5 +274,78 @@ export function toOperationRecord(event: SandboxEvent): OperationRecord | null {
     result: event.result,
     context: operationContextFor(event),
     rules: Object.freeze({ ...rulesDispositionFor(event) }),
+    queryProof,
   });
 }
+
+/** The five phases a listener passes through, whatever variant carried it. */
+export type ListenerPhase = 'attach' | 'detach' | 'delivery' | 'suppressed' | 'errored';
+
+/** Which phase an event reports, or `null` when it is not listener lifecycle. */
+function listenerPhaseOf(event: SandboxEvent): ListenerPhase | null {
+  if (event.kind === 'listener') return event.phase;
+  if (event.kind === 'listener_attach') return 'attach';
+  if (event.kind === 'listener_detach') return 'detach';
+  if (event.kind === 'listener_errored') return 'errored';
+  if (event.kind === 'snapshot_delivery') return 'delivery';
+  if (event.kind === 'snapshot_suppressed') return 'suppressed';
+  return null;
+}
+
+/** Only an errored listener met Security Rules; the other phases never did. */
+function listenerRulesDisposition(event: SandboxEvent, phase: ListenerPhase): RulesDisposition {
+  if (phase !== 'errored') return { kind: 'not-evaluated', reason: 'not-a-rules-operation' };
+  return rulesDispositionFor(event as OperationEvent);
+}
+
+/** The listener-shaped fields every lifecycle variant carries. */
+interface ListenerShape {
+  target: { kind: string; path?: string };
+  auth: AuthState;
+}
+
+/**
+ * Project one listener lifecycle event into the canonical record, with the
+ * phase as the record's `method`.
+ *
+ * Firestore reports lifecycle through its own `listener_attach` /
+ * `listener_detach` / `listener_errored` / `snapshot_delivery` /
+ * `snapshot_suppressed` variants; every other service reports it through the
+ * canonical `listener` variant. Both arrive here as the same five phases, so a
+ * caller paging listener activity never has to know which service produced it.
+ *
+ * Returns `null` for anything that is not listener lifecycle.
+ */
+export function toListenerRecord(event: SandboxEvent): OperationRecord | null {
+  const phase = listenerPhaseOf(event);
+  if (phase === null) return null;
+  const listener = event as unknown as ListenerShape;
+
+  let serviceVal: EventService = 'firestore';
+  if (event.service !== undefined) {
+    serviceVal = event.service;
+  }
+
+  let resultVal: OperationRecord['result'] = undefined;
+  if (event.kind === 'listener' && event.result !== undefined) {
+    resultVal = event.result;
+  } else if (phase === 'errored') {
+    resultVal = 'deny';
+  }
+
+  const record: {
+    -readonly [Key in keyof OperationRecord]: OperationRecord[Key];
+  } = {
+    id: event.id,
+    at: event.at,
+    eventKind: 'listener',
+    service: serviceVal,
+    method: phase,
+    auth: immutableAuthState(listener.auth),
+    result: resultVal,
+    context: operationContextFor(event),
+    rules: Object.freeze(listenerRulesDisposition(event, phase)),
+  };
+  if (listener.target.path !== undefined) record.path = listener.target.path;
+  return Object.freeze(record);
+}