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

package/src/sandbox/internal/sandbox-impl.ts

@@ -1,3 +1,4 @@
+import { EventHistory, type EventHistoryLimits } from './event-history.js';
 /**
  * Internal `Sandbox` implementation — backs the public interface from
  * `/app` and exposes the hook (`getEnv`) that other in-package modules
@@ -19,6 +20,7 @@
  */
 
 import { LocalEnvironment } from '../../firestore/sandbox/local-environment.js';
+import { SandboxClock, SANDBOX_CLOCK } from '../clock.js';
 import type { AuthState } from '../types/auth-state.js';
 import type { SandboxContext } from '../types/context.js';
 import { SandboxError } from '../types/errors.js';
@@ -31,6 +33,7 @@ import type {
   SandboxOperationEvent,
   SandboxRuntimeErrorEvent,
   ServiceMutationEvent,
+  ServiceMutationEventFields,
   SessionBoundaryEvent,
 } from '../types/events.js';
 import type { PersistableService, SandboxSnapshot } from '../types/persistence.js';
@@ -89,8 +92,8 @@ export class SandboxImpl implements LocalSandbox {
   /** Append-only history of every SandboxEvent emitted on this sandbox.
    *  Cleared on `reset()` AFTER the session_boundary event is appended,
    *  so the boundary is the last entry of the old session's history.
-   *  v1 doesn't cap; consumers persist the snapshot they need. */
-  private eventHistory: SandboxEvent[] = [];
+   *  Hosted adapters may bound observation retention; direct SDK roots retain full history. */
+  private readonly eventHistory: EventHistory;
 
   /** Ambient provenance for the current {@link runWithProvenance} window
    *  (undefined outside any window). Purely synchronous — set on entry,
@@ -108,6 +111,17 @@ export class SandboxImpl implements LocalSandbox {
   /** Subscribers to currentUser changes. Stable across reset() and
    *  dispose() the same way `eventSubs` is — dispose clears them. */
   private currentUserSubs = new Set<(user: AuthState) => void>();
+  private readonly documentChanges = new Set<(path: string | null) => void>();
+
+  /** Persistence tracks mutations independently of retained events and SDK transport. */
+  onDocumentChange(callback: (path: string | null) => void): () => void {
+    this.documentChanges.add(callback);
+    return () => { this.documentChanges.delete(callback); };
+  }
+
+  private readonly documentChanged = (path: string | null): void => {
+    for (const callback of this.documentChanges) callback(path);
+  };
 
   /** Persistence controller. Null until `enablePersistence` is called.
    *  Survives `reset()` so the next write re-flushes the empty state;
@@ -144,14 +158,28 @@ export class SandboxImpl implements LocalSandbox {
   private _onServiceRegistered: ((name: string, hooks: PersistableService) => void) | null = null;
   private _onServiceUnregistered: ((name: string) => void) | null = null;
 
-  private constructor(env: LocalEnvironment) {
+  /**
+   * The sandbox's one source of time. Handed to every service on this sandbox
+   * so a `serverTimestamp()`, a `request.time`, and a token's `iat` minted in
+   * the same operation agree. Survives `reset()`: a pinned instant belongs to
+   * the session, not to the data. Reached from outside through `getClock`.
+   */
+  readonly clock: SandboxClock;
+  /** The cross-module-instance key `getClock` reads. See `sandbox/clock.ts`. */
+  declare readonly [SANDBOX_CLOCK]: SandboxClock;
+
+  private constructor(env: LocalEnvironment, clock: SandboxClock, historyLimits?: EventHistoryLimits) {
+    this.eventHistory = new EventHistory(historyLimits);
     this._env = env;
+    this.clock = clock;
+    Object.defineProperty(this, SANDBOX_CLOCK, { value: clock, enumerable: false });
     this.attachToEnv();
   }
 
   /** Factory used by `initializeSandbox`. */
-  static createRoot(): SandboxImpl {
-    return new SandboxImpl(new LocalEnvironment());
+  static createRoot(historyLimits?: EventHistoryLimits): SandboxImpl {
+    const clock = new SandboxClock();
+    return new SandboxImpl(new LocalEnvironment(clock), clock, historyLimits);
   }
 
   /**
@@ -174,6 +202,7 @@ export class SandboxImpl implements LocalSandbox {
    * through {@link emit}. Refreshed on `reset()` after the env swap.
    */
   private attachToEnv(): void {
+    this.envUnsubs.push(this._env.onStateChange(this.documentChanged));
     this.envUnsubs.push(
       this._env.onRequest((event) => {
         // RequestEvent already carries `kind: 'request'` from buildRequestEvent.
@@ -207,7 +236,7 @@ export class SandboxImpl implements LocalSandbox {
         const ev: ListenerLifecycleEvent = {
           kind: 'listener_errored',
           id: makeSandboxEventId(),
-          at: Date.now(),
+          at: this.clock.now(),
           listenerId,
           target:
             target.kind === 'doc'
@@ -271,16 +300,19 @@ export class SandboxImpl implements LocalSandbox {
    * the raw fan-out + history append it wraps.
    */
   private dispatch(event: SandboxEvent): void {
+    event = { ...event, observedAt: Date.now() };
     // Append to history unconditionally — consumers that call
     // sandbox.history() expect every event the sandbox saw, regardless
     // of whether onEvent subscribers were attached at emit time.
-    this.eventHistory.push(event);
+    this.eventHistory.append(event);
     this.dispatchedCount++;
-    if (this.eventSubs.size === 0) return;
+    const hasNoSubscribers = this.eventSubs.size === 0;
+    if (hasNoSubscribers) return;
     for (const cb of this.eventSubs) {
       try {
         const result = cb(event) as unknown;
-        if (result && typeof (result as { then?: unknown }).then === 'function') {
+        const isAsyncResult = result !== null && result !== undefined && typeof (result as { then?: unknown }).then === 'function';
+        if (isAsyncResult) {
           (result as Promise<unknown>).catch(() => { /* swallow */ });
         }
       } catch { /* swallow — observational */ }
@@ -320,7 +352,7 @@ export class SandboxImpl implements LocalSandbox {
    * `dispose()` leaves the boundary as the final entry.
    */
   history(): SandboxEvent[] {
-    return [...this.eventHistory];
+    return this.eventHistory.snapshot();
   }
 
   /**
@@ -344,9 +376,19 @@ export class SandboxImpl implements LocalSandbox {
    * interleave after live ones. Returns the number of events primed.
    */
   primeEventHistory(events: readonly SandboxEvent[]): number {
-    if (this.eventHistory.length > 0) return 0;
-    if (events.length === 0) return 0;
-    this.eventHistory.push(...events);
+    const hasHistory = this.eventHistory.length > 0;
+    const isEmpty = events.length === 0;
+    if (hasHistory) return 0;
+    if (isEmpty) return 0;
+    for (const event of events) {
+      const unfinished = event.kind === 'operation' && event.observation?.status === 'pending';
+      if (unfinished) {
+        const observation: NonNullable<SandboxOperationEvent['observation']> = {
+          ...event.observation!, status: 'interrupted', error: { code: 'host-restarted' },
+        };
+        this.eventHistory.append({ ...event, observation });
+      } else this.eventHistory.append(event);
+    }
     return events.length;
   }
 
@@ -371,7 +413,7 @@ export class SandboxImpl implements LocalSandbox {
     const boundary: SessionBoundaryEvent = {
       kind: 'session_boundary',
       id: makeSandboxEventId(),
-      at: Date.now(),
+      at: this.clock.now(),
       phase: 'reset',
       priorOpCount: this.dispatchedCount,
     };
@@ -379,12 +421,13 @@ export class SandboxImpl implements LocalSandbox {
     // The boundary is now the last entry in eventHistory; clear the
     // history AFTER emit so consumers that took a snapshot before
     // reset() retain the boundary in their copy.
-    this.eventHistory = [];
+    this.eventHistory.clear();
 
     // Clear currentUser to null and notify — a reset wipes everything
     // including signed-in identity. Subscribers see the sign-out so
     // their UI / Firestore handles reflect the post-reset state.
-    if (this._currentUser !== null) {
+    const hadCurrentUser = this._currentUser !== null;
+    if (hadCurrentUser) {
       this._currentUser = null;
       this.notifyCurrentUserSubs(null);
     }
@@ -395,8 +438,9 @@ export class SandboxImpl implements LocalSandbox {
     for (const unsub of this.envUnsubs) unsub();
     this.envUnsubs = [];
     this._env.dispose();
-    this._env = new LocalEnvironment();
+    this._env = new LocalEnvironment(this.clock);
     this.attachToEnv();
+    this.documentChanged(null);
   }
 
   async resetAll(): Promise<{ errors: string[] }> {
@@ -433,7 +477,7 @@ export class SandboxImpl implements LocalSandbox {
     const boundary: SessionBoundaryEvent = {
       kind: 'session_boundary',
       id: makeSandboxEventId(),
-      at: Date.now(),
+      at: this.clock.now(),
       phase: 'dispose',
       priorOpCount: this.dispatchedCount,
     };
@@ -460,6 +504,7 @@ export class SandboxImpl implements LocalSandbox {
     // subscriptions on it would leak.
     this.eventSubs.clear();
     this.currentUserSubs.clear();
+    this.documentChanges.clear();
   }
 
   snapshot(): SandboxSnapshot {
@@ -736,18 +781,14 @@ export function primeEventHistory(
  * their activity lands on the same stream — e.g.
  *   `emitSandboxEvent(sandbox, userCreatedEvent, { service: 'auth' })`.
  *
- * STATUS (Wave 1.5, Gap #1): Auth / Storage / RTDB now emit here. They share
- * one additive union variant — {@link ServiceMutationEvent} (`kind:
- * 'service_mutation'`) — built via {@link makeServiceMutationEvent}, rather
- * than bending into Firestore's rule-eval-shaped `request`/`write` kinds.
- * Wired emit sites:
- *   - auth:    user create/update/delete, users-clear, sign-in, sign-out
- *              (`SandboxBackend` in `pyric/auth`).
- *   - storage: object put / delete / metadata-update (`pyric/storage`).
- *   - rtdb:    set / update / remove / transaction-commit
- *              (`RtdbBackend` in `pyric/database`, via the modular surface).
- * Firestore still rides the env→sandbox fan-out and is unchanged. See
- * the design rationale.
+ * Every non-Firestore service emits here, sharing one additive union variant,
+ * {@link ServiceMutationEvent} (`kind: 'service_mutation'`), built via
+ * {@link makeServiceMutationEvent}, rather than bending into Firestore's
+ * rule-eval-shaped `request`/`write` kinds. Which services those are, and
+ * which operations each of them emits, is declared once per service in
+ * `<surface>/events.ts` and derived into this variant's types by
+ * `sandbox/types/service-event-records.ts`. Firestore still rides the
+ * env→sandbox fan-out and is unchanged.
  *
  * Throws if `sandbox` wasn't produced by `initializeSandbox()` (same guard
  * as {@link getInternalEnv}).
@@ -767,10 +808,14 @@ export function emitSandboxEvent(
 }
 
 /**
- * Build a {@link ServiceMutationEvent} with a fresh `id` + `at` minted from
- * the same monotonic counter Firestore events use — so a non-Firestore
- * service (auth/storage/rtdb) doesn't have to re-implement id minting or
- * worry about colliding with the Firestore stream's ids.
+ * Build a {@link ServiceMutationEvent} with a fresh `id` minted from the same
+ * monotonic counter Firestore events use, so a non-Firestore service
+ * (auth/storage/rtdb) doesn't have to re-implement id minting or worry about
+ * colliding with the Firestore stream's ids.
+ *
+ * `at` is the caller's, and it is required: the instant an event carries is the
+ * sandbox clock's, which only the calling service can resolve, and a default
+ * here would silently stamp the wall clock onto a sandbox running virtual time.
  *
  * The returned event is NOT yet dispatched; hand it to
  * {@link emitSandboxEvent} (which stamps provenance and lands it on the
@@ -778,60 +823,61 @@ export function emitSandboxEvent(
  * site is `emitSandboxEvent(sandbox, makeServiceMutationEvent({ ... }), { service })`.
  */
 export function makeServiceMutationEvent(
-  fields: Omit<ServiceMutationEvent, 'kind' | 'id' | 'at'>,
+  fields: ServiceMutationEventFields,
 ): ServiceMutationEvent {
+  const { at, ...rest } = fields;
   return {
     kind: 'service_mutation',
     id: makeSandboxEventId(),
-    at: Date.now(),
-    ...fields,
+    at,
+    ...rest,
   };
 }
 
 export function makeSandboxOperationEvent(
-  fields: Omit<SandboxOperationEvent, 'kind' | 'id' | 'at'> & { at?: number },
+  fields: Omit<SandboxOperationEvent, 'kind' | 'id'>,
 ): SandboxOperationEvent {
   const { at, ...rest } = fields;
   return {
     kind: 'operation',
     id: makeSandboxEventId(),
-    at: at ?? Date.now(),
+    at,
     ...rest,
   };
 }
 
 export function makeSandboxCommitEvent(
-  fields: Omit<SandboxCommitEvent, 'kind' | 'id' | 'at'> & { at?: number },
+  fields: Omit<SandboxCommitEvent, 'kind' | 'id'>,
 ): SandboxCommitEvent {
   const { at, ...rest } = fields;
   return {
     kind: 'commit',
     id: makeSandboxEventId(),
-    at: at ?? Date.now(),
+    at,
     ...rest,
   };
 }
 
 export function makeSandboxListenerEvent(
-  fields: Omit<SandboxListenerEvent, 'kind' | 'id' | 'at'> & { at?: number },
+  fields: Omit<SandboxListenerEvent, 'kind' | 'id'>,
 ): SandboxListenerEvent {
   const { at, ...rest } = fields;
   return {
     kind: 'listener',
     id: makeSandboxEventId(),
-    at: at ?? Date.now(),
+    at,
     ...rest,
   };
 }
 
 export function makeSandboxRuntimeErrorEvent(
-  fields: Omit<SandboxRuntimeErrorEvent, 'kind' | 'id' | 'at'> & { at?: number },
+  fields: Omit<SandboxRuntimeErrorEvent, 'kind' | 'id'>,
 ): SandboxRuntimeErrorEvent {
   const { at, ...rest } = fields;
   return {
     kind: 'runtime_error',
     id: makeSandboxEventId(),
-    at: at ?? Date.now(),
+    at,
     ...rest,
   };
 }

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

@@ -0,0 +1,291 @@
+import type { AiEvidence } from './ai-evidence.js';
+import { firestoreReadUsage, databaseReadUsage, firestoreWriteUsage, type UsageEvidence } from './usage-evidence.js';
+import type { ListenerOwner } from '../types/events.js';
+import type { ServiceIndexQuery } from '../../rules/indexes/service-query.js';
+import { sdkObservation, type SdkObservation } from './sdk-observation.js';
+
+/** Page-side SDK evidence. Transport messages are deliberately not deliveries. */
+export interface SdkActivitySource {
+  readonly service: 'firestore' | 'database' | 'storage' | 'ai';
+  readonly target: string;
+  /** Canonical adapter descriptor, used only for identity, never exposed in records. */
+  readonly key: string;
+  readonly isQuery?: boolean;
+  readonly indexQuery?: ServiceIndexQuery;
+}
+
+export interface SdkActivityRecord {
+  readonly response?: Readonly<{ text: string; truncated: boolean }>;
+  readonly ai?: Readonly<AiEvidence>;
+  readonly id: string;
+  readonly appId: string;
+  readonly sourceId: string;
+  readonly service: SdkActivitySource['service'];
+  readonly target: string;
+  readonly isQuery: boolean;
+  readonly indexQuery?: ServiceIndexQuery;
+  readonly method: string;
+  readonly kind: 'operation' | 'subscription';
+  readonly status: 'pending' | 'active' | 'completed' | 'failed' | 'closed';
+  readonly startedAt: number;
+  readonly endedAt?: number;
+  readonly deliveryCount: number;
+  readonly lastDeliveryAt?: number;
+  readonly lastProgressAt?: number;
+  readonly owners: readonly ListenerOwner[];
+  /** Optional bridge identity. It is not the logical activity id. */
+  readonly transportId?: string;
+}
+
+export interface SdkActivityHandle {
+  readonly id: string;
+  /** Call immediately before handing a successful result to application code. */
+  delivered(snapshot?: unknown, usage?: UsageEvidence): void;
+  /** A task callback render signal, never a result or rate observation. */
+  progress(): void;
+  complete(usage?: UsageEvidence): void;
+  fail(usage?: UsageEvidence): void;
+  ai(detail: AiEvidence): void;
+  response(value: unknown): void;
+  close(): void;
+  transport(id: string): void;
+}
+
+export interface SdkActivityEvent {
+  readonly phase: 'start' | 'delivery' | 'end' | 'remove' | 'transport' | 'progress';
+  readonly record: SdkActivityRecord;
+  readonly usage?: UsageEvidence;
+}
+
+interface AppIdentity {
+  id: string;
+  sources: Map<string, { id: string; uses: number }>;
+}
+
+/**
+ * Lifecycle only: no DOM, payloads, callback wrappers, Promise chains, or
+ * backend events. Adapters report at their existing public execution boundary.
+ */
+export function createSdkActivityJournal(options: {
+  now?: () => number;
+  /** Independent of the sandbox clock and wall-clock adjustments. */
+  monotonicNow?: () => number;
+  retentionMs?: number;
+  maxCompleted?: number;
+  /** Protect completed deliveries until the page's render window has elapsed. */
+  correlationWindowMs?: number;
+} = {}) {
+  const now = options.now ?? Date.now;
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
+  const correlationWindowMs = options.correlationWindowMs ?? 250;
+  const retentionMs = Math.max(options.retentionMs ?? 30_000, correlationWindowMs);
+  const maxCompleted = options.maxCompleted ?? 100;
+  const apps = new WeakMap<object, AppIdentity>();
+  const records = new Map<string, SdkActivityRecord>();
+  const releaseSources = new Map<string, () => void>();
+  const subscribers = new Set<(event: SdkActivityEvent) => void>();
+  const observers = new Set<(observation: SdkObservation) => void>();
+  const observations: Array<{ event: SdkObservation; observers: Array<(event: SdkObservation) => void> }> = [];
+  let observationSequence = 0;
+  let observing = false;
+  let appSerial = 0;
+  let sourceSerial = 0;
+  let activitySerial = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+  let registrationId: string | undefined;
+  let silenced = false;
+  let pruning = false;
+
+  function notify(phase: SdkActivityEvent['phase'], record: SdkActivityRecord, usage?: UsageEvidence): void {
+    const observation = sdkObservation({ phase, record, usage }, now(), monotonicNow(), observationSequence + 1);
+    if (observation) {
+      observationSequence++;
+      observations.push({ event: observation, observers: [...observers] });
+    }
+    // An observer may synchronously cause another SDK call. Finish delivering
+    // this observation before delivering the next to any other observer.
+    if (!observing) {
+      observing = true;
+      try {
+        while (observations.length) {
+          const next = observations.shift()!;
+          for (const observer of next.observers) {
+            try { observer(next.event); } catch { /* Diagnostics cannot alter SDK behavior. */ }
+          }
+        }
+      } finally {
+        observing = false;
+      }
+    }
+    for (const subscriber of [...subscribers]) {
+      try { subscriber({ phase, record }); } catch { /* Diagnostics cannot alter SDK behavior. */ }
+    }
+  }
+
+  function remove(record: SdkActivityRecord): void {
+    if (!records.delete(record.id)) return;
+    releaseSources.get(record.id)?.();
+    releaseSources.delete(record.id);
+    notify('remove', record);
+  }
+
+  const retainedAt = (record: SdkActivityRecord) => Math.max(record.endedAt ?? 0, record.lastProgressAt ?? 0);
+  function prune(): void {
+    if (pruning) return;
+    pruning = true;
+    try {
+      clearTimeout(timer);
+      timer = undefined;
+      const ended = [...records.values()].filter(record => record.endedAt !== undefined)
+        .sort((a, b) => retainedAt(a) - retainedAt(b));
+      const expiredBefore = now() - retentionMs;
+      while (ended.length && (
+        retainedAt(ended[0]) <= expiredBefore
+        || (ended.length > maxCompleted && retainedAt(ended[0]) <= now() - correlationWindowMs)
+      )) {
+        remove(ended.shift()!);
+      }
+      if (ended.length && !disposed) {
+        const delay = ended.length > maxCompleted ? correlationWindowMs : retentionMs;
+        timer = setTimeout(prune, Math.max(1, retainedAt(ended[0]) + delay - now()));
+        // Retention must not keep a Node process alive.
+        if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+      }
+    } finally { pruning = false; }
+  }
+
+  return {
+    /** Host-side mirror calls implement transport, not another public SDK call. */
+    silence<T>(execute: () => T): T {
+      const previous = silenced;
+      silenced = true;
+      try { return execute(); } finally { silenced = previous; }
+    },
+    /** Synchronous registration scope, solely to join backend attach evidence. */
+    registering<T>(activity: SdkActivityHandle, register: () => T): T {
+      const previous = registrationId;
+      registrationId = activity.id;
+      try { return register(); } finally { registrationId = previous; }
+    },
+    registrationId(): string | undefined { return registrationId; },
+    begin(input: {
+      app: object;
+      source: SdkActivitySource;
+      method: string;
+      kind: SdkActivityRecord['kind'];
+      owners?: readonly ListenerOwner[];
+      transportId?: string;
+    }): SdkActivityHandle {
+      if (disposed || silenced) return {
+        id: '', delivered() {}, progress() {}, complete() {}, fail() {}, close() {}, transport() {}, ai() {}, response() {},
+      };
+      let app = apps.get(input.app);
+      if (!app) {
+        app = { id: `app-${++appSerial}`, sources: new Map() };
+        apps.set(input.app, app);
+      }
+      const key = JSON.stringify([input.source.service, input.source.key]);
+      let source = app.sources.get(key);
+      if (!source) {
+        source = { id: `${app.id}/source-${++sourceSerial}`, uses: 0 };
+        app.sources.set(key, source);
+      }
+      ++source.uses;
+      const id = `${app.id}/activity-${++activitySerial}`;
+      const record: SdkActivityRecord = Object.freeze({
+        id, appId: app.id, sourceId: source.id,
+        service: input.source.service, target: input.source.target,
+        isQuery: input.source.isQuery ?? false,
+        ...(input.source.indexQuery ? { indexQuery: structuredClone(input.source.indexQuery) } : {}),
+        method: input.method, kind: input.kind,
+        status: input.kind === 'operation' ? 'pending' : 'active',
+        startedAt: now(), deliveryCount: 0,
+        owners: Object.freeze([...(input.owners ?? [])]),
+        ...(input.transportId === undefined ? {} : { transportId: input.transportId }),
+      });
+      if (!disposed) {
+        records.set(id, record);
+        const identity = app;
+        const sourceIdentity = source;
+        releaseSources.set(id, () => {
+          if (--sourceIdentity.uses === 0) identity.sources.delete(key);
+        });
+        notify('start', record);
+      }
+      function update(phase: SdkActivityEvent['phase'], patch: Partial<SdkActivityRecord>, usage?: UsageEvidence): void {
+        const current = records.get(id);
+        if (!current || (current.endedAt !== undefined && !(phase === 'progress' && current.status === 'completed'))) return;
+        const next = Object.freeze({ ...current, ...patch });
+        records.set(id, next);
+        notify(phase, next, usage);
+      }
+      function end(status: 'completed' | 'failed' | 'closed', usage?: UsageEvidence): void {
+        update('end', { status, endedAt: now() }, usage);
+        prune();
+      }
+      return {
+        id,
+        delivered(snapshot, suppliedUsage) {
+          const current = records.get(id);
+          if (!current || (current.kind === 'operation' && current.deliveryCount > 0)) return;
+          let usage: UsageEvidence;
+          try {
+            usage = suppliedUsage ?? (current.service === 'firestore'
+              ? (current.method.endsWith('FromCache') ? { documentReads: 0 } : firestoreReadUsage(snapshot, current.kind === 'subscription', current.deliveryCount === 0))
+              : databaseReadUsage(snapshot));
+          } catch { usage = { unmeasured: 1 }; }
+          update('delivery', { deliveryCount: current.deliveryCount + 1, lastDeliveryAt: now() }, usage);
+        },
+        progress() { update('progress', { lastProgressAt: now() }); prune(); },
+        complete(usage) { end('completed', usage ?? (record.service === 'firestore' ? firestoreWriteUsage(record.method) : undefined)); },
+        fail(usage) { end('failed', usage); },
+        response(value) {
+          try {
+            const text = JSON.stringify(value, null, 2);
+            if (text !== undefined) update('transport', { response: Object.freeze({ text: text.slice(0, 65536), truncated: text.length > 65536 }) });
+          } catch { /* Diagnostics must never break the SDK response. */ }
+        },
+        ai(detail) { update('transport', { ai: Object.freeze({ ...detail }) }); },
+        close() { end('closed'); },
+        transport(transportId) { update('transport', { transportId }); },
+      };
+    },
+    records(): readonly SdkActivityRecord[] {
+      prune();
+      return [...records.values()];
+    },
+    subscribe(subscriber: (event: SdkActivityEvent) => void): () => void {
+      if (!disposed) subscribers.add(subscriber);
+      return () => { subscribers.delete(subscriber); };
+    },
+    /** Live observations, independent of history retention and Flow rendering. */
+    observe(observer: (observation: SdkObservation) => void): () => void {
+      if (!disposed) observers.add(observer);
+      return () => { observers.delete(observer); };
+    },
+    dispose(): void {
+      disposed = true;
+      clearTimeout(timer);
+      for (const record of [...records.values()]) remove(record);
+      subscribers.clear();
+      observers.clear();
+    },
+  };
+}
+
+/** Shared by the in-page SDK, bridge adapters, and the page's runtime chip. */
+const JOURNAL_KEY = Symbol.for('pyric.sdk-activity');
+const globalStore = globalThis as {
+  [JOURNAL_KEY]?: ReturnType<typeof createSdkActivityJournal>;
+};
+// SDK and runtime bundles may load separate source/dist copies in one realm.
+export const sdkActivity = globalStore[JOURNAL_KEY]
+  ?? (globalStore[JOURNAL_KEY] = createSdkActivityJournal());
+
+/** Return the same snapshot synchronously, without adding a Promise reaction. */
+export function finishSdkRead<T>(activity: SdkActivityHandle, snapshot: T): T {
+  activity.delivered(snapshot);
+  activity.complete();
+  return snapshot;
+}

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

@@ -0,0 +1,28 @@
+import { storageActivityCoverage } from '../../storage/activity-coverage.js';
+import type { EventService } from '../types/operation.js';
+import { firestoreActivityCoverage } from '../../firestore/activity-coverage.js';
+import { databaseActivityCoverage } from '../../database/activity-coverage.js';
+
+export type SdkMethodCategory = 'read' | 'write' | 'listener';
+export interface SdkMethodCoverage {
+  readonly method: string;
+  readonly category: SdkMethodCategory;
+}
+// Statically aggregate only service-owned data, never import service executors.
+// This keeps the foundation usable before SDK construction and prevents cycles.
+const services = [{ service: 'ai' as const, read: ['generateContent', 'generateContentStream', 'countTokens'], write: [], listener: [], untrackedMethods: [] }, firestoreActivityCoverage, databaseActivityCoverage, storageActivityCoverage];
+const methods = new Map<EventService, readonly SdkMethodCoverage[]>();
+const untracked = new Map<EventService, readonly string[]>();
+for (const service of services) {
+  methods.set(service.service, Object.freeze((['read', 'write', 'listener'] as const).flatMap(category =>
+    service[category].map(method => Object.freeze({ method, category })))));
+  untracked.set(service.service, Object.freeze([...service.untrackedMethods]));
+}
+const empty = Object.freeze([]);
+/** Explicit public data-operation coverage, not a claim about every SDK API. */
+export function sdkMethodCoverage(service: EventService): readonly SdkMethodCoverage[] {
+  return methods.get(service) ?? empty;
+}
+export function sdkUntrackedMethods(service: EventService): readonly string[] {
+  return untracked.get(service) ?? empty;
+}