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

package/src/sandbox/persistence/changed-buckets.ts

@@ -0,0 +1,61 @@
+import { DOC_VALUE_ENCODING } from '../../firestore/internal/value-codec.js';
+import { encodeStateDocument } from '../internal/state-values.js';
+import { checksumDocs, pathToBucketId, type BucketRecord } from './chunk-format.js';
+
+type Document = Record<string, unknown>;
+
+/** Keeps path membership, not a second encoded copy of the document store. */
+export class ChangedBuckets {
+  private readonly paths = new Map<string, Set<string>>();
+  private dirty: Set<string>;
+  private needsSnapshot = true;
+
+  constructor(
+    private readonly snapshot: () => Record<string, Document>,
+    private readonly read: (path: string) => Document | null,
+    persistedIds: Iterable<string>,
+  ) {
+    this.dirty = new Set(persistedIds);
+  }
+
+  mark(path: string | null): void {
+    const replacesState = path === null;
+    if (replacesState) { this.needsSnapshot = true; return; }
+    const id = pathToBucketId(path);
+    const members = this.paths.get(id) ?? new Set<string>();
+    members.add(path);
+    this.paths.set(id, members);
+    this.dirty.add(id);
+  }
+
+  prepare() {
+    if (this.needsSnapshot) {
+      const documents = this.snapshot();
+      for (const id of this.paths.keys()) this.dirty.add(id);
+      this.paths.clear();
+      for (const path of Object.keys(documents)) this.mark(path);
+      this.needsSnapshot = false;
+    }
+    const captured = this.dirty;
+    this.dirty = new Set();
+    const retry = (): void => { for (const id of captured) this.dirty.add(id); };
+    const records = new Map<string, BucketRecord>();
+    const removed: string[] = [];
+    try {
+      for (const id of captured) {
+        const docs: Record<string, Document> = {};
+        const members = this.paths.get(id) ?? new Set<string>();
+        for (const path of members) {
+          const document = this.read(path);
+          const deleted = document === null;
+          if (deleted) members.delete(path);
+          else docs[path] = encodeStateDocument(document);
+        }
+        const empty = members.size === 0;
+        if (empty) { this.paths.delete(id); removed.push(id); }
+        else records.set(id, { docs, encoding: DOC_VALUE_ENCODING, checksum: checksumDocs(docs) });
+      }
+      return { records, removed, retry };
+    } catch (error) { retry(); throw error; }
+  }
+}

package/src/sandbox/persistence/chunk-format.ts

@@ -17,7 +17,9 @@
  * (Float32Array vector encoding is a later, backward-compatible refinement on the
  * per-bucket record shape.)
  */
-import { rehydrateDocValue } from '../../firestore/internal/value-codec.js';
+import { DOC_VALUE_ENCODING, rehydrateEncodedDocValue, requireDocumentData,
+  type DocValueEncoding } from '../../firestore/internal/value-codec.js';
+import { encodeStateDocument } from '../internal/state-values.js';
 import { deserializeSnapshot } from './serialize.js';
 
 export const CHUNK_FORMAT_VERSION = 3 as const;
