akanjs 3.0.0-alpha.4 → 3.0.0-alpha.6

package/base/symbols.ts

@@ -3,6 +3,7 @@ export const SLICE_META = Symbol.for("akan.slice");
 export const FILTER_META = Symbol.for("akan.filter");
 export const LOADER_META = Symbol.for("akan.loader");
 export const INJECT_META = Symbol.for("akan.inject");
+export const LIBS_REMOVE_HOOK = Symbol.for("akan.service.libsRemoveHook");
 export const ENDPOINT_META = Symbol.for("akan.endpoint");
 export const ENDPOINT_DICT_SHAPE: unique symbol = Symbol.for("akan.endpoint.dictShape") as never;
 export const SLICE_DICT_SHAPE: unique symbol = Symbol.for("akan.slice.dictShape") as never;

package/common/Logger.ts

@@ -60,6 +60,10 @@ export class Logger {
   static isVerbose() {
     return Logger.#levelIdx <= 1;
   }
+  /** For hot-path callers that would otherwise build a message the level is about to discard. */
+  static shouldLog(logLevel: LogLevel) {
+    return Logger.#shouldLog(logLevel);
+  }
 
   name?: string;
   constructor(name?: string) {

package/constant/cascadePaths.ts

@@ -1,32 +1,103 @@
+import { type Cls, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
 import type { ConstantField, FieldObject } from "./fieldInfo";
 import type { ConstantModelRef } from "./via";
 
-/** What happens to the documents a relation field points at when the owner is removed. */
-export const cascadeActions = ["remove"] as const;
+/**
+ * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
+ * document is removed; `removeWith` removes this document when what the field points at is removed. The two
+ * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
+ */
+export const cascadeActions = ["removeRef", "removeWith"] as const;
 export type CascadeAction = (typeof cascadeActions)[number];
 
+/** How a `removeWith` field names the owner whose removal takes this document with it. */
+export interface CascadeWithPath {
+  readonly key: string;
+  /** Set when the field is a relation. Resolved to a refName later: the owner may not be registered yet. */
+  readonly modelRef: ConstantModelRef | null;
+  /** Set when the field declares `ref`, which names the owner at declaration. */
+  readonly refName: string | null;
+  /** Set when the field declares `refPath`: the sibling field holding the owner's refName. */
+  readonly typeKey: string | null;
+  /** The refNames `typeKey` may hold. Empty unless the field is polymorphic. */
+  readonly typeValues: readonly string[];
+}
+
+const idNames = new Set(["ID", "String"]);
+
 export class CascadePaths {
-  /** Field key → the model its ids point at. Resolved to a refName later: the target may not be registered yet. */
-  readonly remove = new Map<string, ConstantModelRef>();
+  /** Field key → the model its ids point at, removed when this document is. */
+  readonly removeRef = new Map<string, ConstantModelRef>();
+  /** Field key → the owner whose removal removes this document. */
+  readonly removeWith = new Map<string, CascadeWithPath>();
 
   collect(fieldMap: FieldObject) {
     for (const [key, field] of Object.entries(fieldMap)) {
       if (!field.cascade) continue;
-      this.#assertCascadable(key, field.cascade, field);
-      this.remove.set(key, field.modelRef);
+      this.#assertKnownAction(key, field.cascade);
+      if (field.cascade === "removeRef") this.removeRef.set(key, this.#readOwnedRelation(key, field));
+      else this.removeWith.set(key, this.#readOwnerPath(key, field, fieldMap));
     }
     return this;
   }
 
-  #assertCascadable(key: string, action: CascadeAction, field: ConstantField) {
-    
+  #assertKnownAction(key: string, action: CascadeAction) {
+
     if (!cascadeActions.includes(action)) {
       throw new Error(`Cascade field "${key}" declares cascade: "${action}", which is not one of ${cascadeActions}`);
     }
+  }
+
+  #readOwnedRelation(key: string, field: ConstantField) {
     
     if (!field.isClass || field.isScalar) {
       throw new Error(`Cascade field "${key}" is not a model reference and has no document to remove`);
     }
     if (field.arrDepth > 1) throw new Error(`Cascade field "${key}" is a nested array and cannot cascade`);
+    return field.modelRef;
+  }
+
+  #readOwnerPath(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+
+    if (field.arrDepth > 0) throw new Error(`Cascade field "${key}" is an array and names more than one owner`);
+    if (field.isMap) throw new Error(`Cascade field "${key}" is a Map and names no owner`);
+    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap);
+    if (field.ref) {
+      this.#assertHoldsId(key, field);
+      return { key, modelRef: null, refName: field.ref, typeKey: null, typeValues: [] };
+    }
+    if (field.isClass && !field.isScalar) {
+      return { key, modelRef: field.modelRef, refName: null, typeKey: null, typeValues: [] };
+    }
+    throw new Error(
+      `Cascade field "${key}" declares cascade: "removeWith" but names no owner; make it a model reference, ` +
+        `or add ref: "<model>" / refPath: "<typeField>"`,
+    );
+  }
+
+  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+    if (field.ref) throw new Error(`Cascade field "${key}" declares both ref and refPath; keep one`);
+    this.#assertHoldsId(key, field);
+    const typeKey = field.refPath as string;
+    const typeField = fieldMap[typeKey];
+    if (!typeField) throw new Error(`Cascade field "${key}" declares refPath: "${typeKey}", which is not a field`);
+
+    if (!typeField.enum) {
+      throw new Error(
+        `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
+          `refNames it may hold`,
+      );
+    }
+    const typeValues = typeField.enum.values.map((value) => String(value));
+    return { key, modelRef: null, refName: null, typeKey, typeValues };
+  }
+
+  #assertHoldsId(key: string, field: ConstantField) {
+    const modelRef = field.modelRef as unknown as Cls;
+    const refName = PrimitiveRegistry.has(modelRef)
+      ? PrimitiveRegistry.getName(modelRef as unknown as typeof PrimitiveScalar)
+      : null;
+    if (refName && idNames.has(refName)) return;
+    throw new Error(`Cascade field "${key}" declares ref or refPath and must hold an ID`);
   }
 }

package/constant/fieldInfo.ts

@@ -450,7 +450,13 @@ export class ConstantField<
   get isMap() {
     return (this.modelRef as Cls) === Map;
   }
+
+  #props: FieldProps | null = null;
   getProps(): FieldProps {
+    this.#props ??= Object.freeze(this.#buildProps());
+    return this.#props;
+  }
+  #buildProps(): FieldProps {
     return {
       nullable: this.nullable as unknown as boolean,
       ref: this.ref,

package/constant/getDefault.ts

@@ -2,17 +2,45 @@ import { DEFAULT_VALUE, FIELD_META, type PrimitiveScalar } from "akanjs/base";
 import type { FieldObject } from ".";
 import type { DefaultOf } from "./types";
 
+interface DefaultPlan {
+  /** Fields whose default is a value that can be shared: a primitive, `null`, or the field's own literal. */
+  shared: Record<string, unknown>;
+  /** Fields that have to be produced per call — a thunk, a fresh array, or a nested scalar record. */
+  perCall: [key: string, make: () => unknown][];
+}
+
+const planCache = new WeakMap<FieldObject, DefaultPlan>();
+
+/**
+ * The split is what keeps this faithful: `default: () => dayjs()` still means "now" on every call, and an array
+ * or nested-scalar default is still a fresh object, so two documents filled from the same model never end up
+ * sharing one. Only values that were already shared before this cache existed live in `shared`.
+ */
 export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
-  const result: Record<string, unknown> = {};
+  let plan = planCache.get(fieldObj);
+  if (!plan) {
+    plan = buildPlan(fieldObj);
+    planCache.set(fieldObj, plan);
+  }
+  const result: Record<string, unknown> = { ...plan.shared };
+  for (const [key, make] of plan.perCall) result[key] = make();
+  return result as DefaultOf<T>;
+};
+
+const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
+  const shared: Record<string, unknown> = {};
+  const perCall: [string, () => unknown][] = [];
   for (const [key, field] of Object.entries(fieldObj)) {
-    if (field.fieldType === "hidden" || field.fieldType === "secret") result[key] = null;
+    if (field.fieldType === "hidden" || field.fieldType === "secret") shared[key] = null;
     else if (field.default !== undefined && field.default !== null) {
-      if (typeof field.default === "function") result[key] = (field.default as () => object)();
-      else result[key] = field.default as object;
-    } else if (field.isArray) result[key] = [];
-    else if (field.nullable) result[key] = null;
-    else if (field.isClass) result[key] = field.isScalar ? getDefault(field.modelRef[FIELD_META]) : null;
-    else result[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+      if (typeof field.default === "function") perCall.push([key, field.default as () => unknown]);
+      else shared[key] = field.default as object;
+    } else if (field.isArray) perCall.push([key, () => []]);
+    else if (field.nullable) shared[key] = null;
+    else if (field.isClass) {
+      if (field.isScalar) perCall.push([key, () => getDefault(field.modelRef[FIELD_META])]);
+      else shared[key] = null;
+    } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
   }
-  return result as DefaultOf<T>;
+  return { shared, perCall };
 };

package/document/database.ts

@@ -3,8 +3,9 @@ import { Logger } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions } from "akanjs/service";
 import type { DataLoader } from "./dataLoader";
+import type { DocumentUpdateInput } from "./documentQuery";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta";
-import type { CRUDEventType, Mdl, SaveEventType } from "./into";
+import type { CRUDEventType, Mdl, SaveEventType, UpdateResult } from "./into";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types";
 
 export class CacheDatabase<T = unknown> {
@@ -25,6 +26,15 @@ export class CacheDatabase<T = unknown> {
     await this.cache.delete(this.refName, `${topic}:${key}`);
   }
 }
+/**
+ * What `update<Filter>` returns. The patch cannot be a trailing parameter — a filter's own args may be optional,
+ * and no tuple type puts a required element after those — and leading it reads backwards. So it lands here, on a
+ * terminal `.set()` that mirrors the `UPDATE … SET …` it compiles to.
+ */
+export interface UpdateChain<Doc = any> {
+  set(update: DocumentUpdateInput<Doc>): Promise<UpdateResult>;
+}
+
 type QueryMethodOfKey<
   CapitalizedK extends string,
   Doc,
@@ -53,6 +63,14 @@ type QueryMethodOfKey<
   [K in `insight${CapitalizedK}`]: (...args: _Args) => Promise<Insight>;
 } & {
   [K in `query${CapitalizedK}`]: (...args: _Args) => _QueryOfDoc;
+} & {
+  [K in `remove${CapitalizedK}`]: (...args: _Args) => Promise<UpdateResult>;
+} & {
+  [K in `removeOne${CapitalizedK}`]: (...args: _Args) => Promise<UpdateResult>;
+} & {
+  [K in `update${CapitalizedK}`]: (...args: _Args) => UpdateChain<Doc>;
+} & {
+  [K in `updateOne${CapitalizedK}`]: (...args: _Args) => UpdateChain<Doc>;
 };
 type QueryMethodMap<Query, Doc, Insight, _FindQueryOption, _ListQueryOption, _QueryOfDoc> = {
   [K in keyof Query]: K extends string
@@ -105,6 +123,10 @@ type DatabaseModelWithQuerySort<
   __create: (data: _DataInput) => Promise<Doc>;
   __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
   __remove: (id: string) => Promise<Doc>;
+  __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
+  __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
+  __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+  __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
   __list(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/document/databaseRegistry.ts

@@ -19,7 +19,7 @@ export interface DatabaseModel<
   model: ModelCls<Model>;
   filter: FilterCls<Filter>;
   obj: ConstantCls<Obj>;
-  insight: ConstantCls<Insight>;
+  insight: DatabaseCls<Insight>;
   _Input: Input;
   _Doc: Doc;
   _Model: Model;
@@ -92,7 +92,7 @@ export class DatabaseRegistry {
     doc: DatabaseCls<Doc>,
     model: ModelCls<Model>,
     obj: ConstantCls<Obj>,
-    insight: ConstantCls<Insight>,
+    insight: DatabaseCls<Insight>,
     filter: FilterCls<Filter>,
   ): DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter, _Query, _Sort> {
     const dbInfo = {

package/document/filterMeta.ts

@@ -98,6 +98,13 @@ export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) =
   return [...args, ...Array(filterInfo.args.length - args.length).fill(undefined)];
 };
 
+export const assertFilterFitsCrud = (refName: string, queryKey: string, className: string) => {
+  if (queryKey.toLowerCase() !== refName.toLowerCase()) return;
+  throw new Error(
+    `Filter "${queryKey}" on "${refName}" generates remove${className}/update${className}, which are the generated CRUD methods; rename the filter`,
+  );
+};
+
 export type BaseFilterSortKey = "latest" | "oldest" | "relevance";
 export type BaseFilterQueryKey = "any";
 export type BaseFilterKey = BaseFilterSortKey | BaseFilterQueryKey;

package/document/into.ts

@@ -77,22 +77,27 @@ export type Mdl<
   find(query: _RawQuery, projection?: _Projection): FindManyChain<Doc>;
   findOne(query: _RawQuery, projection?: _Projection): FindOneChain<Doc>;
   findById(id: string | undefined, projection?: _Projection): Promise<Doc | null>;
-  countDocuments(query: _RawQuery): Promise<number>;
+  count(query: _RawQuery): Promise<number>;
   exists(query: _RawQuery): Promise<string | null>;
+
   updateOne(
     query: _RawQuery,
     update: DocumentUpdateInput<_RawDoc>,
     options?: DocumentUpdateOptions,
   ): Promise<UpdateResult>;
   updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
-  deleteMany(query: _RawQuery): Promise<UpdateResult>;
+  removeOne(query: _RawQuery): Promise<UpdateResult>;
+  removeMany(query: _RawQuery): Promise<UpdateResult>;
   bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
+  /** @deprecated Renamed to `count`. */
+  countDocuments(query: _RawQuery): Promise<number>;
 };
 
-interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw> {
+interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw, Insight> {
   refName: T;
   _CapitalizedRefName: _CapitalizedRefName;
   _Full: Raw;
+  _Insight: Insight;
 }
 type NoInferType<T> = [T][T extends unknown ? 0 : never];
 type IntoModelActions<
@@ -100,6 +105,8 @@ type IntoModelActions<
   _CapitalizedRefName extends string,
   Doc,
   Raw,
+  
+  Insight,
   _Query,
   _Sort,
   _QueryOfDoc = QueryOf<Doc>,
@@ -121,13 +128,14 @@ type IntoModelActions<
   [K in `update${_CapitalizedRefName}`]: (id: string, data: Partial<Doc>) => Promise<Doc>;
 } & {
   [K in `remove${_CapitalizedRefName}`]: (id: string) => Promise<Doc>;
-} & QueryMethodPart<_Query, _Sort, Raw, Doc, unknown, unknown, unknown, _QueryOfDoc>;
+} & QueryMethodPart<_Query, _Sort, Raw, Doc, DocumentModel<Insight>, unknown, unknown, _QueryOfDoc>;
 
 export const into = <
   Doc,
   FilterRef extends FilterCls,
   T extends string,
   Raw,
+  Insight,
   AddDbModels extends ModelCls[],
   _CapitalizedRefName extends string,
   _QueryOfDoc = QueryOf<Doc>,
@@ -137,11 +145,11 @@ export const into = <
 >(
   docRef: Cls<Doc>,
   filterRef: FilterRef,
-  cnst: IntoConstantModel<T, _CapitalizedRefName, Raw>,
+  cnst: IntoConstantModel<T, _CapitalizedRefName, Raw, Insight>,
   loaderBuilder: _LoaderBuilder,
   ...addMdls: [...AddDbModels]
 ): ModelCls<
-  IntoModelActions<T, _CapitalizedRefName, Doc, Raw, _Query, _Sort, _QueryOfDoc>,
+  IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
   ReturnType<_LoaderBuilder>
 > => {
   const loaderInfoMap = loaderBuilder(makeLoaderBuilder<Doc>());
@@ -162,7 +170,7 @@ export const into = <
     });
   });
   return DefaultModel as unknown as ModelCls<
-    IntoModelActions<T, _CapitalizedRefName, Doc, Raw, _Query, _Sort, _QueryOfDoc>,
+    IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
     ReturnType<_LoaderBuilder>
   >;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -23,14 +23,31 @@ Read snapshots from:
 curl http://localhost:8080/_akan/app/metrics
 ```
 
+A replica and its RSC worker are separate processes and are reported separately. **`rssBytes` is the
+replica's own; the worker's is `rscWorkerRssBytes`.** Sum them for what the pod pays.
+
 Key fields:
 
-- `rssBytes`, `heapUsedBytes`, `jscHeapSizeBytes`: distinguish RSS-only native retention from JS heap retention.
+- `rssBytes`, `heapUsedBytes`, `jscHeapSizeBytes`: the replica. Distinguish RSS-only native retention from JS
+  heap retention.
+- `rscWorkerRssBytes`, `rscWorkerHeapUsedBytes`, `rscWorkerJscHeapSizeBytes`, `rscWorkerJscExtraMemorySizeBytes`:
+  the same for the worker. `jscExtra` is off-heap, mostly typed-array backing stores.
 - `rscRenderCount`, `rscInFlightRenderCount`: detect request lifecycle leaks.
 - `rscLoadedRouteModuleCount`, `rscRouteModuleCacheHits`, `rscRouteModuleCacheMisses`: detect route module warm-up.
-- `ssrChunkRegistrySize`, `ssrChunkLoadCount`: detect full-document SSR client chunk retention.
+- `ssrChunkRegistrySize`, `ssrChunkLoadCount`: full-document SSR client chunk loading. **`…RegistrySize` counts
+  keys, not bytes** — evicting does not unload the module, so it can never fall on its own.
+- `httpHtmlCacheEntries` / `httpHtmlCacheBytes`, `rscResultCacheEntries` / `rscResultCacheBytes`,
+  `rscPatchResultCacheEntries` / `rscPatchResultCacheBytes`: what each cache actually holds. Entry count alone
+  says nothing when entries span three orders of magnitude.
 - `httpFullSsrCount`, `httpRscNavigationCount`, `httpStaticAssetCount`, `httpImageCount`: separate request kinds.
 
+Two things measured on `apps/akan` that shape how to read all of the above:
+
+- **Growth converges; it is not a leak.** Ten passes over the same routes plateau by roughly the sixth, with a
+  flat JS heap throughout. Three passes is not enough to tell a plateau from a ratchet.
+- **Freeing JS objects does not lower RSS.** Emptying both result caches returns their bytes to the heap and
+  leaves RSS unchanged. Only not allocating, or restarting the process, reduces what the pod pays.
+
 ## Scenarios
 
 ### Same Route Repeated

package/server/akanApp.ts

@@ -7,6 +7,7 @@ import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport,
 import { isTraceEnabled } from "akanjs/signal";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
+import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -808,41 +809,17 @@ export class AkanApp {
     const headers = new Headers({ "Content-Type": options.contentType });
     if (options.cacheControl) headers.set("Cache-Control", options.cacheControl);
 
-    const gzipPath = `${filePath}.gz`;
-    if (this.#acceptsGzip(req) && this.#isCompressible(options.contentType)) {
-      const gzipFile = Bun.file(gzipPath);
-      if (await gzipFile.exists()) {
-        const gzipBytes = await gzipFile.bytes();
-        headers.set("Content-Encoding", "gzip");
-        headers.set("Content-Length", String(gzipBytes.byteLength));
-        headers.set("Vary", "Accept-Encoding");
-        return new Response(this.#toArrayBuffer(gzipBytes), { headers });
-      }
+    const sidecar = await resolveEncodedSidecar(req, filePath, options.contentType);
+    if (sidecar) {
+      headers.set("Content-Encoding", sidecar.encoding);
+      headers.set("Content-Length", String(sidecar.bytes.byteLength));
+      headers.set("Vary", "Accept-Encoding");
+      return new Response(sidecar.bytes, { headers });
     }
 
     return new Response(Bun.file(filePath).stream(), { headers });
   }
 
-  #acceptsGzip(req: Request): boolean {
-    const acceptEncoding = req.headers.get("accept-encoding") ?? "";
-    return /\bgzip\b/.test(acceptEncoding);
-  }
-
-  #isCompressible(contentType: string): boolean {
-    const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-    return (
-      type.startsWith("text/") ||
-      type === "application/javascript" ||
-      type === "application/json" ||
-      type === "application/manifest+json" ||
-      type === "image/svg+xml"
-    );
-  }
-
-  #toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-  }
-
   #safeResolve(baseDir: string, urlPath: string): string | null {
     let decoded: string;
     try {

package/server/artifact/routeClientCache.ts

@@ -48,12 +48,22 @@ export class RouteClientCache {
   };
   readonly #buildRoute: RouteBuildFn;
   readonly #onMerge?: OnMergeFn;
+  #revision = 0;
 
   constructor({ buildRoute, onMerge }: RouteClientCacheOptions) {
     this.#buildRoute = buildRoute;
     this.#onMerge = onMerge;
   }
 
+  /**
+   * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
+   * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
+   * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
+   */
+  get revision(): number {
+    return this.#revision;
+  }
+
   #getEmptyDelta(): BuildRouteClientResult {
     return {
       manifestDelta: {},
@@ -75,6 +85,7 @@ export class RouteClientCache {
     Object.assign(this.merged.ssrManifest.moduleMap, manifest.ssrManifest.moduleMap);
     for (const abs of manifest.knownEntries) this.merged.knownEntries.add(abs);
     for (const routeId of manifest.routeIds) this.#built.set(routeId, this.#getEmptyDelta());
+    this.#revision += 1;
   }
 
   async ensure(routeId: string, seeds: string[]): Promise<MergedManifest> {
@@ -125,6 +136,7 @@ export class RouteClientCache {
     for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap))
       this.merged.ssrManifest.moduleMap[url] = byName;
     for (const entry of delta.newEntries) this.merged.knownEntries.add(entry);
+    this.#revision += 1;
     this.#built.set(routeId, delta);
     this.#logger.verbose(
       `[route-cache] build done routeId=${routeId} generation=${generation} entries=+${delta.newEntries.length} deps=${delta.clientDeps.length} in ${Date.now() - started}ms`,
@@ -176,6 +188,7 @@ export class RouteClientCache {
     }
     const nextGeneration = this.merged.generation + 1;
     this.merged = this.#getEmptyMerged(nextGeneration);
+    this.#revision += 1;
     this.#building.clear();
     this.#logger.verbose(`[route-cache] cleared generation=${nextGeneration} dropped=${dropped.length}`);
     return dropped;
@@ -209,6 +222,7 @@ export class RouteClientCache {
       ),
     };
     this.merged = next;
+    this.#revision += 1;
   }
 
   static #normalizePath(filePath: string): string {

package/server/assetEncoding.ts

@@ -0,0 +1,47 @@
+const COMPRESSIBLE_TYPES = new Set([
+  "application/javascript",
+  "application/json",
+  "application/manifest+json",
+  "image/svg+xml",
+]);
+
+/**
+ * br is tried first: it is ~15% smaller than gzip across the artifact and ~22% on the CSS bundle.
+ * The gzip sidecar stays the fallback because browsers only advertise `br` on secure origins, so a
+ * plain-http dev server or an intermediary that rewrites Accept-Encoding still gets a compressed body.
+ */
+const SIDECAR_ENCODINGS = [
+  { encoding: "br", ext: ".br", accept: /(?:^|,)\s*(?:br|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
+  { encoding: "gzip", ext: ".gz", accept: /(?:^|,)\s*(?:gzip|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
+] as const;
+
+export interface EncodedSidecar {
+  bytes: ArrayBuffer;
+  encoding: string;
+}
+
+export const isCompressibleContentType = (contentType: string): boolean => {
+  const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return type.startsWith("text/") || COMPRESSIBLE_TYPES.has(type);
+};
+
+/** Picks the best precompressed sidecar the caller accepts, or null to serve the file as-is. */
+export const resolveEncodedSidecar = async (
+  req: Request,
+  filePath: string,
+  contentType: string,
+): Promise<EncodedSidecar | null> => {
+  if (!isCompressibleContentType(contentType)) return null;
+  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
+  for (const { encoding, ext, accept } of SIDECAR_ENCODINGS) {
+    const match = accept.exec(acceptEncoding);
+    
+    if (!match || (match[1] !== undefined && Number.parseFloat(match[1]) <= 0)) continue;
+    const file = Bun.file(`${filePath}${ext}`);
+    if (!(await file.exists())) continue;
+    const bytes = await file.bytes();
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+    return { bytes: buffer, encoding };
+  }
+  return null;
+};