feat: persist partition catalogs in DO storage + expose in explain()

- PartitionCatalog.serialize()/deserialize() for durable storage persistence
- Catalogs saved to ctx.storage on build, restored on DO wake (ensureInitialized)
- Survives DO hibernation — no rebuild needed across requests
- ExplainResult.partitionCatalog shows column + partition value count
- At PB scale: catalog persists across millions of queries without rebuild cost

Author: teamchong

src/partition-catalog.ts

@@ -142,6 +142,23 @@ export class PartitionCatalog {
     }
   }
 
+  /** Serialize to a plain object for DO durable storage. */
+  serialize(): { column: string; index: Record<string, number[]>; allFragmentIds: number[] } {
+    const index: Record<string, number[]> = {};
+    for (const [key, ids] of this.index) index[key] = ids;
+    return { column: this.column, index, allFragmentIds: this.allFragmentIds };
+  }
+
+  /** Restore from serialized form. */
+  static deserialize(data: { column: string; index: Record<string, number[]>; allFragmentIds: number[] }): PartitionCatalog {
+    const catalog = new PartitionCatalog(data.column);
+    for (const [key, ids] of Object.entries(data.index)) {
+      catalog.index.set(key, ids);
+    }
+    catalog.allFragmentIds = data.allFragmentIds;
+    return catalog;
+  }
+
   /** Stats for diagnostics. */
   stats(): { column: string; partitionValues: number; fragments: number; indexSizeBytes: number } {
     let indexSizeBytes = 0;

src/query-do.ts

@@ -484,6 +484,7 @@ export class QueryDO extends DurableObject<Env> {
     if (partitionBy) {
       const catalog = PartitionCatalog.fromFragments(partitionBy, fragmentMetas);
       this.partitionCatalogs.set(tableName, catalog);
+      this.ctx.storage.put(`pcatalog:${tableName}`, catalog.serialize());
       this.log("info", "partition_catalog_built", { ...catalog.stats(), source: "explicit" });
       return;
     }
@@ -516,6 +517,7 @@ export class QueryDO extends DurableObject<Env> {
     if (bestColumn) {
       const catalog = PartitionCatalog.fromFragments(bestColumn, fragmentMetas);
       this.partitionCatalogs.set(tableName, catalog);
+      this.ctx.storage.put(`pcatalog:${tableName}`, catalog.serialize());
       this.log("info", "partition_catalog_built", catalog.stats());
     }
   }
@@ -540,6 +542,13 @@ export class QueryDO extends DurableObject<Env> {
     const stored = await this.ctx.storage.list<TableMeta>({ prefix: "table:" });
     for (const [key, meta] of stored) this.footerCache.set(key.replace("table:", ""), meta);
 
+    // Restore persisted partition catalogs
+    const catalogs = await this.ctx.storage.list<ReturnType<PartitionCatalog["serialize"]>>({ prefix: "pcatalog:" });
+    for (const [key, data] of catalogs) {
+      const tableName = key.replace("pcatalog:", "");
+      this.partitionCatalogs.set(tableName, PartitionCatalog.deserialize(data));
+    }
+
     this.wasmEngine = await instantiateWasm(wasmModule);
 
     // Register with Master for invalidation broadcasts
@@ -773,6 +782,9 @@ export class QueryDO extends DurableObject<Env> {
       estimatedRows: meta.totalRows,
       fragments: totalFragments,
       fragmentsSkipped,
+      partitionCatalog: this.partitionCatalogs.has(query.table)
+        ? { column: this.partitionCatalogs.get(query.table)!.column, partitionValues: this.partitionCatalogs.get(query.table)!.stats().partitionValues }
+        : undefined,
       filters: [
         ...query.filters.map(f => ({
           column: f.column,

src/types.ts

@@ -309,6 +309,8 @@ export interface ExplainResult {
   fragments: number;
   /** Fragments skipped by fragment-level min/max pruning */
   fragmentsSkipped?: number;
+  /** Partition catalog info (present when catalog exists for this table) */
+  partitionCatalog?: { column: string; partitionValues: number };
   filters: { column: string; op: string; pushable: boolean }[];
   metaCached: boolean;
   /** Estimated number of rows after filter pushdown */