@ixo/oracle-runtime-workers 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {

package/src/core/env.ts

@@ -76,6 +76,15 @@ export const baseEnvSchema = z.object({
   /** UCAN store worker base URL (defaults per NETWORK). */
   UCAN_STORE_URL: z.string().url().optional(),
 
+  /**
+   * R2 page tier knobs (the bucket itself is a binding, `TIER_BUCKET`, not
+   * a var). Hot-set target in bytes (or `16m`), periods of inactivity before
+   * a chunk is evicted, and the period length in ms (a day; tests shorten it).
+   */
+  TIER_HOT_BUDGET_BYTES: z.string().min(1).optional(),
+  TIER_EVICT_AFTER_PERIODS: z.coerce.number().int().min(1).optional(),
+  TIER_PERIOD_MS: z.coerce.number().int().min(1000).optional(),
+
   // --- llm ----------------------------------------------------------------
   OPEN_ROUTER_API_KEY: z.string().min(1),
   /**

package/src/do/contracts.ts

@@ -1,6 +1,7 @@
 import type { BotStatus, EncryptedFileInfo } from '@ixo/matrix-bot-workers-sdk';
 import type { AttachmentInput } from '../attachments/types';
 import type { RealtimeStatus } from '../realtime/realtime-endpoint';
+import type { TierFlushResult, TierStatus } from '../sqlite/do-vfs';
 /**
  * Cross-object contracts for the Workers runtime.
  *
@@ -82,6 +83,20 @@ export interface OracleWorkerEnv {
    * for the hit/miss counters that show what a budget buys.
    */
   CHUNK_CACHE_BYTES?: string;
+  /**
+   * R2 page tier for the users' working copies (see `sqlite/page-tier.ts`):
+   * chunks no turn touched for `TIER_EVICT_AFTER_PERIODS` periods move
+   * from DO SQLite ($0.20/GB-month, 10 GB cap per object) into 1 MiB R2
+   * segment objects ($0.015/GB-month, no cap) under a per-object prefix.
+   * Absent = every chunk stays in DO storage (the pre-tier behaviour).
+   */
+  TIER_BUCKET?: R2Bucket;
+  /** Soft target for hot bytes per user object (bytes or `16m`; default 16 MiB). */
+  TIER_HOT_BUDGET_BYTES?: string;
+  /** Periods (of `TIER_PERIOD_MS`) a chunk must go untouched before eviction (default 2). */
+  TIER_EVICT_AFTER_PERIODS?: string;
+  /** Length of one access-tracking period in ms (default one day; tests shorten it). */
+  TIER_PERIOD_MS?: string;
   /** IXO VFS worker base URL when `OWNER_STORE=vfs` (defaults per NETWORK). */
   VFS_BASE_URL?: string;
   /** UCAN store worker base URL when `OWNER_STORE=vfs` (defaults per NETWORK). */
@@ -284,6 +299,8 @@ export interface StorageStatus {
   freelistCount?: number;
   /** SQLite's own page cache (`PRAGMA cache_size`; negative = KiB). */
   sqliteCacheSize?: number;
+  /** The R2 page tier of this object's working copy (see sqlite/page-tier.ts). */
+  tier?: TierStatus & { lastPassAt?: number };
   /** The DO VFS clean-chunk cache and its storage counters (isolate lifetime). */
   chunkCache?: {
     budgetBytes: number;
@@ -356,6 +373,11 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
    * the "user deleted their file upstream" path.
    */
   resetWorkingCopy(): Promise<{ reloadedFromOwnerStore: boolean }>;
+  /** Run one R2 page-tier eviction pass now (debug routes; `force` ignores recency). */
+  tierFlush(opts?: {
+    force?: boolean;
+    maxSegments?: number;
+  }): Promise<TierFlushResult>;
   /** Raw upstream schema of the memory search tool as fetched right now. */
   debugMemorySchema(userDid: string): Promise<MemorySchemaDebug>;
   /** Forcibly reset the object like a platform host drain (debug routes only). The call itself rejects. */

package/src/do/user-oracle-do.ts

@@ -83,12 +83,17 @@ import {
   finishCompaction,
   type CompactCursors,
 } from '../sqlite/blob-compactor';
-import { createHash } from 'node:crypto';
 import {
   cachePagesForBytes,
+  parseByteSize,
   parseChunkCacheBytes,
 } from '../sqlite/cache-config';
-import { DoSqliteDatabase } from '../sqlite/database';
+import { DoSqliteDatabase, type DoSqliteOpenOptions } from '../sqlite/database';
+import type { TierFlushResult } from '../sqlite/do-vfs';
+import {
+  DEFAULT_TIER_HOT_BUDGET_BYTES,
+  type PageTierOptions,
+} from '../sqlite/page-tier';
 import {
   shouldVacuum,
   vacuumWanted,
@@ -107,6 +112,7 @@ import {
 } from '../sqlite/sessions-store';
 import { createAttachmentDecryptor } from '@ixo/matrix-bot-workers-sdk';
 import { MatrixMediaOwnerStore } from '../owner-store/matrix-media-store';
+import { measureForSave } from '../owner-store/measure';
 import { MigratingOwnerStore } from '../owner-store/migrating-store';
 import type { OwnerCopy } from '../owner-store/types';
 import {
@@ -224,6 +230,14 @@ interface MatrixUserIdCache {
 /** Consecutive flush failures (cleared on success). */
 const META_FLUSH_FAILURES = 'meta:flushFailures';
 const META_LAST_VACUUM = 'meta:lastVacuumAt';
+/** When the last R2 page-tier eviction pass ran (see `tierTick`). */
+const META_LAST_TIER_PASS = 'meta:lastTierPassAt';
+/**
+ * Eviction passes at most this often per object. The horizon is two daily
+ * periods, so four checks a day catch chunks the moment they age out
+ * without re-reading the hot set more than that.
+ */
+const TIER_PASS_INTERVAL_MS = 6 * 60 * 60_000;
 /**
  * Persisted twin of the in-memory `dirty` flag. The flag alone dies with an
  * eviction, and evictions are routine — without the marker an alarm waking a
@@ -314,22 +328,6 @@ interface FlushResult {
 }
 
 /** Hex SHA-256 of a byte stream, hashed as it flows. */
-async function sha256OfStream(
-  stream: ReadableStream<Uint8Array>,
-): Promise<string> {
-  const hash = createHash('sha256');
-  const reader = stream.getReader();
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      hash.update(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return hash.digest('hex');
-}
 
 /** Does this adapter expose provider config + role resolution (platform adapters do)? */
 function isProviderAdapter(llm: LlmAdapter): llm is OpenRouterLlmAdapter {
@@ -1131,7 +1129,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       if (db) {
         await db.close().catch(() => undefined);
       }
-      await DoSqliteDatabase.wipe(this.ctx, DB_FILE);
+      const tier = this.tierOptions();
+      await DoSqliteDatabase.wipe(this.ctx, DB_FILE, tier ? { tier } : {});
       await this.ctx.storage.delete([
         META_OWNER_ETAG,
         META_LAST_CHECKSUM,
@@ -1142,12 +1141,40 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       ]);
     }
 
-    /** `CHUNK_CACHE_BYTES` → the VFS clean-chunk budget for this object. */
-    private sqliteOpenOptions(): { cachePages: number } {
+    /**
+     * `CHUNK_CACHE_BYTES` → the VFS clean-chunk budget for this object, and
+     * the R2 page tier when the script binds `TIER_BUCKET` (the object's id
+     * is its key prefix; the knobs are documented in `contracts.ts`).
+     */
+    private sqliteOpenOptions(): DoSqliteOpenOptions {
       const bytes = parseChunkCacheBytes(this.env.CHUNK_CACHE_BYTES, (m) =>
         console.warn(`[user-do] ${m}`),
       );
-      return { cachePages: cachePagesForBytes(bytes) };
+      const tier = this.tierOptions();
+      return { cachePages: cachePagesForBytes(bytes), ...(tier && { tier }) };
+    }
+
+    private tierOptions(): PageTierOptions | undefined {
+      const bucket = this.env.TIER_BUCKET;
+      if (!bucket) return undefined;
+      const warn = (m: string): void => console.warn(`[user-do] ${m}`);
+      const hotBudgetBytes = parseByteSize(this.env.TIER_HOT_BUDGET_BYTES, {
+        name: 'TIER_HOT_BUDGET_BYTES',
+        fallback: DEFAULT_TIER_HOT_BUDGET_BYTES,
+        min: 1024 * 1024,
+        max: 1024 * 1024 * 1024,
+        warn,
+      });
+      const periods = Number(this.env.TIER_EVICT_AFTER_PERIODS);
+      const periodMs = Number(this.env.TIER_PERIOD_MS);
+      return {
+        bucket,
+        prefix: this.ctx.id.toString(),
+        hotBudgetBytes,
+        ...(Number.isInteger(periods) &&
+          periods >= 1 && { evictAfterPeriods: periods }),
+        ...(Number.isFinite(periodMs) && periodMs >= 1000 && { periodMs }),
+      };
     }
 
     /**
@@ -1333,6 +1360,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         if (next !== null) deadlines.push(next);
       }
 
+      // R2 page tier: move chunks no turn touched for a couple of days out
+      // of DO storage (see sqlite/page-tier.ts). After the flush above (the
+      // upload reads hot rows, not R2) and never over an in-flight one (it
+      // holds a snapshot). A pass is capped; more work re-arms soon.
+      if (this.db?.tierEnabled && !this.flushInFlight) {
+        const next = await this.tierTick(this.db, now);
+        if (next !== null) deadlines.push(next);
+      }
+
       // Idle housekeeping: a user silent for a day loses the cached pages —
       // their file is safe upstream, and we stop paying to store a copy. Never
       // evict while tasks are scheduled: their runs ARE activity. The flush
@@ -1361,6 +1397,71 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       );
     }
 
+    /**
+     * One page-tier eviction pass, at most once per `TIER_PASS_INTERVAL_MS`
+     * (a pass that hit its segment cap re-arms in a minute). Returns the next
+     * time a pass is due, or null when nothing is pending.
+     */
+    private async tierTick(
+      db: DoSqliteDatabase,
+      now: number,
+    ): Promise<number | null> {
+      const last =
+        (await this.ctx.storage.get<number>(META_LAST_TIER_PASS)) ?? 0;
+      if (now - last < TIER_PASS_INTERVAL_MS)
+        return last + TIER_PASS_INTERVAL_MS;
+      try {
+        const pass = await db.tierFlush();
+        await this.ctx.storage.put(META_LAST_TIER_PASS, now);
+        if (pass.skipped) {
+          if (pass.skipped !== 'no-tier')
+            console.log(
+              `[user-do] tier pass skipped for ${this.userDid}: ${pass.skipped}`,
+            );
+          return now + 60_000;
+        }
+        if (pass.evictedChunks > 0 || pass.remaining > 0) {
+          console.log(
+            `[user-do] tier pass for ${this.userDid}: ${pass.evictedChunks} chunks → R2 in ${pass.segmentsRewritten} segment(s), ${pass.hotRows} hot rows (${Math.round(pass.hotBytes / 1024 / 1024)} MB) kept, ${pass.remaining} segment(s) pending`,
+          );
+        }
+        const budget = this.tierOptions()?.hotBudgetBytes;
+        if (
+          budget !== undefined &&
+          pass.remaining === 0 &&
+          pass.hotBytes > budget
+        ) {
+          // Everything left is recent: the user's real working set exceeds
+          // the target — a sizing signal, not a failure.
+          console.warn(
+            `[user-do] tier hot set of ${this.userDid} is ${Math.round(pass.hotBytes / 1024 / 1024)} MB, over the ${Math.round(budget / 1024 / 1024)} MB target (all of it touched within the eviction horizon)`,
+          );
+        }
+        return pass.remaining > 0 ? now + 60_000 : now + TIER_PASS_INTERVAL_MS;
+      } catch (err) {
+        console.error(
+          `[user-do] tier pass failed for ${this.userDid}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return now + FLUSH_RETRY_DELAY_MS;
+      }
+    }
+
+    /** Operator/test entry: run an eviction pass now (debug routes). */
+    async tierFlush(
+      opts: { force?: boolean; maxSegments?: number } = {},
+    ): Promise<TierFlushResult> {
+      if (!this.db) {
+        const userDid =
+          this.userDid ?? (await this.ctx.storage.get<string>(META_USER_DID));
+        if (userDid) await this.ready({ userDid });
+      }
+      if (!this.db) throw new Error('no working copy');
+      if (this.flushInFlight) await this.flushInFlight.catch(() => undefined);
+      const pass = await this.db.tierFlush(opts);
+      await this.ctx.storage.put(META_LAST_TIER_PASS, Date.now());
+      return pass;
+    }
+
     /**
      * One VACUUM policy check. Returns the time of a follow-up check when a
      * rebuild is wanted but the object is not quiet yet, else null.
@@ -2015,7 +2116,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
 
       const snapshot = await db.snapshot();
       try {
-        const checksum = await sha256OfStream(snapshot.open());
+        // One pass yields the change gate (hash) AND the length the store
+        // needs to upload; the upload is the only other read of the file.
+        const { sha256Hex: checksum, gzippedLength } = await measureForSave(
+          snapshot.open(),
+        );
         const last = await this.ctx.storage.get<string>(META_LAST_CHECKSUM);
         if (last === checksum) {
           await this.ctx.storage.put(META_UPLOADED_GEN, snapshot.generation);
@@ -2030,7 +2135,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
 
         let saved: { etag: string; bytes: number };
         try {
-          saved = await store.save(snapshot);
+          saved = await store.save(snapshot, { gzippedLength });
         } catch (err) {
           // Never diverted anywhere else: the working copy in Durable Object
           // storage is durable, stays dirty, and is retried. Loud from the
@@ -2295,6 +2400,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
               rowsWritten: vfs.rowsWritten,
             }
           : undefined,
+        tier: db
+          ? {
+              ...db.tierStatus(),
+              lastPassAt:
+                await this.ctx.storage.get<number>(META_LAST_TIER_PASS),
+            }
+          : undefined,
       };
     }
 
@@ -3235,6 +3347,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           await sessions.setTitle(sessionId, title, { onlyIfUntitled: true });
       }
       this.markDirty();
+      // Which chunks this turn touched, for the page tier's eviction policy
+      // (one row write; a no-op without a tier).
+      try {
+        this.db?.recordAccess();
+      } catch (err) {
+        console.warn(
+          `[user-do] tier access record failed for ${this.userDid}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
     }
 
     private async generateTitle(

package/src/owner-store/ixo-vfs-store.ts

@@ -50,6 +50,7 @@ import {
   type OwnerCopy,
   type OwnerStore,
   type SaveResult,
+  type SaveHints,
 } from './types';
 
 const VFS_RESOURCE = 'ixo:filesystem';
@@ -233,9 +234,11 @@ export class IxoVfsOwnerStore implements OwnerStore {
    * Atomic replace, always delete + re-create, never a new version:
    *
    *   1. drop stale `.uploading-*` temp files a crashed flush left behind;
-   *   2. measure the gzipped length in a counting pass (the VFS needs
-   *      `Upload-Length` at session creation — `Upload-Defer-Length` is not
-   *      supported — and gzip output is deterministic for identical input);
+   *   2. take the gzipped length from `hints` (the object measured it in the
+   *      same pass as its checksum) or, without a hint, count it in a pass
+   *      of its own (the VFS needs `Upload-Length` at session creation —
+   *      `Upload-Defer-Length` is not supported — and gzip output is
+   *      deterministic for identical input);
    *   3. upload gzip → a TEMP path next to the real one: one `POST /files`
    *      when it fits in a single part, else a tus session in 5 MiB parts
    *      (`tusUpload`, resumable per part);
@@ -247,7 +250,10 @@ export class IxoVfsOwnerStore implements OwnerStore {
    * file is cleaned up then). Peak memory is one part (5 MiB) plus fixed
    * overhead, whatever the file size.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
+  async save(
+    snapshot: FileSnapshot,
+    hints: SaveHints = {},
+  ): Promise<SaveResult> {
     const listing = await this.listOracleFiles();
     const existing = listing.filter((f) => f.path === this.path);
     const stale = listing.filter((f) =>
@@ -261,7 +267,8 @@ export class IxoVfsOwnerStore implements OwnerStore {
       });
     }
 
-    const gzLength = await countStream(gzipStream(snapshot.open()));
+    const gzLength =
+      hints.gzippedLength ?? (await countStream(gzipStream(snapshot.open())));
     const tempPath = `${this.path}${TEMP_PATH_INFIX}${Date.now().toString(36)}`;
     const uploaded =
       gzLength <= SINGLE_SHOT_MAX_BYTES

package/src/owner-store/matrix-media-store.ts

@@ -22,6 +22,7 @@ import {
   type OwnerCopy,
   type OwnerStore,
   type SaveResult,
+  type SaveHints,
 } from './types';
 
 /**
@@ -89,19 +90,23 @@ export class MatrixMediaOwnerStore implements OwnerStore {
   }
 
   /**
-   * Streamed as well: the snapshot is opened three times — a header peek, a
-   * gzip pass that only counts (the homeserver needs the exact ciphertext
-   * length up front; gzip output is deterministic for identical input, the
-   * VFS store relies on the same property) and the gzip pass that is
-   * uploaded — and never held whole.
+   * Streamed as well: the snapshot is opened for a header peek, for a gzip
+   * pass that only counts unless the caller measured the length already
+   * (`hints`; the homeserver needs the exact ciphertext length up front and
+   * gzip output is deterministic for identical input) and for the gzip pass
+   * that is uploaded — and never held whole.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
+  async save(
+    snapshot: FileSnapshot,
+    hints: SaveHints = {},
+  ): Promise<SaveResult> {
     const checked = await assertSqliteStream(
       snapshot.open(),
       `MatrixMediaOwnerStore: refusing to save — the working copy (${snapshot.size} bytes)`,
     );
     await checked.cancel().catch(() => undefined);
-    const gzLength = await countStream(gzipStream(snapshot.open()));
+    const gzLength =
+      hints.gzippedLength ?? (await countStream(gzipStream(snapshot.open())));
     const { eventId } = await this.gateway.uploadUserSnapshotStream(
       this.userDid,
       this.storageKey,

package/src/owner-store/measure.ts

@@ -0,0 +1,39 @@
+/**
+ * One streamed pass over a snapshot that yields BOTH what a flush needs
+ * before it uploads: the SHA-256 of the raw SQLite bytes (the "did anything
+ * change" gate against the last upload) and the exact gzipped length (the
+ * VFS needs `Upload-Length` when the tus session is created). Before this
+ * helper the object hashed in one pass and the store counted the gzip in a
+ * second one; with the R2 page tier every pass over a cold file is one R2
+ * GET per segment, so the two are folded together and the upload itself is
+ * the only other read.
+ *
+ * The length is exact for the store's own gzip: `gzipStream` is the same
+ * `CompressionStream('gzip')` the stores pipe the upload through, and its
+ * output is deterministic for identical input.
+ */
+import { createHash } from 'node:crypto';
+import { countStream, gzipStream } from './types';
+
+export interface SnapshotMeasure {
+  /** Hex SHA-256 of the raw (uncompressed) bytes. */
+  sha256Hex: string;
+  /** Byte length of `gzipStream(<the same bytes>)`. */
+  gzippedLength: number;
+}
+
+export async function measureForSave(
+  stream: ReadableStream<Uint8Array>,
+): Promise<SnapshotMeasure> {
+  const hash = createHash('sha256');
+  const tapped = stream.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        hash.update(chunk);
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  const gzippedLength = await countStream(gzipStream(tapped));
+  return { sha256Hex: hash.digest('hex'), gzippedLength };
+}

package/src/owner-store/migrating-store.ts

@@ -20,7 +20,13 @@
  *            Matrix copy so no second copy of the user's history lingers.
  */
 import { VfsNoDelegationError } from './ixo-vfs-store';
-import type { FileSnapshot, OwnerCopy, OwnerStore, SaveResult } from './types';
+import type {
+  FileSnapshot,
+  OwnerCopy,
+  OwnerStore,
+  SaveHints,
+  SaveResult,
+} from './types';
 
 export interface MigratingOwnerStoreOptions {
   /** System of record (IXO VFS). */
@@ -104,8 +110,8 @@ export class MigratingOwnerStore implements OwnerStore {
    * "not on VFS yet" (no delegation) — so the object keeps the copy dirty
    * and retries; Matrix media is never written.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
-    return this.primary.save(snapshot);
+  async save(snapshot: FileSnapshot, hints?: SaveHints): Promise<SaveResult> {
+    return this.primary.save(snapshot, hints);
   }
 
   /**

package/src/owner-store/types.ts

@@ -15,9 +15,13 @@
  * Both directions STREAM: `load()` hands back the raw (already gunzipped)
  * SQLite bytes as a `ReadableStream` the object writes into its VFS chunk by
  * chunk, and `save()` takes a `FileSnapshot` — a re-openable, consistent
- * view of the working copy — that the store reads as many times as it needs
- * (the VFS store measures the gzipped length in one pass and uploads in a
- * second). Nothing on this path ever holds the whole file in memory — the
+ * view of the working copy — that the store reads as many times as it needs.
+ * The object measures the hash and the gzipped length in ONE pass
+ * (`measureForSave`) and hands the length in as a `SaveHints`, so a store
+ * only reads the snapshot once more, for the upload itself; a store called
+ * without the hint counts the gzip in a pass of its own. That matters with
+ * the R2 page tier, where every pass over a cold file is one R2 GET per
+ * segment. Nothing on this path ever holds the whole file in memory — the
  * legacy Matrix media path included: the gateway hands the media over as a
  * stream and decryption, gunzip and the SQLite header check run chunk by
  * chunk in the object. Compression is the store's concern. `etag` lets the object skip a reload
@@ -26,7 +30,7 @@
 export interface OwnerStore {
   readonly kind: 'matrix' | 'vfs';
   load(): Promise<OwnerCopy | null>;
-  save(snapshot: FileSnapshot): Promise<SaveResult>;
+  save(snapshot: FileSnapshot, hints?: SaveHints): Promise<SaveResult>;
   /** Cheap upstream freshness probe — null when unsupported/unknown. */
   head(): Promise<{ etag: string } | null>;
   /** Remove the durable copy (user asked to be forgotten). */
@@ -60,6 +64,12 @@ export interface OwnerCopy {
   fromLegacy?: true;
 }
 
+/** What the caller already measured about the snapshot (see `measureForSave`). */
+export interface SaveHints {
+  /** Byte length of `gzipStream(snapshot.open())`; spares the store its counting pass. */
+  gzippedLength?: number;
+}
+
 export interface SaveResult {
   etag: string;
   /** Bytes actually sent upstream (compressed size on the VFS path). */

package/src/shell/app.ts

@@ -471,6 +471,18 @@ export function createShell(
   app.post('/debug/storage/flush', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).flushToOwnerStore()),
   );
+  app.post('/debug/storage/tier-flush', async (c) => {
+    const body: unknown = await c.req.json().catch(() => ({}));
+    const rec = typeof body === 'object' && body !== null ? body : {};
+    const force = Reflect.get(rec, 'force') === true;
+    const max = Number(Reflect.get(rec, 'maxSegments'));
+    return c.json(
+      await userStub(c.env, c.get('auth').userDid).tierFlush({
+        force,
+        ...(Number.isInteger(max) && max > 0 && { maxSegments: max }),
+      }),
+    );
+  });
   app.post('/debug/storage/reset', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).resetWorkingCopy()),
   );

package/src/sqlite/cache-config.ts

@@ -19,22 +19,43 @@ export function parseChunkCacheBytes(
   raw: string | undefined,
   warn: (message: string) => void = () => undefined,
 ): number {
-  if (raw === undefined || raw.trim() === '') return DEFAULT_CHUNK_CACHE_BYTES;
+  return parseByteSize(raw, {
+    name: 'CHUNK_CACHE_BYTES',
+    fallback: DEFAULT_CHUNK_CACHE_BYTES,
+    min: MIN_CHUNK_CACHE_BYTES,
+    max: MAX_CHUNK_CACHE_BYTES,
+    warn,
+  });
+}
+
+/** Same grammar for any byte-sized env knob (`TIER_HOT_BUDGET_BYTES`, ...). */
+export function parseByteSize(
+  raw: string | undefined,
+  options: {
+    name: string;
+    fallback: number;
+    min: number;
+    max: number;
+    warn?: (message: string) => void;
+  },
+): number {
+  const warn = options.warn ?? (() => undefined);
+  if (raw === undefined || raw.trim() === '') return options.fallback;
   const match = /^\s*(\d+)\s*([kKmM]?)\s*$/.exec(raw);
   if (!match) {
     warn(
-      `CHUNK_CACHE_BYTES=${JSON.stringify(raw)} is not a byte count — using the default ${DEFAULT_CHUNK_CACHE_BYTES}`,
+      `${options.name}=${JSON.stringify(raw)} is not a byte count — using the default ${options.fallback}`,
     );
-    return DEFAULT_CHUNK_CACHE_BYTES;
+    return options.fallback;
   }
   const unit = match[2]?.toLowerCase();
   const multiplier = unit === 'k' ? 1024 : unit === 'm' ? 1024 * 1024 : 1;
   const bytes = Number(match[1]) * multiplier;
-  if (bytes < MIN_CHUNK_CACHE_BYTES || bytes > MAX_CHUNK_CACHE_BYTES) {
+  if (bytes < options.min || bytes > options.max) {
     warn(
-      `CHUNK_CACHE_BYTES=${raw} is outside ${MIN_CHUNK_CACHE_BYTES}..${MAX_CHUNK_CACHE_BYTES} — using the default ${DEFAULT_CHUNK_CACHE_BYTES}`,
+      `${options.name}=${raw} is outside ${options.min}..${options.max} — using the default ${options.fallback}`,
     );
-    return DEFAULT_CHUNK_CACHE_BYTES;
+    return options.fallback;
   }
   return bytes;
 }

package/src/sqlite/chunk-layout.ts

@@ -0,0 +1,14 @@
+/**
+ * The storage grain shared by the DO VFS and the R2 page tier. Kept in its
+ * own module so `page-tier.ts` can import it without a cycle through
+ * `do-vfs.ts`.
+ */
+
+/** Bytes per SQLite page. Matches `PRAGMA page_size=4096`. */
+export const VFS_PAGE_SIZE = 4096;
+
+/** SQLite pages packed into one stored row (billing grain). */
+export const PAGES_PER_CHUNK = 16;
+
+/** Bytes per stored chunk row (64 KiB — well under the 2 MB DO value cap). */
+export const CHUNK_SIZE = VFS_PAGE_SIZE * PAGES_PER_CHUNK;