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

package/src/sandbox/index.ts

@@ -29,7 +29,9 @@ export type {
   EventService,
   OperationContext,
   ListenerLifecycleEvent,
+  ListenerOwner,
   LocalSandbox,
+  MutationEventService,
   PersistableService,
   RequestEvent,
   RulesDisposition,
@@ -41,28 +43,48 @@ export type {
   SandboxEvent,
   SandboxListenerEvent,
   SandboxOperationEvent,
+  SandboxObservationGapEvent,
   SandboxRuntimeErrorEvent,
   SandboxSnapshot,
+  ServiceEventOperation,
+  ServiceEventRecord,
+  ServiceEventTarget,
   ServiceMutationEvent,
+  ServiceMutationEventFields,
   SessionBoundaryEvent,
   SnapshotDeliveryEvent,
   SnapshotErrorEvent,
   SnapshotSuppressedEvent,
   WriteSandboxEvent,
 } from './types/index.js';
-export { SandboxError } from './types/index.js';
+export { SandboxError, MUTATION_EVENT_SERVICES, SERVICE_EVENT_RECORDS } from './types/index.js';
 export {
   SandboxContextImpl,
   normalizeAuthState,
   validateAuthState,
 } from './sandbox-context.js';
+// The sandbox clock: the one source of time every service on the sandbox
+// reads. `getClock(sandbox).set(...)` / `.advance(...)` / `.reset()` move
+// Firestore `serverTimestamp()` and `request.time`, Realtime Database
+// `ServerValue.TIMESTAMP` and rules `now`, Storage `timeCreated` / `updated`,
+// auth token `iat` / `exp` / `auth_time`, and every listener and event stamp
+// together.
+export { SandboxClock, wallClockState } from './clock.js';
+export type { SandboxClockMode, SandboxClockState } from './clock.js';
+export { getClock } from './clock.js';
+
 export {
   isOperationEvent,
   operationContextFor,
   rulesDispositionFor,
+  toListenerRecord,
   toOperationRecord,
+  trafficOperationEvent,
 } from './operation-record.js';
-export type { OperationRecord } from './operation-record.js';
+export type { ListenerPhase, OperationRecord } from './operation-record.js';
+
+export { activeListeners, activeListenerTargetStartsWith } from './active-listeners.js';
+export type { ActiveListener, ActiveListenerTarget } from './active-listeners.js';
 
 // Remote sandbox (slice 1) — the brand + minimal channel contract that
 // lets `pyric-admin` recognize a Node-side handle onto the browser-hosted
@@ -82,15 +104,36 @@ export type {
 export { replay } from './replay/index.js';
 export type { Divergence, ReplayOptions, ReplayResult } from './replay/index.js';
 
+// Full sandbox state: the whole sandbox as one JSON value, and the total
+// replace that installs one. Firestore documents, the Realtime Database tree,
+// Storage objects with their bytes and metadata, auth accounts, and the three
+// rule sources. This is what a branch forks from and promotes onto.
+export { captureFullState, applyFullState, holdsBytesInline } from './full-state.js';
+export type {
+  AuthAccountsState,
+  DatabaseRuleset,
+  FullSandboxState,
+  FullStateCaptureOptions,
+  SandboxRuleSources,
+  SandboxService,
+  StorageObjectState,
+} from './full-state.js';
+
 // Branches — fork/apply/diff/promote/discard experiments built on top of
-// `snapshot()` + `replay()`. A branch is an isolated in-memory sandbox
-// seeded from a `SandboxSnapshot`; `apply` re-issues events via `replay`,
-// `diff` is a focused doc-level structural diff (reuses `Divergence`),
-// `promote` lands the branch's mutations on a target, `discard` drops it.
-// Substrate for Studio's agent dry-run/accept, rules-edit branches, and
-// time-travel. See the design rationale.
-export { apply, discard, diff, fork, promote } from './branches/index.js';
-export type { Branch, DiffTarget } from './branches/index.js';
+// `captureFullState()` + `applyFullState()`. A branch is an isolated
+// in-memory sandbox seeded from a `FullSandboxState`, so it carries every
+// service; `apply` re-issues captured writes onto it, `diff` walks the two
+// states service by service (reuses `Divergence`), `promote` writes that
+// same walk onto a target, `discard` drops it. Substrate for Studio's agent
+// dry-run/accept, rules-edit branches, and time-travel.
+export { apply, discard, diff, diffFullStates, fork, promote, promoteFullState } from './branches/index.js';
+export type {
+  Branch,
+  BranchCandidateRules,
+  BranchDivergence,
+  DiffTarget,
+  TreeChange,
+} from './branches/index.js';
 
 // Persistence — snapshot the sandbox to IndexedDB (or a custom backend)
 // and restore on next init. Turns the sandbox into the host page's

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

@@ -0,0 +1,38 @@
+/** Payload-free observations. Routed identity is distinct from backend-reported identity. */
+export interface AiEvidence {
+  requestedModel: string;
+  routedModel?: string;
+  reportedModel?: string;
+  engine: 'scripted' | 'openai' | 'gemini' | 'custom' | 'unknown';
+  endpoint?: string;
+  mappingReason?: string;
+  usageSource: 'backend' | 'estimated' | 'scripted' | 'unknown';
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  durationMs?: number;
+  firstChunkMs?: number;
+}
+// Out-of-band metadata never changes Firebase response envelopes.
+const key = Symbol.for('pyric.ai-evidence');
+const store = globalThis as { [key]?: WeakMap<object, Partial<AiEvidence>> };
+const evidence = store[key] ??= new WeakMap<object, Partial<AiEvidence>>();
+export function setAiEvidence<T extends object>(value: T, detail: Partial<AiEvidence>): T {
+  evidence.set(value, Object.freeze({ ...detail }));
+  return value;
+}
+export function getAiEvidence(value: object): Partial<AiEvidence> | undefined { return evidence.get(value); }
+/** Strip credentials, paths, and query parameters from diagnostic endpoints. */
+export function aiEndpoint(value?: string): string | undefined {
+  if (!value) return;
+  try { return new URL(value).origin; } catch { return 'Same-origin proxy'; }
+}
+
+/** Explicit worker envelope; the page removes it before enhancing Firebase results. */
+export function packAiEvidence<T extends object>(response: T): T & { __pyricAi?: Partial<AiEvidence> } {
+  return { ...response, __pyricAi: getAiEvidence(response) };
+}
+export function unpackAiEvidence<T extends object>(response: T & { __pyricAi?: Partial<AiEvidence> }): T {
+  const { __pyricAi, ...plain } = response;
+  return setAiEvidence(plain as T, __pyricAi ?? {});
+}

package/src/sandbox/internal/event-history.ts

@@ -0,0 +1,193 @@
+import { encodedBytes, type EventHistoryLimits } from './history-retention.js';
+export type { EventHistoryLimits } from './history-retention.js';
+import { RulesEvidenceRetention } from './rules-evidence-retention.js';
+import type { SandboxEvent, SandboxObservationGapEvent } from '../types/events.js';
+
+interface HistoryEntry {
+  event: SandboxEvent;
+  bytes: number;
+}
+
+/** One observation history owner; adapters may bound retention without truncating undo state. */
+export class EventHistory {
+  private entries: HistoryEntry[] = [];
+  private bytes = 0;
+  // Live state remains visible; its reservation may use at most half the history budget.
+  private liveCount = 0;
+  private liveBytes = 0;
+  private readonly activeRequests = new Map<string, HistoryEntry>();
+  private readonly completedRequests = new Set<string>();
+  private readonly activeListeners = new Map<string, HistoryEntry>();
+  private readonly retainedIds = new Set<string>();
+  private readonly rulesEvidence = new RulesEvidenceRetention<HistoryEntry>();
+  private sourceGapCount = 0;
+  private gap: SandboxObservationGapEvent | undefined;
+
+  constructor(private readonly limits?: EventHistoryLimits) {}
+
+  get length(): number {
+    return this.snapshot().length;
+  }
+
+  append(event: SandboxEvent): void {
+    const observation = event.kind === 'operation' ? event.observation : undefined;
+    const isBounded = this.limits !== undefined;
+    const bytes = isBounded ? encodedBytes(event) + 1 : 0;
+    if (observation?.status === 'pending') {
+      if (this.completedRequests.has(observation.id)) return;
+      const previous = this.activeRequests.get(observation.id);
+      if (previous) this.releaseLive(previous);
+      const entry = { event, bytes };
+      this.activeRequests.set(observation.id, entry);
+      this.reserveLive(entry);
+      this.prune();
+      return;
+    }
+    if (observation) {
+      const pending = this.activeRequests.get(observation.id);
+      if (pending) this.releaseLive(pending);
+      this.activeRequests.delete(observation.id);
+      this.completedRequests.add(observation.id);
+    }
+    this.trackListener(event, bytes);
+    if (this.retainedIds.has(event.id)) return;
+    this.retainedIds.add(event.id);
+    const activeListener = 'listenerId' in event ? this.activeListeners.get(event.listenerId) : undefined;
+    const retainsListener = activeListener?.event.id === event.id;
+    if (retainsListener) this.releaseLive(activeListener);
+    const isPriorEviction = isBounded && event.kind === 'observation_gap' && event.reason === 'history-limit';
+    const mustOmit = isPriorEviction || !Number.isFinite(bytes);
+    if (mustOmit) {
+      this.forgetId(event);
+      if (isPriorEviction) {
+        const omittedCount = Math.max(0, event.omittedCount - this.sourceGapCount);
+        this.sourceGapCount = Math.max(this.sourceGapCount, event.omittedCount);
+        if (omittedCount) this.omit({ ...event, omittedCount });
+      } else this.omit(event);
+    } else {
+      const entry = { event, bytes };
+      this.entries.push(entry);
+      this.bytes += bytes;
+      const expired = this.rulesEvidence.record(entry);
+      const hasExpiredEvidence = expired !== undefined;
+      if (hasExpiredEvidence) this.expireRulesEvidence(expired);
+    }
+    this.prune();
+  }
+
+  snapshot(): SandboxEvent[] {
+    const events = [...this.entries.map(entry => entry.event), ...[...this.activeRequests.values()].map(entry => entry.event),
+      ...[...this.activeListeners.values()].map(entry => entry.event).filter(event => !this.retainedIds.has(event.id))];
+    const gap = this.gap;
+    const hasGap = gap !== undefined;
+    return hasGap ? [{ ...gap }, ...events] : events;
+  }
+
+  clear(): void {
+    this.entries = [];
+    this.activeRequests.clear();
+    this.activeListeners.clear();
+    this.completedRequests.clear();
+    this.retainedIds.clear();
+    this.rulesEvidence.clear();
+    this.bytes = 0;
+    this.liveCount = 0;
+    this.liveBytes = 0;
+    this.gap = undefined;
+    this.sourceGapCount = 0;
+  }
+
+  private forgetId(event: SandboxEvent): void {
+    this.retainedIds.delete(event.id);
+    const listener = 'listenerId' in event ? this.activeListeners.get(event.listenerId) : undefined;
+    const isActiveListener = listener?.event.id === event.id;
+    if (isActiveListener) this.reserveLive(listener);
+    const observation = event.kind === 'operation' ? event.observation : undefined;
+    if (observation) this.completedRequests.delete(observation.id);
+  }
+
+  private trackListener(event: SandboxEvent, bytes: number): void {
+    if (!('listenerId' in event)) return;
+    const attaches = event.kind === 'listener_attach' || (event.kind === 'listener' && event.phase === 'attach');
+    const closes = event.kind === 'listener_detach' || event.kind === 'listener_errored'
+      || (event.kind === 'listener' && (event.phase === 'detach' || event.phase === 'errored'));
+    const changesRegistration = attaches || closes;
+    if (!changesRegistration) return;
+    const previous = this.activeListeners.get(event.listenerId);
+    const previousIsLiveOnly = previous !== undefined && !this.retainedIds.has(previous.event.id);
+    if (previousIsLiveOnly) this.releaseLive(previous);
+    if (attaches) {
+      const entry = { event, bytes };
+      this.activeListeners.set(event.listenerId, entry);
+      const isLiveOnly = !this.retainedIds.has(event.id);
+      if (isLiveOnly) this.reserveLive(entry);
+    } else this.activeListeners.delete(event.listenerId);
+    if (previousIsLiveOnly) this.omit(previous.event);
+  }
+
+  private expireRulesEvidence(entry: HistoryEntry): void {
+    const event = entry.event;
+    const isOtherEvent = event.kind !== 'request';
+    if (isOtherEvent) return;
+    const { rulesEvidence, ...metadata } = event;
+    entry.event = { ...metadata, rulesEvidenceExpired: true };
+    const isBounded = this.limits !== undefined;
+    const bytes = isBounded ? encodedBytes(entry.event) + 1 : 0;
+    this.bytes += bytes - entry.bytes;
+    entry.bytes = bytes;
+  }
+
+  private reserveLive(entry: HistoryEntry): void {
+    this.liveCount++;
+    this.liveBytes += entry.bytes;
+  }
+
+  private releaseLive(entry: HistoryEntry): void {
+    this.liveCount--;
+    this.liveBytes -= entry.bytes;
+  }
+
+  private prune(): void {
+    let exceedsLimits = this.exceedsLimits();
+    while (exceedsLimits) {
+      const oldest = this.entries.shift();
+      const isEmpty = oldest === undefined;
+      if (isEmpty) break;
+      this.forgetId(oldest.event);
+      this.rulesEvidence.forget(oldest);
+      this.bytes -= oldest.bytes;
+      this.omit(oldest.event);
+      exceedsLimits = this.exceedsLimits();
+    }
+  }
+
+  private exceedsLimits(): boolean {
+    const limits = this.limits;
+    const isUnbounded = limits === undefined;
+    if (isUnbounded) return false;
+    const hasNoGap = this.gap === undefined;
+    const gapBytes = hasNoGap ? 0 : encodedBytes(this.gap) + 1;
+    const reservedEvents = Math.min(this.liveCount, Math.floor(limits.maxEvents / 2));
+    const reservedBytes = Math.min(this.liveBytes, Math.floor(limits.maxBytes / 2));
+    const eventCount = this.entries.length + reservedEvents;
+    const exceedsCount = eventCount > limits.maxEvents;
+    const exceedsBytes = this.bytes + reservedBytes + gapBytes + 2 > limits.maxBytes;
+    return exceedsCount || exceedsBytes;
+  }
+
+  private omit(event: SandboxEvent): void {
+    const listener = 'listenerId' in event ? this.activeListeners.get(event.listenerId) : undefined;
+    const remainsVisible = listener?.event.id === event.id;
+    if (remainsVisible) return;
+    const isGap = event.kind === 'observation_gap';
+    const count = isGap ? event.omittedCount : 1;
+    const first = isGap ? event.firstEventId : event.id;
+    const last = isGap ? event.lastEventId : event.id;
+    this.gap = {
+      kind: 'observation_gap', reason: 'history-limit', id: 'history-gap',
+      at: this.gap?.at ?? event.at,
+      firstEventId: this.gap?.firstEventId ?? first, lastEventId: last,
+      omittedCount: (this.gap?.omittedCount ?? 0) + count,
+    };
+  }
+}

package/src/sandbox/internal/history-integrity.ts

@@ -0,0 +1,12 @@
+import { SandboxError } from '../types/errors.js';
+
+/** A retained suffix cannot stand in for a complete replay or verification input. */
+export function assertCompleteHistory(events: readonly unknown[]): void {
+  const hasGap = events.some(event => {
+    const isRecord = event !== null && typeof event === 'object';
+    const isGap = isRecord && 'kind' in event && event.kind === 'observation_gap';
+    return isGap;
+  });
+  if (hasGap) throw new SandboxError('failed-precondition',
+    'Cannot replay or verify incomplete observation history. Capture a fresh session without observation gaps.');
+}

package/src/sandbox/internal/history-retention.ts

@@ -0,0 +1,16 @@
+export interface EventHistoryLimits {
+  maxEvents: number;
+  maxBytes: number;
+}
+
+const utf8 = new TextEncoder();
+
+export function encodedBytes(value: unknown): number {
+  try {
+    const json = JSON.stringify(value);
+    const hasBuffer = typeof Buffer === 'function';
+    return hasBuffer ? Buffer.byteLength(json) : utf8.encode(json).byteLength;
+  }
+  catch { return Infinity; }
+}
+

package/src/sandbox/internal/index.ts

@@ -15,6 +15,58 @@
  * scope summary".
  */
 export { getInternalEnv } from './sandbox-impl.js';
+export { decodeImportBundle, validatePersistenceEncoding } from '../persistence/import-bundle.js';
+export { validatePersistedService, persistedServiceHasData, UnsupportedPersistedServiceError } from '../persistence/validate-services.js';
+export { seedUserSchema, storedMetadataSchema } from './state-schemas.js';
+export { captureIndexQuery, analyzeIndexQuery, readIndexConfig, type IndexQuery, type IndexFinding } from '../../rules/indexes/query-analysis.js';
+export type { IndexesConfig, IndexesConfigEntry } from '../../rules/indexes/types.js';
+export {
+  analyzeServiceIndex, captureDatabaseIndexQuery, databaseIndexLocations, indexService, isDatabaseIndexQuery,
+  type DatabaseIndexQuery, type DatabaseIndexDefinition, type DatabaseIndexConfig,
+  type ServiceIndexQuery, type ServiceIndexConfig, type ServiceIndexDefinition, type ServiceIndexFinding,
+} from '../../rules/indexes/service-query.js';
+export { observationService, type SdkObservation } from './sdk-observation.js';
+export { runSdkWrite } from './sdk-write-activity.js';
+export { createSdkRates, createSdkRateMonitor, sdkRates } from './sdk-rates.js';
+export type { AiRequestObservation, SdkRateSnapshot, SdkServiceRate, SdkMethodRate, SdkRateBucket } from './sdk-rates.js';
+export { sdkMethodCoverage } from './sdk-coverage.js';
+export type { SdkMethodCoverage, SdkMethodCategory } from './sdk-coverage.js';
+export {
+  createSdkActivityJournal,
+  finishSdkRead,
+  sdkActivity,
+  type SdkActivityEvent,
+  type SdkActivityHandle,
+  type SdkActivityRecord,
+  type SdkActivitySource,
+} from './sdk-activity.js';
+// Listener attribution: the owner records pyric stamps onto its own listener
+// events. Every mirrored surface with listeners reaches these, so they live in
+// the cross-surface runtime rather than in one surface's backend.
+export {
+  configureListenerAttribution,
+  listenerAttributionEnabled,
+  listenerAttributionMode,
+  type ListenerAttributionMode,
+} from '../attribution/attribution-mode.js';
+export {
+  callerFrameFromStack,
+  captureCreationFrame,
+  listenerAttachOwners,
+  tagOwnerFor,
+  type ComponentOwnerInput,
+  type ListenerAttribution,
+  type ListenerOwnerHint,
+  type RecordedListenerOwners,
+} from '../attribution/listener-owners.js';
+export { recordEffectRegions } from '../attribution/effect-regions.js';
+export {
+  isSelectableElement,
+  ownerSelectorFor,
+  tagNameOf,
+  type SelectableElement,
+} from '../attribution/element-selector.js';
+export { getClock } from '../clock.js';
 export { stampProvenance } from './provenance.js';
 export { bindOperationContext } from '../sandbox-context.js';
 export {
@@ -95,3 +147,16 @@ export * from '../../firestore/sandbox/wire-encoder.js';
 // with explicit named re-exports once the admin-compat layer's
 // surface stops drifting.
 export { createSandboxRoot } from './root.js';
+
+export { assertCompleteHistory } from './history-integrity.js';
+export { EventHistory } from './event-history.js';
+export { firestoreReadUsage } from './usage-evidence.js';
+export type { UsageEvidence } from './usage-evidence.js';
+
+export { OBSERVATION_HISTORY_LIMITS } from './observation-history.js';
+export { observationPayload, observationText } from './observation-payload.js';
+
+export { aiCompletionUsage } from './usage-evidence.js';
+export { requestStatusLabel } from '../types/request-observation.js';
+
+export { createActiveListenerState } from '../active-listeners.js';

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

@@ -0,0 +1,5 @@
+/** Shared count and byte bounds; elapsed time must not make replay history incomplete. */
+export const OBSERVATION_HISTORY_LIMITS = {
+  maxEvents: 10_000,
+  maxBytes: 8 * 1024 * 1024,
+} as const;

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

@@ -0,0 +1,18 @@
+/** Diagnostic previews are bounded and omit credential fields at every depth. */
+const secretField = /password|credential|secret|token|authorization|cookie|api[-_]?key/i;
+export function observationText(text: string): string {
+  return text
+    .replace(/\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi, 'Bearer [redacted]')
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted token]')
+    .replace(/((?:password|api[-_]?key|access[-_]?token|refresh[-_]?token|secret)["']?\s*[:=]\s*["']?)[^\s"',;}]+/gi, '$1[redacted]');
+}
+export function observationPayload(value: unknown, limit = 16384): { text: string; truncated: boolean } | undefined {
+  try {
+    const text = JSON.stringify(value, (key, item) => {
+      if (secretField.test(key)) return '[redacted]';
+      return typeof item === 'string' ? observationText(item) : item;
+    }, 2);
+    if (text === undefined) return;
+    return { text: text.slice(0, limit), truncated: text.length > limit };
+  } catch { return; }
+}

package/src/sandbox/internal/provenance.ts

@@ -1,4 +1,5 @@
 /** Canonical provenance stamping and nested-window composition. */
+import { sdkActivity } from './sdk-activity.js';
 
 import type {
   EventProvenance,
@@ -18,6 +19,10 @@ export function stampProvenance<E extends SandboxEvent>(
   overrides?: EventProvenance,
 ): E {
   const out = { ...event } as E & EventProvenance;
+  if (event.kind === 'listener_attach' || (event.kind === 'listener' && event.phase === 'attach')) {
+    const listenerId = sdkActivity.registrationId();
+    if (listenerId) out.activity = { ...out.activity, listenerId };
+  }
   out.service = event.service ?? overrides?.service ?? 'firestore';
 
   // Pre-context admin events used `detail.admin` as their only execution-lens

package/src/sandbox/internal/root.ts

@@ -1,7 +1,8 @@
+import type { EventHistoryLimits } from './event-history.js';
 import { SandboxImpl } from './sandbox-impl.js';
 import type { LocalSandbox } from '../types/service.js';
 
 /** Create one isolated in-memory sandbox for any browser host. */
-export function createSandboxRoot(): LocalSandbox {
-  return SandboxImpl.createRoot();
+export function createSandboxRoot(historyLimits?: EventHistoryLimits): LocalSandbox {
+  return SandboxImpl.createRoot(historyLimits);
 }

package/src/sandbox/internal/rules-evidence-retention.ts

@@ -0,0 +1,28 @@
+import type { SandboxEvent } from '../types/events.js';
+
+/** Track retained entries by identity so history eviction cannot shift the owner. */
+export class RulesEvidenceRetention<Entry extends { event: SandboxEvent }> {
+  private readonly entries = new Set<Entry>();
+
+  record(entry: Entry): Entry | undefined {
+    const event = entry.event;
+    const hasEvidence = event.kind === 'request' && event.rulesEvidence !== undefined;
+    const hasNoEvidence = !hasEvidence;
+    if (hasNoEvidence) return;
+    this.entries.add(entry);
+    const withinLimit = this.entries.size <= 64;
+    if (withinLimit) return;
+    const oldest = this.entries.values().next().value;
+    const hasOldest = oldest !== undefined;
+    if (hasOldest) this.entries.delete(oldest);
+    return oldest;
+  }
+
+  forget(entry: Entry): void {
+    this.entries.delete(entry);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}