rastack 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.21](https://github.com/theserverkid/reactapistack/compare/v0.0.20...v0.0.21) (2026-07-08)
+
 ### [0.0.20](https://github.com/theserverkid/reactapistack/compare/v0.0.19...v0.0.20) (2026-07-07)
 
 ### 0.0.19 (2026-07-07)

package/cache/cache.ts

@@ -0,0 +1,258 @@
+/**
+ * The Iceberg file cache: query the database's own files locally instead of
+ * loading them into a second database.
+ *
+ * Iceberg gives the cache its correctness model for free:
+ *
+ * - `metadata/version-hint.text` is the only mutable object per table — a tiny
+ *   pointer to the current snapshot. It is revalidated against the source on
+ *   every seed (network-first, cache fallback when offline).
+ * - `metadata/v{N}.metadata.json` and `data/*.parquet` are immutable — once
+ *   written they never change — so a cached copy is correct forever
+ *   (cache-first; the network is only touched for files never seen before).
+ *
+ * Seeding hands the cached bytes to the WASM engine (`RadApi.seedFile`), which
+ * reads the *actual* Parquet/metadata files — the cache is a transparent layer
+ * between object storage and the engine, not a new store format.
+ *
+ * Security model:
+ * - Every entry is namespaced by identity (the Cognito `sub`), so two accounts
+ *   on one device can never read each other's cached rows.
+ * - When the source reports access revoked (401/403/AccessDenied), the cache
+ *   deletes everything it holds for that identity before surfacing the error.
+ */
+
+import {
+  AccessRevokedError,
+  CacheExpiredError,
+  CacheStorage,
+  isAccessRevoked,
+  SeedableEngine,
+  SeedStats,
+  WarehouseFileSource,
+} from "./types";
+
+const ANONYMOUS = "anonymous";
+const LAST_VERIFIED = "__meta/last-verified";
+
+export interface IcebergFileCacheOptions {
+  storage: CacheStorage;
+  source: WarehouseFileSource;
+  /**
+   * The identity the cached data belongs to — the verified Cognito `sub`.
+   * Entries are namespaced per identity and purged per identity.
+   */
+  identity?: string;
+  /**
+   * Offline-retention bound: how long cached data may be served without the
+   * source re-confirming access (each successful source contact refreshes the
+   * stamp). Past the bound the cache is *deleted*, not served — a device that
+   * revocation can't reach stops holding the data. Unset = no bound.
+   */
+  maxOfflineMs?: number;
+  /** Clock override for tests. */
+  now?: () => number;
+}
+
+export class IcebergFileCache {
+  private storage: CacheStorage;
+  private source: WarehouseFileSource;
+  private maxOfflineMs?: number;
+  private now: () => number;
+  readonly identity: string;
+
+  constructor(options: IcebergFileCacheOptions) {
+    this.storage = options.storage;
+    this.source = options.source;
+    this.identity = options.identity || ANONYMOUS;
+    this.maxOfflineMs = options.maxOfflineMs;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  private ns(key: string): string {
+    return `${this.identity}::${key}`;
+  }
+
+  /** Refresh the access-verified stamp after any successful source contact. */
+  private async stampVerified(): Promise<void> {
+    if (this.maxOfflineMs === undefined) return;
+    await this.storage.put(
+      this.ns(LAST_VERIFIED),
+      new TextEncoder().encode(String(this.now())),
+    );
+  }
+
+  /**
+   * Enforce the offline-retention bound before serving cached bytes without a
+   * live access check. Too stale ⇒ purge and refuse.
+   */
+  private async ensureWithinOfflineBound(): Promise<void> {
+    if (this.maxOfflineMs === undefined) return;
+    const stamp = await this.storage.get(this.ns(LAST_VERIFIED));
+    const verifiedAt = stamp ? Number(new TextDecoder().decode(stamp)) : NaN;
+    if (!Number.isFinite(verifiedAt) || this.now() - verifiedAt > this.maxOfflineMs) {
+      await this.purge();
+      throw new CacheExpiredError();
+    }
+  }
+
+  /**
+   * An immutable warehouse file (snapshot metadata, Parquet data file):
+   * cache-first, fetched and stored on first sight. Revocation purges before
+   * rethrowing.
+   */
+  async getImmutable(key: string): Promise<Uint8Array | null> {
+    const cached = await this.storage.get(this.ns(key));
+    if (cached) return cached;
+    const bytes = await this.fetch(key);
+    if (bytes) await this.storage.put(this.ns(key), bytes);
+    return bytes;
+  }
+
+  /**
+   * The mutable snapshot pointer (`version-hint.text`): network-first so a new
+   * commit is picked up immediately, falling back to the cached copy when the
+   * network is unreachable (offline-tolerant). An access-revoked answer never
+   * falls back — it purges.
+   */
+  async getHint(key: string): Promise<{ bytes: Uint8Array | null; fromCache: boolean }> {
+    try {
+      const bytes = await this.fetch(key);
+      if (bytes) {
+        await this.storage.put(this.ns(key), bytes);
+        return { bytes, fromCache: false };
+      }
+      // The table genuinely has no committed data: drop any stale pointer.
+      await this.storage.delete(this.ns(key));
+      return { bytes: null, fromCache: false };
+    } catch (error) {
+      if (isAccessRevoked(error)) throw error; // already purged by fetch()
+      const cached = await this.storage.get(this.ns(key));
+      if (cached) {
+        // Offline fallback is bounded: past maxOfflineMs the data is deleted
+        // rather than served un-re-verified.
+        await this.ensureWithinOfflineBound();
+        return { bytes: cached, fromCache: true };
+      }
+      throw error;
+    }
+  }
+
+  private async fetch(key: string): Promise<Uint8Array | null> {
+    try {
+      const bytes = await this.source.fetchFile(key);
+      await this.stampVerified();
+      return bytes;
+    } catch (error) {
+      if (isAccessRevoked(error)) {
+        // Revoked access ⇒ this identity's local data must not outlive it.
+        await this.purge();
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Seed a WASM engine by walking each table's Iceberg pointers through the
+   * cache: `version-hint.text` → `v{N}.metadata.json` → that snapshot's data
+   * files. On a warm cache with no new commits this costs one small read per
+   * table; everything else is served locally. Files from superseded snapshots
+   * are pruned from the cache as tables move forward.
+   */
+  async seed(
+    engine: SeedableEngine,
+    resources: { app: string; model: string }[],
+  ): Promise<SeedStats> {
+    const decoder = new TextDecoder();
+    const stats: SeedStats = { tables: 0, fromCache: 0, fetched: 0 };
+
+    for (const { app, model } of resources) {
+      const prefix = `${app}.db/${model}`;
+      const hintKey = `${prefix}/metadata/version-hint.text`;
+
+      const hint = await this.getHint(hintKey);
+      if (!hint.bytes) continue; // no committed data for this table
+      hint.fromCache ? stats.fromCache++ : stats.fetched++;
+      await engine.seedFile(hintKey, hint.bytes);
+      const version = decoder.decode(hint.bytes).trim();
+
+      const metaKey = `${prefix}/metadata/v${version}.metadata.json`;
+      const metaBytes = await this.trackImmutable(metaKey, stats);
+      if (!metaBytes) continue;
+      await engine.seedFile(metaKey, metaBytes);
+
+      const meta = JSON.parse(decoder.decode(metaBytes)) as {
+        data_files?: string[];
+      };
+      const live = new Set([hintKey, metaKey]);
+      for (const rel of meta.data_files || []) {
+        const key = `${prefix}/${rel}`;
+        live.add(key);
+        const bytes = await this.trackImmutable(key, stats);
+        if (bytes) await engine.seedFile(key, bytes);
+      }
+      await this.pruneTable(prefix, live);
+      stats.tables++;
+    }
+    return stats;
+  }
+
+  private async trackImmutable(key: string, stats: SeedStats): Promise<Uint8Array | null> {
+    const hadCached = (await this.storage.get(this.ns(key))) !== null;
+    const bytes = await this.getImmutable(key);
+    if (bytes) hadCached ? stats.fromCache++ : stats.fetched++;
+    return bytes;
+  }
+
+  /** Drop cached files of superseded snapshots for one table. */
+  private async pruneTable(tablePrefix: string, live: Set<string>): Promise<void> {
+    const keys = await this.storage.keys(this.ns(`${tablePrefix}/`));
+    for (const nsKey of keys) {
+      const key = nsKey.slice(this.ns("").length);
+      if (!live.has(key)) await this.storage.delete(nsKey);
+    }
+  }
+
+  /** Delete every cached file belonging to this identity. */
+  async purge(): Promise<void> {
+    await purgeIdentityCache(this.storage, this.identity);
+  }
+}
+
+/** Delete every cached warehouse file a given identity holds on this device. */
+export async function purgeIdentityCache(
+  storage: CacheStorage,
+  identity: string | undefined,
+): Promise<void> {
+  const keys = await storage.keys(`${identity || ANONYMOUS}::`);
+  await Promise.all(keys.map((key) => storage.delete(key)));
+}
+
+/**
+ * A WarehouseFileSource over plain HTTP(S) — the committed `data/warehouse`
+ * directory in `local` mode, or a CloudFront/S3-website endpoint. 401/403
+ * surface as {@link AccessRevokedError}, which is what triggers local purge.
+ */
+export function httpFileSource(
+  baseUrl: string,
+  init?: { headers?: () => Record<string, string> | Promise<Record<string, string>> },
+): WarehouseFileSource {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return {
+    async fetchFile(key: string): Promise<Uint8Array | null> {
+      const headers = init?.headers ? await init.headers() : undefined;
+      const response = await fetch(base + key, headers ? { headers } : undefined);
+      if (response.status === 404) return null;
+      if (response.status === 401 || response.status === 403) {
+        throw new AccessRevokedError(
+          `access to ${key} refused (${response.status})`,
+          response.status,
+        );
+      }
+      if (!response.ok) {
+        throw new Error(`failed to fetch ${key} (${response.status})`);
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  };
+}

package/cache/encrypted.ts

@@ -0,0 +1,100 @@
+/**
+ * At-rest encryption for the local cache: wrap any {@link CacheStorage} in
+ * AES-256-GCM (WebCrypto). Every value is sealed with a fresh random 12-byte
+ * IV (prepended to the ciphertext), so identical plaintexts never produce
+ * identical stored bytes and integrity is authenticated on read.
+ *
+ * Key custody stays with the app — pass a `CryptoKey` or an async provider:
+ * on web, generate a **non-extractable** key once and persist the CryptoKey
+ * object itself in IndexedDB (the raw bits never exist in JS); on React
+ * Native, keep the raw key in the platform keystore (Keychain / Android
+ * Keystore via expo-secure-store) and `importEncryptionKey` it at startup.
+ *
+ * A value that fails to decrypt (tampered, or written under a different key)
+ * reads as a cache miss — the cache re-fetches from the source rather than
+ * ever surfacing unauthenticated bytes.
+ */
+
+import { CacheStorage } from "./types";
+
+const IV_BYTES = 12;
+
+function subtle(): any {
+  const subtleCrypto = (globalThis as any).crypto?.subtle;
+  if (!subtleCrypto) {
+    throw new Error(
+      "WebCrypto is unavailable; provide a platform crypto polyfill to use the encrypted cache.",
+    );
+  }
+  return subtleCrypto;
+}
+
+/** Generate a non-extractable AES-256-GCM cache key. */
+export function generateEncryptionKey(extractable = false): Promise<any> {
+  return subtle().generateKey({ name: "AES-GCM", length: 256 }, extractable, [
+    "encrypt",
+    "decrypt",
+  ]);
+}
+
+/** Import a raw 32-byte key (e.g. from the platform keystore). */
+export function importEncryptionKey(raw: Uint8Array): Promise<any> {
+  return subtle().importKey("raw", raw.slice().buffer, { name: "AES-GCM" }, false, [
+    "encrypt",
+    "decrypt",
+  ]);
+}
+
+export type EncryptionKeySource = any | (() => any | Promise<any>);
+
+export function createEncryptedCacheStorage(
+  inner: CacheStorage,
+  key: EncryptionKeySource,
+): CacheStorage {
+  const resolveKey = async (): Promise<any> =>
+    typeof key === "function" ? key() : key;
+
+  return {
+    async get(name: string): Promise<Uint8Array | null> {
+      const sealed = await inner.get(name);
+      if (!sealed || sealed.length <= IV_BYTES) return null;
+      try {
+        const plain = await subtle().decrypt(
+          { name: "AES-GCM", iv: sealed.slice(0, IV_BYTES) },
+          await resolveKey(),
+          sealed.slice(IV_BYTES),
+        );
+        return new Uint8Array(plain);
+      } catch {
+        // Wrong key or tampered bytes: never surface unauthenticated data.
+        return null;
+      }
+    },
+
+    async put(name: string, bytes: Uint8Array): Promise<void> {
+      const iv = new Uint8Array(IV_BYTES);
+      (globalThis as any).crypto.getRandomValues(iv);
+      const sealed = new Uint8Array(
+        await subtle().encrypt(
+          { name: "AES-GCM", iv },
+          await resolveKey(),
+          bytes.slice().buffer,
+        ),
+      );
+      const out = new Uint8Array(IV_BYTES + sealed.length);
+      out.set(iv, 0);
+      out.set(sealed, IV_BYTES);
+      await inner.put(name, out);
+    },
+
+    delete(name: string): Promise<void> {
+      return inner.delete(name);
+    },
+
+    keys(prefix?: string): Promise<string[]> {
+      // Keys stay in the clear (they are warehouse paths, not row data) so
+      // namespace purge and pruning keep working.
+      return inner.keys(prefix);
+    },
+  };
+}

package/cache/index.ts

@@ -0,0 +1,32 @@
+export {
+  AccessRevokedError,
+  CacheExpiredError,
+  isAccessRevoked,
+} from "./types";
+export {
+  createEncryptedCacheStorage,
+  generateEncryptionKey,
+  importEncryptionKey,
+} from "./encrypted";
+export type { EncryptionKeySource } from "./encrypted";
+export type {
+  CacheStorage,
+  SeedableEngine,
+  SeedStats,
+  WarehouseFileSource,
+} from "./types";
+export {
+  httpFileSource,
+  IcebergFileCache,
+  purgeIdentityCache,
+} from "./cache";
+export type { IcebergFileCacheOptions } from "./cache";
+export {
+  createKeyValueCacheStorage,
+  defaultCacheStorage,
+  IndexedDbCacheStorage,
+  MemoryCacheStorage,
+} from "./storage";
+export type { KeyValueStore } from "./storage";
+export { deleteIndexedDb, purgeLocalData } from "./revocation";
+export type { PurgeLocalDataOptions } from "./revocation";

package/cache/revocation.ts

@@ -0,0 +1,50 @@
+/**
+ * Local data deletion for access revocation and sign-out.
+ *
+ * The rule: local data never outlives the access that fetched it. When the
+ * backend says an identity may no longer read the data (revoked token, expired
+ * Cognito session that can't refresh, S3 AccessDenied), everything that
+ * identity holds on the device is deleted — the Iceberg file cache, the
+ * persisted warehouse snapshot, and the sync-engine store.
+ */
+
+import { purgeIdentityCache } from "./cache";
+import { CacheStorage } from "./types";
+
+/** Delete an IndexedDB database outright. Resolves quietly where IDB is absent. */
+export function deleteIndexedDb(name: string): Promise<void> {
+  const idb = (globalThis as any).indexedDB;
+  if (!idb) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const request = idb.deleteDatabase(name);
+    request.onsuccess = () => resolve();
+    // `blocked` still deletes once open connections close; don't hang on it.
+    request.onblocked = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+}
+
+export interface PurgeLocalDataOptions {
+  /** The identity whose data is being removed (the Cognito `sub`). */
+  identity?: string;
+  /** The Iceberg file cache's storage — its identity namespace is emptied. */
+  cacheStorage?: CacheStorage;
+  /**
+   * IndexedDB databases to delete outright — the persisted warehouse snapshot
+   * (`rad-warehouse…`) and the sync-engine store, which hold row data derived
+   * from the revoked access.
+   */
+  databases?: string[];
+}
+
+/** Remove every locally persisted trace of an identity's data. */
+export async function purgeLocalData(options: PurgeLocalDataOptions): Promise<void> {
+  const tasks: Promise<unknown>[] = [];
+  if (options.cacheStorage) {
+    tasks.push(purgeIdentityCache(options.cacheStorage, options.identity));
+  }
+  for (const name of options.databases || []) {
+    tasks.push(deleteIndexedDb(name));
+  }
+  await Promise.all(tasks);
+}

package/cache/storage.ts

@@ -0,0 +1,164 @@
+/**
+ * CacheStorage implementations: IndexedDB for the web, an in-memory fallback
+ * for SSR/tests, and a key-value adapter that turns any React Native storage
+ * engine (expo-file-system, MMKV, expo-sqlite/kv-store, AsyncStorage) into a
+ * CacheStorage — the mobile answer to "IndexedDB on web".
+ *
+ * IndexedDB is reached through `globalThis` so this module type-checks (and
+ * degrades cleanly) on platforms compiled without DOM types.
+ */
+
+import { CacheStorage } from "./types";
+
+const STORE = "files";
+
+function idbFactory(): any | undefined {
+  return (globalThis as any).indexedDB;
+}
+
+function openDb(name: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const request = idbFactory()!.open(name, 1);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE)) {
+        db.createObjectStore(STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+export class IndexedDbCacheStorage implements CacheStorage {
+  private db: Promise<any>;
+
+  constructor(databaseName = "rad-iceberg-cache") {
+    this.db = openDb(databaseName);
+  }
+
+  private async run<T>(mode: "readonly" | "readwrite", op: (store: any) => any): Promise<T> {
+    const db = await this.db;
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, mode);
+      const request = op(tx.objectStore(STORE));
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async get(key: string): Promise<Uint8Array | null> {
+    const value = await this.run<ArrayBuffer | undefined>("readonly", (s) => s.get(key));
+    return value ? new Uint8Array(value) : null;
+  }
+
+  async put(key: string, bytes: Uint8Array): Promise<void> {
+    // Store a copy: the caller may reuse its buffer.
+    await this.run("readwrite", (s) => s.put(bytes.slice().buffer, key));
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.run("readwrite", (s) => s.delete(key));
+  }
+
+  async keys(prefix = ""): Promise<string[]> {
+    const all = await this.run<unknown[]>("readonly", (s) => s.getAllKeys());
+    return all
+      .filter((k): k is string => typeof k === "string")
+      .filter((k) => k.startsWith(prefix));
+  }
+}
+
+/** In-memory CacheStorage — SSR, tests, and unsupported environments. */
+export class MemoryCacheStorage implements CacheStorage {
+  private map = new Map<string, Uint8Array>();
+
+  async get(key: string): Promise<Uint8Array | null> {
+    const bytes = this.map.get(key);
+    return bytes ? bytes.slice() : null;
+  }
+
+  async put(key: string, bytes: Uint8Array): Promise<void> {
+    this.map.set(key, bytes.slice());
+  }
+
+  async delete(key: string): Promise<void> {
+    this.map.delete(key);
+  }
+
+  async keys(prefix = ""): Promise<string[]> {
+    return Array.from(this.map.keys()).filter((k) => k.startsWith(prefix));
+  }
+}
+
+/**
+ * The minimal string key-value surface most React Native storage engines
+ * already expose (AsyncStorage verbatim; MMKV / expo-file-system / SQLite in a
+ * few lines).
+ */
+export interface KeyValueStore {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+  getAllKeys(): Promise<string[]>;
+}
+
+/**
+ * Adapt a string KeyValueStore into a byte CacheStorage (values are
+ * base64-encoded). This is how mobile apps plug their platform storage into
+ * the same Iceberg file cache the web uses:
+ *
+ * ```ts
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ * const storage = createKeyValueCacheStorage(AsyncStorage);
+ * ```
+ */
+export function createKeyValueCacheStorage(kv: KeyValueStore): CacheStorage {
+  return {
+    async get(key) {
+      const value = await kv.getItem(key);
+      return value === null ? null : fromBase64(value);
+    },
+    async put(key, bytes) {
+      await kv.setItem(key, toBase64(bytes));
+    },
+    async delete(key) {
+      await kv.removeItem(key);
+    },
+    async keys(prefix = "") {
+      const all = await kv.getAllKeys();
+      return all.filter((k) => k.startsWith(prefix));
+    },
+  };
+}
+
+/** The default storage for the current platform. */
+export function defaultCacheStorage(databaseName?: string): CacheStorage {
+  if (idbFactory()) {
+    return new IndexedDbCacheStorage(databaseName);
+  }
+  return new MemoryCacheStorage();
+}
+
+// -- base64 (btoa/atob on web, Buffer on node/RN polyfills) -------------------
+
+function toBase64(bytes: Uint8Array): string {
+  const btoaFn = (globalThis as any).btoa;
+  if (typeof btoaFn === "function") {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoaFn(binary);
+  }
+  return (globalThis as any).Buffer.from(bytes).toString("base64");
+}
+
+function fromBase64(value: string): Uint8Array {
+  const atobFn = (globalThis as any).atob;
+  if (typeof atobFn === "function") {
+    const binary = atobFn(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array((globalThis as any).Buffer.from(value, "base64"));
+}

package/cache/types.ts

@@ -0,0 +1,85 @@
+/**
+ * The local Iceberg file cache: types.
+ *
+ * The database is a set of Iceberg files on object storage, and the browser
+ * queries them through the WASM engine — so the local cache is a cache of
+ * *those files*, not a second database. Iceberg's layout makes this cheap and
+ * exact: snapshot metadata and data files are immutable (a new commit writes
+ * new files and swaps one tiny pointer, `version-hint.text`), so everything
+ * except the pointer can be cached forever and revalidation costs one small
+ * read.
+ */
+
+/**
+ * Async byte storage behind the cache. Web uses {@link IndexedDbCacheStorage};
+ * React Native / Expo supply any key-value engine (expo-file-system, MMKV,
+ * expo-sqlite, AsyncStorage) through {@link createKeyValueCacheStorage} — the
+ * cache itself is platform-free.
+ */
+export interface CacheStorage {
+  get(key: string): Promise<Uint8Array | null>;
+  put(key: string, bytes: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Every stored key, optionally only those starting with `prefix`. */
+  keys(prefix?: string): Promise<string[]>;
+}
+
+/**
+ * Where warehouse files come from: a public HTTP directory in `local` mode, or
+ * SigV4-signed S3 GETs (Cognito Identity Pool temp credentials) in `s3` mode.
+ * Implementations MUST throw {@link AccessRevokedError} when the backend
+ * refuses access (HTTP 401/403, S3 AccessDenied, an expired identity that can
+ * no longer be refreshed) — that signal is what triggers local data deletion.
+ */
+export interface WarehouseFileSource {
+  /** Fetch one warehouse object by key, or `null` if it does not exist. */
+  fetchFile(key: string): Promise<Uint8Array | null>;
+}
+
+/** The engine surface seeding needs (the WASM `RadApi`). */
+export interface SeedableEngine {
+  seedFile(key: string, bytes: Uint8Array): Promise<void>;
+}
+
+/**
+ * Access to the data has been revoked (or the identity can no longer prove
+ * it). The cache reacts by deleting everything it holds for that identity.
+ */
+export class AccessRevokedError extends Error {
+  readonly status?: number;
+
+  constructor(message = "Access revoked", status?: number) {
+    super(message);
+    this.name = "AccessRevokedError";
+    this.status = status;
+  }
+}
+
+export function isAccessRevoked(error: unknown): error is AccessRevokedError {
+  return (
+    error instanceof AccessRevokedError ||
+    (error instanceof Error && error.name === "AccessRevokedError")
+  );
+}
+
+/**
+ * The cache exceeded its offline-retention bound (`maxOfflineMs`): access
+ * could not be re-verified for too long, so the cached data was deleted
+ * rather than served. Distinct from {@link AccessRevokedError} — access may
+ * still be fine, but it could not be proven.
+ */
+export class CacheExpiredError extends Error {
+  constructor(message = "Cached data expired: access not re-verified in time") {
+    super(message);
+    this.name = "CacheExpiredError";
+  }
+}
+
+/** What a cached seed did — how much came from cache vs. the network. */
+export interface SeedStats {
+  tables: number;
+  /** Files served straight from the local cache (no network). */
+  fromCache: number;
+  /** Files fetched from the source (then cached). */
+  fetched: number;
+}