akanjs 3.0.0-alpha.0 → 3.0.0-alpha.2

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/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/document/database.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions } from "akanjs/service";
 import type { DataLoader } from "./dataLoader";
 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> {
@@ -105,6 +105,7 @@ 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>;
   __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/into.ts

@@ -85,14 +85,15 @@ export type Mdl<
     options?: DocumentUpdateOptions,
   ): Promise<UpdateResult>;
   updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
-  deleteMany(query: _RawQuery): Promise<UpdateResult>;
+  removeMany(query: _RawQuery): Promise<UpdateResult>;
   bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
 };
 
-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 +101,8 @@ type IntoModelActions<
   _CapitalizedRefName extends string,
   Doc,
   Raw,
+  
+  Insight,
   _Query,
   _Sort,
   _QueryOfDoc = QueryOf<Doc>,
@@ -121,13 +124,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 +141,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 +166,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.0",
+  "version": "3.0.0-alpha.2",
   "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/cachePolicy.ts

@@ -234,20 +234,62 @@ export function shouldInvalidateRouteCacheEntry(
   return false;
 }
 
-export class LruTtlCache<T> {
-  readonly #entries = new Map<string, { value: T; expiresAt: number }>();
+export interface LruTtlCacheOptions<T> {
+  /**
+   * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
+   * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
+   * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
+   */
+  sizeOf?: (value: T) => number;
+  /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
+  maxBytes?: number;
+  /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
+  maxEntryBytes?: number;
+  /**
+   * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
+   * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
+   * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
+   * the last request, with a 30s TTL. 0 disables it.
+   */
+  sweepIntervalMs?: number;
+}
 
-  constructor(readonly maxEntries = 100) {}
+export class LruTtlCache<T> {
+  readonly #entries = new Map<string, { value: T; expiresAt: number; byteLength: number }>();
+  #byteLength = 0;
+  #sweepTimer: ReturnType<typeof setInterval> | null = null;
+  readonly #sizeOf: (value: T) => number;
+  readonly #maxBytes: number;
+  readonly #maxEntryBytes: number;
+
+  constructor(
+    readonly maxEntries = 100,
+    options: LruTtlCacheOptions<T> = {},
+  ) {
+    this.#sizeOf = options.sizeOf ?? (() => 0);
+    this.#maxBytes = options.maxBytes ?? 0;
+    this.#maxEntryBytes = options.maxEntryBytes ?? 0;
+    const sweepIntervalMs = options.sweepIntervalMs ?? 0;
+    if (sweepIntervalMs > 0) {
+      this.#sweepTimer = setInterval(() => this.sweepExpired(), sweepIntervalMs);
+      
+      (this.#sweepTimer as { unref?: () => void }).unref?.();
+    }
+  }
 
   get size(): number {
     return this.#entries.size;
   }
 
+  get byteSize(): number {
+    return this.#byteLength;
+  }
+
   get(key: string): T | null {
     const entry = this.#entries.get(key);
     if (!entry) return null;
     if (entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
+      this.#remove(key);
       return null;
     }
     this.#entries.delete(key);
@@ -255,26 +297,56 @@ export class LruTtlCache<T> {
     return entry.value;
   }
 
-  set(key: string, value: T, ttlSeconds: number): void {
-    this.#entries.delete(key);
+  /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
+  set(key: string, value: T, ttlSeconds: number): boolean {
+    this.#remove(key);
+    const byteLength = LruTtlCache.#measure(this.#sizeOf, value);
+    if (this.#maxEntryBytes > 0 && byteLength > this.#maxEntryBytes) return false;
+    this.sweepExpired();
     const maxEntries = this.maxEntries > 0 ? this.maxEntries : 100;
     while (this.#entries.size >= maxEntries) {
-      const oldest = this.#entries.keys().next().value;
-      if (!oldest) break;
-      this.#entries.delete(oldest);
+      if (!this.#removeOldest()) break;
+    }
+    while (this.#maxBytes > 0 && this.#entries.size > 0 && this.#byteLength + byteLength > this.#maxBytes) {
+      if (!this.#removeOldest()) break;
     }
-    this.#entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+    this.#entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000, byteLength });
+    this.#byteLength += byteLength;
+    return true;
+  }
+
+  /**
+   * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
+   * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
+   * differ per entry, so expiry is not monotonic in map order and an early break would leave
+   * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
+   */
+  sweepExpired(now = Date.now()): number {
+    let removed = 0;
+    for (const [key, entry] of this.#entries) {
+      if (entry.expiresAt > now) continue;
+      this.#remove(key);
+      removed += 1;
+    }
+    return removed;
+  }
+
+  /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
+  dispose(): void {
+    if (!this.#sweepTimer) return;
+    clearInterval(this.#sweepTimer);
+    this.#sweepTimer = null;
   }
 
   delete(key: string): boolean {
-    return this.#entries.delete(key);
+    return this.#remove(key);
   }
 
   invalidate(predicate: (key: string, value: T) => boolean): number {
     let count = 0;
     for (const [key, entry] of this.#entries) {
       if (!predicate(key, entry.value)) continue;
-      this.#entries.delete(key);
+      this.#remove(key);
       count += 1;
     }
     return count;
@@ -282,5 +354,35 @@ export class LruTtlCache<T> {
 
   clear(): void {
     this.#entries.clear();
+    this.#byteLength = 0;
+  }
+
+  static parseByteCeiling(value: string | undefined | null, fallback = 0): number {
+    const parsed = Number.parseInt(value ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+  }
+
+  #remove(key: string): boolean {
+    const entry = this.#entries.get(key);
+    if (!entry) return false;
+    this.#entries.delete(key);
+    this.#byteLength -= entry.byteLength;
+    return true;
+  }
+
+  #removeOldest(): boolean {
+    const oldest = this.#entries.keys().next().value;
+    if (!oldest) return false;
+    return this.#remove(oldest);
+  }
+
+  /** A measurement must never fail a cache write, and a bad measurement must never skew the total. */
+  static #measure<T>(sizeOf: (value: T) => number, value: T): number {
+    try {
+      const measured = sizeOf(value);
+      return Number.isFinite(measured) && measured > 0 ? measured : 0;
+    } catch {
+      return 0;
+    }
   }
 }

package/server/di/diLifecycle.ts

@@ -21,7 +21,7 @@ import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
 import { createDefaultAkanOption } from "../akanOption";
 import type { WebProxyRegistration } from "../proxy";
-import { DatabaseResolver, ServiceResolver, SignalResolver } from "../resolver";
+import { CascadeRunner, DatabaseResolver, ServiceResolver, SignalResolver } from "../resolver";
 import type { SignalRoutes, WebsocketRoutes } from "../types";
 import { getPredefinedAdaptor, predefinedAdaptorRole } from "./predefinedAdaptor";
 import { collectAdaptors, resolveAdaptorHierarchy } from "./resolveAdaptorHierarchy";
@@ -63,6 +63,7 @@ export class DiLifecycle {
   readonly disabledModules = new Map<string, string>();
   readonly #predefinedAdaptor;
   readonly #predefinedAdaptorRole = predefinedAdaptorRole;
+  readonly #cascade = new CascadeRunner();
 
   /** Read-only view of the resolved module maps, for tooling that needs to describe the container. */
   get modules(): {
@@ -122,8 +123,9 @@ export class DiLifecycle {
       this.#service.set(refName, module as ServiceModule);
     });
     this.#database.forEach((mod) => {
-      const databaseAdaptor = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
-      this.#adaptor.set(databaseAdaptor.refName, databaseAdaptor);
+      const { adaptor, schema } = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
+      this.#adaptor.set(adaptor.refName, adaptor);
+      this.#cascade.register(mod.constant, schema, mod.service.srv);
     });
     const services = [
       ...[...this.#service.values()].map((mod) => mod.service.srv),
@@ -457,13 +459,7 @@ export class DiLifecycle {
             if (serviceCls.type === "database") {
               const databaseModule = this.#database.get(serviceCls.refName);
               if (!databaseModule) throw new Error(`Database "${serviceCls.refName}" is not registered`);
-              ServiceResolver.resolveDatabaseService(
-                databaseModule.constant,
-                databaseModule.database,
-                serviceCls,
-
-                (refName) => this.getService(refName),
-              );
+              ServiceResolver.resolveDatabaseService(databaseModule.database, serviceCls, this.#cascade);
             }
             const service = new serviceCls();
             await InjectInfo.resolveInjection(service, serviceCls, this.registry, this.#env);
@@ -476,6 +472,8 @@ export class DiLifecycle {
         })),
       );
     }
+
+    this.#cascade.seal((refName) => this.getService(refName));
   }
 
   async #initializeInternal() {

package/server/processMetricsCollector.ts

@@ -138,6 +138,10 @@ export class ProcessMetricsCollector {
       ...(metrics.jscHeapSizeBytes !== undefined
         ? [`jscHeap=${ProcessMetricsCollector.formatBytes(metrics.jscHeapSizeBytes)}`]
         : []),
+
+      ...(metrics.rscWorkerRssBytes !== undefined
+        ? [`rscWorkerRss=${ProcessMetricsCollector.formatBytes(metrics.rscWorkerRssBytes)}`]
+        : []),
       ...(metrics.eventLoopLagMeanMs !== undefined
         ? [`elLag=${metrics.eventLoopLagMeanMs}/${metrics.eventLoopLagP99Ms ?? 0}/${metrics.eventLoopLagMaxMs ?? 0}ms`]
         : []),