@@ -42,6 +44,8 @@ export function pathToBucketId(path: string): string {
 /** A firestore bucket record: marker-encoded docs keyed by full path. */
 export interface BucketRecord {
   docs: Record<string, Record<string, unknown>>;
+  /** Per-bucket declaration permits legacy and newly flushed buckets to coexist. */
+  encoding?: DocValueEncoding;
   /** FNV checksum of `docs`, set on write and verified on read so a corrupt
    *  bucket is quarantined (skipped) rather than restored as garbage. */
   checksum?: number;
@@ -54,20 +58,17 @@ export interface MetaRecord {
   services: Record<string, unknown>;
 }
 
-/** Marker-encode a doc to a structured-clone-safe plain tree (reuses the wrapper
- *  `toJSON` markers via a per-doc round-trip; small per-doc strings, never one
- *  keyspace blob). */
-function encodeDoc(data: Record<string, unknown>): Record<string, unknown> {
-  return JSON.parse(JSON.stringify(data)) as Record<string, unknown>;
-}
-
 /** FNV-1a checksum of a bucket's docs, for corruption detection on read. */
-function checksumDocs(docs: Record<string, Record<string, unknown>>): number {
+export function checksumDocs(docs: Record<string, unknown>): number {
   const s = JSON.stringify(docs);
   let h = 0x811c9dc5;
-  for (let i = 0; i < s.length; i++) {
+  let i = 0;
+  let hasCharacter = i < s.length;
+  while (hasCharacter) {
     h ^= s.charCodeAt(i);
     h = Math.imul(h, 16777619) >>> 0;
+    i += 1;
+    hasCharacter = i < s.length;
   }
   return h;
 }
@@ -86,16 +87,15 @@ export function serializeToBuckets(
   records.set(META_RECORD_ID, { version: CHUNK_FORMAT_VERSION, savedAt, services });
   for (const [path, data] of Object.entries(firestore)) {
     const id = pathToBucketId(path);
-    let bucket = records.get(id) as BucketRecord | undefined;
-    if (!bucket) {
-      bucket = { docs: {} };
-      records.set(id, bucket);
-    }
-    bucket.docs[path] = encodeDoc(data);
+    const existing = records.get(id) as BucketRecord | undefined;
+    const bucket = existing ?? { docs: {}, encoding: DOC_VALUE_ENCODING };
+    records.set(id, bucket);
+    bucket.docs[path] = encodeStateDocument(data);
   }
   // Checksum each bucket so a corrupt record is detected + quarantined on read.
   for (const [id, rec] of records) {
-    if (id === META_RECORD_ID) continue;
+    const isMetadata = id === META_RECORD_ID;
+    if (isMetadata) continue;
     (rec as BucketRecord).checksum = checksumDocs((rec as BucketRecord).docs);
   }
   return records;
@@ -164,31 +164,43 @@ export function migrateV2ToRecords(
  *  [recordId, record] pairs). Rehydrates wrapper types from their markers. */
 export function deserializeFromBuckets(
   records: Iterable<[string, unknown]>,
+  options: { skipInvalidDocuments?: boolean } = {},
 ): { firestore: Record<string, Record<string, unknown>>; services: Record<string, unknown> } {
   const firestore: Record<string, Record<string, unknown>> = {};
   let services: Record<string, unknown> = {};
   for (const [id, rec] of records) {
-    if (id === META_RECORD_ID) {
+    const isMetadata = id === META_RECORD_ID;
+    if (isMetadata) {
       const meta = rec as Partial<MetaRecord> | null;
-      if (meta && typeof meta.services === 'object' && meta.services !== null) {
-        services = meta.services;
+      const savedServices = meta?.services;
+      const hasServices = typeof savedServices === 'object' && savedServices !== null;
+      if (hasServices) {
+        services = savedServices;
       }
       continue;
     }
     const bucket = rec as Partial<BucketRecord> | null;
-    if (!bucket || typeof bucket.docs !== 'object' || bucket.docs === null) continue;
+    const documents = bucket?.docs;
+    const isMalformedBucket = typeof documents !== 'object' || documents === null;
+    if (isMalformedBucket) continue;
     // C5: verify the bucket's checksum (when present). A mismatch means the
     // record was corrupted in storage; quarantine it (skip + warn) rather than
     // restore garbage. Records without a checksum (pre-checksum v3) are accepted.
-    if (
-      typeof bucket.checksum === 'number' &&
-      checksumDocs(bucket.docs as Record<string, Record<string, unknown>>) !== bucket.checksum
-    ) {
+    const hasCorruptChecksum =
+      typeof bucket?.checksum === 'number' &&
+      checksumDocs(documents) !== bucket.checksum;
+    if (hasCorruptChecksum) {
       console.warn(`[sandbox/persistence] checksum mismatch for bucket '${id}'; skipping corrupt bucket`);
       continue;
     }
-    for (const [path, data] of Object.entries(bucket.docs)) {
-      firestore[path] = rehydrateDocValue(data) as Record<string, unknown>;
+    for (const [path, data] of Object.entries(documents)) {
+      try {
+        firestore[path] = requireDocumentData(rehydrateEncodedDocValue(data, bucket?.encoding));
+      } catch (error) {
+        const mustReject = options.skipInvalidDocuments !== true;
+        if (mustReject) throw error;
+        console.warn(`[sandbox/persistence] skipping unreadable Firestore document '${path}' in bucket '${id}':`, error);
+      }
     }
   }
   return { firestore, services };

package/src/sandbox/persistence/controller.ts

@@ -9,10 +9,13 @@
  * every side effect and leaves the sandbox unchanged.
  */
 
+import { ChangedBuckets } from './changed-buckets.js';
+import { CHUNK_FORMAT_VERSION, META_RECORD_ID } from './chunk-format.js';
 import type { SandboxEvent } from '../types/events.js';
 import type { PersistableService } from '../types/persistence.js';
 import type { Sandbox } from '../types/service.js';
 import { SandboxImpl } from '../internal/sandbox-impl.js';
+import { getClock } from '../clock.js';
 import { createIndexedDBBackend, createMemoryBackend } from './backends.js';
 import {
   serializeToBuckets,
@@ -127,6 +130,9 @@ export async function attachPersistence(
   // though they weren't in the registry when `restore()` ran.
   const restoredServices = await restore(sandbox, backend, options.key, lastHashes);
 
+  const pendingServices = new Map(Object.entries(restoredServices ?? {}));
+  const serviceSnapshots = new Map<string, unknown>();
+
   let pendingFlush: ReturnType<typeof setTimeout> | null = null;
   let disposed = false;
 
@@ -135,33 +141,55 @@ export async function attachPersistence(
   // but makes debugging easier).
   const serviceUnsubs = new Map<string, () => void>();
 
-  // The actual flush. Reads CURRENT state each time it runs.
+  const localSandbox = sandbox instanceof SandboxImpl ? sandbox : null;
+  const changedBuckets = localSandbox ? new ChangedBuckets(
+    () => localSandbox.getEnv().snapshot(),
+    path => localSandbox.getEnv().getDocument(path),
+    [...lastHashes.keys()].filter(id => id !== META_RECORD_ID),
+  ) : null;
+
+  // Prepare immutable records before awaiting the backend; later mutations stay dirty.
   const realFlush = async (): Promise<void> => {
     if (disposed) return;
-    // `sandbox.snapshot()` now includes `{ firestore, services }` — the
-    // services map is built live from the registry, so services registered
-    // after enablePersistence (late registration) are naturally included.
-    const snap = sandbox.snapshot();
-    const records = serializeToBuckets(snap.firestore, snap.services, Date.now());
-    // Incremental flush: write ONLY the buckets whose content changed since the
-    // last flush, and delete buckets that disappeared. Comparison is by content
-    // hash, so it is safe by construction: a changed bucket cannot hash equal to
-    // its prior content, so no write is ever skipped (no write-site dirty-set to
-    // keep in sync). Put changed buckets BEFORE deleting removed ones, and adopt
-    // the new hashes only AFTER both land, so a crash mid-flush never loses live
-    // data and the next flush simply retries against the unchanged hash state.
-    const changed = new Map<string, unknown>();
-    const nextHashes = new Map<string, number>();
-    for (const [id, rec] of records) {
-      const h = hashRecord(rec);
-      nextHashes.set(id, h);
-      if (lastHashes.get(id) !== h) changed.set(id, rec);
-    }
-    const removed = [...lastHashes.keys()].filter((id) => !records.has(id));
-    if (changed.size > 0) await backend.putRecords(options.key, changed);
-    if (removed.length > 0) await backend.deleteRecords(options.key, removed);
-    lastHashes.clear();
-    for (const [id, h] of nextHashes) lastHashes.set(id, h);
+    const prepared = changedBuckets?.prepare();
+    try {
+      const services = { ...Object.fromEntries(pendingServices) };
+      let records: Map<string, unknown>;
+      const usesChangedBuckets = prepared !== undefined && localSandbox !== null;
+      if (usesChangedBuckets) {
+        for (const [name, service] of localSandbox.getServiceRegistry()) {
+          const needsSnapshot = !service.subscribe || !serviceSnapshots.has(name);
+          if (needsSnapshot) serviceSnapshots.set(name, structuredClone(service.snapshot()));
+          services[name] = serviceSnapshots.get(name);
+        }
+        records = new Map(prepared.records);
+        records.set(META_RECORD_ID, { version: CHUNK_FORMAT_VERSION, savedAt: getClock(sandbox).now(), services });
+      } else {
+        const snap = sandbox.snapshot();
+        records = serializeToBuckets(snap.firestore, { ...services, ...snap.services }, getClock(sandbox).now());
+      }
+      const changed = new Map<string, unknown>();
+      const nextHashes = new Map<string, number>();
+      for (const [id, record] of records) {
+        const hash = hashRecord(record);
+        nextHashes.set(id, hash);
+        const changedHash = lastHashes.get(id) !== hash;
+        if (changedHash) changed.set(id, record);
+      }
+      const removed = prepared?.removed ?? [...lastHashes.keys()].filter(id => !records.has(id));
+      const applyChanges = backend.applyChanges;
+      const commitsAtomically = applyChanges !== undefined;
+      if (commitsAtomically) {
+        await applyChanges(options.key, changed, removed);
+      } else {
+        const hasChanges = changed.size > 0;
+        if (hasChanges) await backend.putRecords(options.key, changed);
+        const hasRemovals = removed.length > 0;
+        if (hasRemovals) await backend.deleteRecords(options.key, removed);
+      }
+      for (const id of removed) lastHashes.delete(id);
+      for (const [id, hash] of nextHashes) lastHashes.set(id, hash);
+    } catch (error) { prepared?.retry(); throw error; }
   };
 
   // Serialize flushes on a single chain so two never overlap. Without this, a
@@ -180,11 +208,13 @@ export async function attachPersistence(
 
   const scheduleFlush = (): void => {
     if (disposed) return;
-    if (pendingFlush) return;
+    const alreadyScheduled = pendingFlush !== null;
+    if (alreadyScheduled) return;
     pendingFlush = setTimeout(() => {
       pendingFlush = null;
       void flushNow().catch((e) => {
-        if (isQuotaExceeded(e)) {
+        const quotaExceeded = isQuotaExceeded(e);
+        if (quotaExceeded) {
           // Storage is full: retrying will not help until space is freed, so
           // warn loudly instead of busy-looping. The unpersisted changes stay in
           // memory; the next successful flush (after space frees) re-detects them.
@@ -194,6 +224,11 @@ export async function attachPersistence(
           );
           return;
         }
+        const requiresRepair = backend.retryFailedFlush === false;
+        if (requiresRepair) {
+          console.warn('[sandbox/persistence] auto-flush failed; repair and restart required.');
+          return;
+        }
         console.warn('[sandbox/persistence] auto-flush failed, will retry:', e);
         // A failed flush did not adopt its hashes, so the change is still
         // unpersisted. Re-arm rather than waiting for the next write event, so
@@ -211,6 +246,7 @@ export async function attachPersistence(
   const attachServiceSubscription = (name: string, hooks: PersistableService): void => {
     if (!hooks.subscribe || serviceUnsubs.has(name)) return;
     const unsub = hooks.subscribe(() => {
+      serviceSnapshots.delete(name);
       scheduleFlush();
     });
     serviceUnsubs.set(name, unsub);
@@ -306,8 +342,10 @@ export async function attachPersistence(
     if (stored) tryRestoreSession(name, stored, hooks);
   };
 
-  if (sandbox instanceof SandboxImpl) {
+  const ownsServiceRegistry = sandbox instanceof SandboxImpl;
+  if (ownsServiceRegistry) {
     for (const [name, hooks] of sandbox.getServiceRegistry()) {
+      pendingServices.delete(name);
       attachServiceSubscription(name, hooks);
       restoreSessionForService(name, hooks);
       // Restore before subscribing: restore(mode, uid) can emit session
@@ -316,21 +354,26 @@ export async function attachPersistence(
       attachSessionSubscription(name, hooks);
     }
     sandbox.setServiceRegistrationHook((name, hooks) => {
-      if (restoredServices !== null && name in restoredServices) {
+      serviceSnapshots.delete(name);
+      const hasPendingState = pendingServices.has(name);
+      if (hasPendingState) {
         try {
-          hooks.restore(restoredServices[name]);
+          hooks.restore(pendingServices.get(name));
+          pendingServices.delete(name);
         } catch (error) {
           console.warn(`[sandbox/persistence] late-restore for service '${name}' failed:`, error);
         }
       }
       const stored = loadStoredSession(name);
-      if (stored) pendingSessions.set(name, stored);
+      const hasStoredSession = stored !== null;
+      if (hasStoredSession) pendingSessions.set(name, stored);
       restoreSessionForService(name, hooks);
       attachServiceSubscription(name, hooks);
       attachSessionSubscription(name, hooks);
       scheduleFlush();
     });
     sandbox.setServiceUnregistrationHook((name) => {
+      serviceSnapshots.delete(name);
       serviceUnsubs.get(name)?.();
       serviceUnsubs.delete(name);
       sessionUnsubs.get(name)?.();
@@ -343,6 +386,12 @@ export async function attachPersistence(
     });
   }
 
+  const unsubscribeDocuments = localSandbox?.onDocumentChange(path => {
+    changedBuckets?.mark(path);
+    const replacesState = path === null;
+    if (replacesState) serviceSnapshots.clear();
+    scheduleFlush();
+  });
   const unsubscribe = sandbox.onEvent((event) => {
     if (isPersistableEvent(event)) scheduleFlush();
   });
@@ -359,7 +408,8 @@ export async function attachPersistence(
     });
   };
 
-  if (typeof window !== 'undefined') {
+  const inBrowser = typeof window !== 'undefined';
+  if (inBrowser) {
     window.addEventListener('beforeunload', beforeUnload);
   }
 
@@ -376,6 +426,7 @@ export async function attachPersistence(
       // must treat every bucket as changed and re-persist the full in-memory
       // state (otherwise untouched buckets stay suppressed and are lost).
       lastHashes.clear();
+      changedBuckets?.mark(null);
     },
     dispose() {
       if (disposed) return;
@@ -385,6 +436,7 @@ export async function attachPersistence(
         pendingFlush = null;
       }
       unsubscribe();
+      unsubscribeDocuments?.();
       // Detach service change-notification subscriptions.
       for (const unsub of serviceUnsubs.values()) unsub();
       serviceUnsubs.clear();
@@ -486,7 +538,7 @@ async function restore(
   // Seed the flush hash state from the effective v3 records, so the first flush
   // does not redundantly re-write the just-restored (or just-migrated) buckets.
   for (const [id, rec] of v3Records) lastHashes.set(id, hashRecord(rec));
-  const parsed = deserializeFromBuckets(v3Records);
+  const parsed = deserializeFromBuckets(v3Records, { skipInvalidDocuments: true });
 
   // 1. Restore Firestore documents first. These are the structural data
   //    that services (auth) may depend on being present.

package/src/sandbox/persistence/import-bundle.ts

@@ -0,0 +1,64 @@
+import { DOC_VALUE_ENCODING } from '../../firestore/internal/value-codec.js';
+import { FirebaseError } from '../internal/firebase-error.js';
+import { isPlainObject } from '../../firestore/plain-object.js';
+import { CHUNK_FORMAT_VERSION, checksumDocs, deserializeFromBuckets, META_RECORD_ID, parseBundle } from './chunk-format.js';
+
+/** Decode a replacement before its caller changes the current sandbox. */
+export function decodeImportBundle(bundle: string) {
+  const records = parseBundle(bundle);
+  const isMissingMetadata = !records.has(META_RECORD_ID);
+  if (isMissingMetadata) {
+    throw new FirebaseError('invalid-argument', 'State import requires sandbox metadata.');
+  }
+  const metadata = records.get(META_RECORD_ID);
+  const isMalformedMetadata = !isPlainObject(metadata);
+  if (isMalformedMetadata) {
+    throw new FirebaseError('invalid-argument', 'State import metadata must be an object.');
+  }
+  const hasUnsupportedVersion = metadata.version !== CHUNK_FORMAT_VERSION;
+  if (hasUnsupportedVersion) {
+    throw new FirebaseError('invalid-argument', `State import requires metadata version ${CHUNK_FORMAT_VERSION}.`);
+  }
+  const isMalformedServices = !isPlainObject(metadata.services);
+  if (isMalformedServices) {
+    throw new FirebaseError('invalid-argument', 'State import requires a service state map.');
+  }
+  const paths = new Set<string>();
+  for (const [id, record] of records) {
+    const isMetadata = id === META_RECORD_ID;
+    if (isMetadata) continue;
+    const isMalformedBucket = !isPlainObject(record);
+    if (isMalformedBucket) {
+      throw new FirebaseError('invalid-argument', `State import bucket '${id}' must be an object.`);
+    }
+    validatePersistenceEncoding(record.encoding);
+    const documents = record.docs;
+    const isMalformedDocuments = !isPlainObject(documents);
+    if (isMalformedDocuments) {
+      throw new FirebaseError('invalid-argument', `State import bucket '${id}' requires a document map.`);
+    }
+    for (const [path, document] of Object.entries(documents)) {
+      const duplicatePath = paths.has(path);
+      if (duplicatePath) throw new FirebaseError('invalid-argument', `State import contains duplicate document '${path}'.`);
+      paths.add(path);
+      const isMalformedDocument = !isPlainObject(document);
+      if (isMalformedDocument) {
+        throw new FirebaseError('invalid-argument', `State import document '${path}' must be an object.`);
+      }
+    }
+    const hasChecksum = record.checksum !== undefined;
+    if (hasChecksum) {
+      const hasCorruptDocuments = record.checksum !== checksumDocs(documents);
+      if (hasCorruptDocuments) {
+        throw new FirebaseError('invalid-argument', `State import bucket '${id}' has an invalid checksum.`);
+      }
+    }
+  }
+  return deserializeFromBuckets(records);
+}
+
+/** Unknown codecs cannot be treated as corruption: an older host cannot decode them. */
+export function validatePersistenceEncoding(encoding: unknown): void {
+  const unsupported = encoding !== undefined && encoding !== DOC_VALUE_ENCODING;
+  if (unsupported) throw new FirebaseError('invalid-argument', 'Unsupported Firestore value encoding.');
+}

package/src/sandbox/persistence/serialize.ts

@@ -24,7 +24,7 @@
 // engine. `serialize.ts` re-uses that same codec so there is exactly one
 // rehydrate implementation — the IDB persistence format and the MessagePort
 // wire format can't drift.
-import { rehydrateDocValue } from '../../firestore/internal/value-codec.js';
+import { assertEncodedDocValueDepth, rehydrateDocValue } from '../../firestore/internal/value-codec.js';
 
 // Re-exported so existing consumers (`sandbox/persistence/index.ts` →
 // `pyric/sandbox`) keep their import path; the implementation now lives in the
@@ -61,10 +61,11 @@ export class PersistenceSchemaError extends Error {
 export function serializeSnapshot(
   firestore: Record<string, Record<string, unknown>>,
   services: Record<string, unknown> = {},
+  savedAt: number = Date.now(),
 ): string {
   const payload: SerializedBlob = {
     version: SCHEMA_VERSION,
-    savedAt: Date.now(),
+    savedAt,
     firestore,
     services,
   };
@@ -100,32 +101,37 @@ export function deserializeSnapshot(raw: string): DeserializedSnapshot {
   let parsed: SerializedBlob;
   try {
     parsed = JSON.parse(raw) as SerializedBlob;
-  } catch (e) {
+  } catch (error) {
+    const isError = error instanceof Error;
     throw new PersistenceSchemaError(
-      `Persisted blob is not valid JSON: ${(e as Error).message}`,
+      `Persisted blob is not valid JSON: ${isError ? error.message : String(error)}`,
     );
   }
-  if (typeof parsed !== 'object' || parsed === null) {
+  const isInvalidBlob = typeof parsed !== 'object' || parsed === null;
+  if (isInvalidBlob) {
     throw new PersistenceSchemaError('Persisted blob is not an object');
   }
   // Accept v1 (no services) and v2 (with services). Any other version
   // is unrecognized — quarantine it so we don't silently corrupt state.
-  if (parsed.version !== 1 && parsed.version !== 2) {
+  const hasUnsupportedVersion = parsed.version !== 1 && parsed.version !== 2;
+  if (hasUnsupportedVersion) {
     throw new PersistenceSchemaError(
       `Persisted blob has version ${String(parsed.version)}, expected 1 or 2`,
     );
   }
-  if (typeof parsed.firestore !== 'object' || parsed.firestore === null) {
+  const hasNoFirestore = typeof parsed.firestore !== 'object' || parsed.firestore === null;
+  if (hasNoFirestore) {
     throw new PersistenceSchemaError('Persisted blob has no firestore field');
   }
   const firestore: Record<string, Record<string, unknown>> = {};
   for (const [path, data] of Object.entries(parsed.firestore)) {
+    assertEncodedDocValueDepth(data);
     firestore[path] = rehydrateDocValue(data) as Record<string, unknown>;
   }
   // v1 blobs lack `services` — default to {} so the restore path
   // proceeds without error. No auth users in the blob = no auth restore.
-  const services = (parsed.services !== undefined && typeof parsed.services === 'object' && parsed.services !== null)
-    ? (parsed.services as Record<string, unknown>)
-    : {};
+  const serviceState = parsed.services;
+  const hasServices = serviceState !== undefined && typeof serviceState === 'object' && serviceState !== null;
+  const services = hasServices ? serviceState : {};
   return { firestore, services };
 }

package/src/sandbox/persistence/types.ts

@@ -98,6 +98,10 @@ export interface SandboxPersistenceOptions {
  * them. (v2 and earlier used a single string blob; v3 is record-shaped.)
  */
 export interface PersistenceBackend {
+  /** False when a failed durable write requires operator repair and restart. */
+  retryFailedFlush?: boolean;
+  /** Commit changed and removed records atomically when the backend supports it. */
+  applyChanges?(key: string, changed: ReadonlyMap<string, unknown>, removed: readonly string[]): Promise<void>;
   /** Read one record by id under `key`. Resolves `null` when absent. */
   getRecord(key: string, recordId: string): Promise<unknown | null>;
   /** List all record ids under `key`, any order. */

package/src/sandbox/persistence/validate-services.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { seedUserSchema } from '../internal/state-schemas.js';
+import { isMessagingSnapshot } from '../../messaging/broker/persistence.js';
+
+const authState = z.object({ users: z.array(seedUserSchema), providers: z.record(z.boolean()) });
+const databaseState = z.object({
+  '.pyricRtdbPersistence': z.literal(1),
+  data: z.unknown().refine(value => value !== undefined, 'Required'),
+  priorities: z.record(z.union([z.string(), z.number().finite()])),
+  rules: z.object({ rules: z.record(z.unknown()) }).optional(),
+  instances: z.record(z.unknown()).optional(),
+});
+
+export class UnsupportedPersistedServiceError extends Error {}
+
+/** Hosted strict restore and explicit salvage use the same service validators. */
+export function validatePersistedService(name: string, value: unknown): void {
+  const isAuth = name === 'auth';
+  if (isAuth) {
+    authState.parse(value);
+    return;
+  }
+  const isDatabase = name === 'rtdb';
+  if (isDatabase) {
+    const parsed = databaseState.parse(value);
+    for (const instance of Object.values(parsed.instances ?? {})) databaseState.parse(instance);
+    return;
+  }
+  const isMessaging = name === 'messaging';
+  if (isMessaging) {
+    const valid = isMessagingSnapshot(value);
+    const invalidSnapshot = !valid;
+    if (invalidSnapshot) throw new Error('Invalid persisted Messaging state.');
+    return;
+  }
+  const noDurableState = name === 'storage' || name.startsWith('auth-session:');
+  if (noDurableState) {
+    const invalid = value !== null;
+    if (invalid) throw new Error(`Unexpected persisted data for '${name}'.`);
+    return;
+  }
+  throw new UnsupportedPersistedServiceError(`Unsupported persisted service '${name}'.`);
+}
+
+/** Empty service envelopes are not evidence that salvage recovered user state. */
+export function persistedServiceHasData(name: string, value: unknown): boolean {
+  const isAuth = name === 'auth';
+  if (isAuth) {
+    const auth = authState.parse(value);
+    return auth.users.length > 0 || Object.keys(auth.providers).length > 0;
+  }
+  const isDatabase = name === 'rtdb';
+  if (isDatabase) {
+    const database = databaseState.parse(value);
+    const hasData = containsDatabaseData(database.data);
+    const hasInstanceData = Object.values(database.instances ?? {}).some(instance => persistedServiceHasData('rtdb', instance));
+    return hasData || hasInstanceData;
+  }
+  const isMessaging = name === 'messaging' && isMessagingSnapshot(value);
+  if (isMessaging) return value.tokens.length > 0 || value.topics.length > 0;
+  return false;
+}
+
+function containsDatabaseData(value: unknown): boolean {
+  const isNull = value === null;
+  if (isNull) return false;
+  const isObject = typeof value === 'object';
+  if (isObject) return Object.values(value).some(containsDatabaseData);
+  return true;
+}

package/src/sandbox/remote.ts

@@ -27,6 +27,7 @@
  */
 
 import type { Sandbox } from './types/service.js';
+import type { RemoteByteRoute } from '../storage/remote-bytes.js';
 
 /**
  * Brand stamped (value `true`) on every remote sandbox handle.
@@ -66,6 +67,12 @@ export interface RemoteSandboxChannel {
     onSnap: (value: unknown) => void,
     onError?: (err: Error & { code: string }) => void,
   ): () => void;
+
+  /**
+   * The host's HTTP byte route for Storage bytes, once the channel is
+   * attached, or undefined when the host has none and takes bytes as frames.
+   */
+  byteRoute?(): Promise<RemoteByteRoute | undefined>;
 }
 
 /**