bazis 0.98.32 → 0.98.34

package/cli/templates/module.ts

@@ -56,9 +56,7 @@ export function buildModuleTemplates(
 }
 
 function moduleFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
-  const cacheImport = profile === "full" ? "import { cachedScoped } from \"bazis/core/cache\";\n" : "";
   const moduleImport = "import { Module, scoped } from \"bazis/core/di\";";
-  const providerFactory = profile === "full" ? "cachedScoped" : "scoped";
   const backgroundImport = profile === "full" ? `import { ${n.module}Reporter } from "./background/${n.module}.reporter";\n` : "";
   const aiImports = profile === "full"
     ? `import { ${n.module}AnalystAgent } from "./ai/agents/${n.module}Analyst.agent";
@@ -72,7 +70,7 @@ import { ${n.module}SummaryTool } from "./ai/tools/${n.module}Summary.tool";
 `
     : "";
 
-  return `${cacheImport}${moduleImport}
+  return `${moduleImport}
 ${aiImports}${backgroundImport}import { ${n.module}Controller } from "./http/${n.module}.controller";
 import { ${n.entity} } from "./model/${n.module}.model";
 import { ${n.module}DbContext } from "./model/${n.module}.dbContext";
@@ -86,7 +84,7 @@ import { ${n.module}Service } from "./services/${n.module}.service";
   },
   controllers: [${n.module}Controller],
   providers: [
-    ${providerFactory}(I${n.module}Service, ${n.module}Service),
+    scoped(I${n.module}Service, ${n.module}Service),
   ],
 ${backgroundLine}${aiLines}  exports: [I${n.module}Service],
 })

package/cli/templates/passport.ts

@@ -78,7 +78,7 @@ exports: [I${m}Service]. TypeScript contract: services/I${e}.service.ts;
 HTTP access is defined by the controller and the host policy, separately from DI exports.
 I${m}Service → ${m}Service, scoped lifetime. The context and DbSet belong to the ORM.
 ${profile === "full" ? `${m}SummaryTool is listed in tools: [${m}SummaryTool]; the framework registers it as scoped, the tool is not exported.
-The service uses cachedScoped; ICache comes from the host cacheModule.
+The service is scoped; its keyed @Cacheable works when the host installs the cache (runApp cache: memory()).
 The background service gets its own scope per tick and disposes it in finally.
 The host also provides auth from src/app/modules/auth (TokenKind.Admin/Client),
 AgentRuntime and the reasoning modelProfile. The CLI does not create them.

package/core/background/BackgroundService.ts

@@ -1,4 +1,4 @@
-import type { HostedService, HostedServiceDiagnostics } from "../di";
+import type { HostedService, HostedServiceDiagnostics, HostedServiceHealth } from "../di";
 import { backgroundOptionsOf } from "./decorator";
 import { delay } from "./delay";
 import { redactSensitive } from "../../library/redaction";
@@ -56,6 +56,8 @@ export abstract class BackgroundService implements HostedService {
 
   /** The application logger, passed by the kernel; console until then. */
   private diagnostics?: HostedServiceDiagnostics;
+  /** Set when the service stopped for good after a crash: `/health` reports it. */
+  private terminated?: string;
 
   public constructor(options?: BackgroundServiceOptions) {
     // Explicit `super(...)` options win over `@Background({...})` metadata.
@@ -68,6 +70,15 @@ export abstract class BackgroundService implements HostedService {
   /** The background workload. Must observe `signal` for cooperative shutdown. */
   protected abstract execute(signal: AbortSignal): void | Promise<void>;
 
+  /**
+   * Unhealthy once the service stopped for good: it crashed without a restart
+   * policy, or used up its restarts. A pause before a restart, a tick failure
+   * of a periodic service and a normal end of `execute` stay healthy.
+   */
+  public checkHealth(): HostedServiceHealth {
+    return this.terminated === undefined ? { healthy: true } : { healthy: false, details: this.terminated };
+  }
+
   public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
     this.diagnostics = diagnostics;
   }
@@ -119,9 +130,11 @@ export abstract class BackgroundService implements HostedService {
         this.reportError(error, restarts);
         if (restarts >= maxRestarts) {
           // Without this line the service would just go quiet.
-          report(this.diagnostics, "error", this.constructor.name, maxRestarts === 0
+          const stopped = maxRestarts === 0
             ? "stopped after a crash and will not run again (no restart policy)"
-            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`, { restarts });
+            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`;
+          report(this.diagnostics, "error", this.constructor.name, stopped, { restarts });
+          this.terminated = `${stopped}: ${error instanceof Error ? error.message : String(error)}`;
           return;
         }
         restarts += 1;

package/core/background/decorator.ts

@@ -26,7 +26,8 @@ interface BackgroundMetadataCarrier {
  * ```
  *
  * Options passed explicitly to `super(...)` take precedence over the decorator.
- * Registration stays explicit — list the class in `backgroundModule({ services })`.
+ * Registration stays explicit — list the class in `background` of its module:
+ * `@Module({ background: [Heartbeat] })`.
  */
 export function Background(options: BackgroundDecoratorOptions = {}) {
   return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {

package/core/background/index.ts

@@ -10,6 +10,5 @@ export {
   type BackgroundServiceOptions,
   type PeriodicBackgroundServiceOptions,
 } from "./BackgroundService";
-export { backgroundModule, type BackgroundModuleConfig } from "./backgroundModule";
 export { Background, backgroundOptionsOf, type BackgroundDecoratorOptions } from "./decorator";
 export { delay } from "./delay";

package/core/cache/COMPATIBILITY.md

@@ -1,12 +1,12 @@
 # Cache Compatibility
 
-The aliases below were removed in 0.96.1, before the first `bazis` npm release,
-so no published version ever contained them. Use the replacement.
+The names below were removed; use the replacement. The `cached*` helpers were
+public until 0.98.34, the others were removed in 0.96.1 before the first npm release.
 
 | Removed name | Kind | Replacement |
 | --- | --- | --- |
-| `autoCachedScoped` | public alias | `cachedScoped` |
-| `autoCachedSingleton` | public alias | `cachedSingleton` |
+| `autoCachedScoped`, `cachedScoped` | public helpers, removed in 0.98.34 | `scoped(...)`: the cache hook wraps it |
+| `autoCachedSingleton`, `cachedSingleton` | public helpers, removed in 0.98.34 | `singleton(...)` |
 | `warnInsecureOutputCacheRoute` | public alias | `guardInsecureOutputCacheRoute` |
 | `warnOnAuthorizedRoutesWithoutVaryByUser` | config switch | `insecureAuthorizedRouteBehavior` (`false` was `"ignore"`) |
 | `DEFAULT_CACHEABLE_METHODS` | internal alias | `DEFAULT_OUTPUT_CACHE_METHODS` |

package/core/cache/README.md

@@ -79,5 +79,5 @@ The `@/core/cache` core does not import Redis at all, only the
 
 ## Compatibility
 
-DI helpers are `cachedScoped` and `cachedSingleton`. Former aliases were
-removed before the first npm release; see [COMPATIBILITY.md](./COMPATIBILITY.md).
+Cached services are registered with the regular `scoped` / `singleton`; the cache
+hook wraps them. Removed names are listed in [COMPATIBILITY.md](./COMPATIBILITY.md).

package/core/cache/SPEC.md

@@ -19,7 +19,7 @@ Quick navigation:
 - [7. `@OutputRedisCache` — HTTP output cache (distributed)](#7-outputrediscache--http-output-cache-distributed)
 - [8. `@Cacheable`: service method cache (memory)](#8-cacheable-service-method-cache-memory)
 - [9. `@CacheableRedis`: service method cache (distributed)](#9-cacheableredis-service-method-cache-distributed)
-- [10. DI providers: `cachedSingleton` / `cachedScoped` (+ auto-hook)](#10-di-providers-cachedsingleton--cachedscoped--auto-hook)
+- [10. DI registration: `singleton` / `scoped` with the cache hook](#10-di-registration-singleton--scoped-with-the-cache-hook)
 - [11. `ICache`: programmatic API](#11-icache-programmatic-api)
 - [12. Output cache key building](#12-output-cache-key-building)
 - [13. Anti-stampede and concurrent miss](#13-anti-stampede-and-concurrent-miss)
@@ -68,7 +68,6 @@ import {
   OutputRedisCache,
   Cacheable,
   CacheableRedis,
-  cachedScoped,
   ICache,
 } from "@/core/cache";
 import { composeRouteMiddlewareComposers } from "@/core/http";
@@ -116,8 +115,8 @@ import { redisConnect } from "@/core/infra";
 | --- | --- | --- | --- |
 | `@OutputCache` | controller action | `ICache` in-memory | the cache module's `ROUTE_MIDDLEWARE_COMPOSER` registration (automatic) |
 | `@OutputRedisCache` | controller action | `IDistributedCache` | the same + `redisConnect(config, { cache: "distributed" })` in Infra |
-| `@Cacheable` | service method | `ICache` in-memory | `cachedSingleton` / `cachedScoped` (or the auto-hook) |
-| `@CacheableRedis` | service method | `IDistributedCache` | `cachedSingleton` / `cachedScoped` + `redisConnect(config, { cache: "distributed" })` in Infra |
+| `@Cacheable` | service method | `ICache` in-memory | `singleton` / `scoped` (the cache hook wraps it) |
+| `@CacheableRedis` | service method | `IDistributedCache` | `singleton` / `scoped` + `redisConnect(config, { cache: "distributed" })` in Infra |
 
 **Important:** put decorators on the **implementation class**, not on a TypeScript interface. DI registers the interface token → the proxy wraps the implementation.
 
@@ -161,7 +160,7 @@ flowchart TB
 ### 3.1. Minimum: in-memory output + method cache
 
 ```ts
-import { Cacheable, OutputCache, cachedScoped, memory } from "@/core/cache";
+import { Cacheable, OutputCache, memory } from "@/core/cache";
 import { runApp } from "@/core/app";
 
 await runApp(AppModule, {
@@ -195,7 +194,7 @@ class UserService implements IUserStore {
 
 // UsersModule:
 providers: [
-  cachedScoped(IUserStore, UserService, [repositoryFor(User)]),
+  scoped(IUserStore, UserService, [repositoryFor(User)]),
 ],
 ```
 
@@ -232,7 +231,7 @@ class ProductService {
 
 // The same provider as for memory: the distributed level turns on
 // automatically when Infra publishes the registry of distributed stores in DI.
-cachedScoped(IProductService, ProductService, deps);
+scoped(IProductService, ProductService, deps);
 ```
 
 ---
@@ -620,32 +619,27 @@ class UserService implements IUserStore {
 
 ---
 
-## 10. DI providers: `cachedSingleton` / `cachedScoped` (+ auto-hook)
+## 10. DI registration: `singleton` / `scoped` with the cache hook
 
-One provider covers both levels. `@Cacheable` → the in-memory `ICache`; `@CacheableRedis` →
-the distributed `DISTRIBUTED_SERVICE_CACHE`, **automatically** if the registry is
-registered through Infra/DI. There are no separate `redisCached*` / `hybridCached*` anymore.
+`memory()` registers a hook on the core `singleton()` / `scoped()` providers: if a class
+carries `@Cacheable` / `@CacheableRedis`, the regular registration is wrapped with a
+caching proxy. One proxy routes `@Cacheable` to the in-memory `ICache` and
+`@CacheableRedis` to the distributed `DISTRIBUTED_SERVICE_CACHE`. The former
+`cachedSingleton` / `cachedScoped` helpers were removed in 0.98.34: they did the same.
 
-| Provider | Decorators | DI dependencies | Scope |
-| --- | --- | --- | --- |
-| `cachedSingleton` | `@Cacheable` and/or `@CacheableRedis` | `ICache`, `CACHE_POLICIES`, (optional) `DISTRIBUTED_SERVICE_CACHE` | singleton |
-| `cachedScoped` | `@Cacheable` and/or `@CacheableRedis` | the same | scoped |
+The hook checks the lifetime at container build (0.98.34):
 
-Removed aliases: `src/bazis/core/cache/COMPATIBILITY.md`.
+| Lifetime | Rule |
+| --- | --- |
+| `singleton` | Any declaration; the automatic key works across calls |
+| `scoped` | Every cached method needs an explicit `key` (or a named `policy`): the automatic key belongs to the instance, so it would cache within one request only. Otherwise `CacheDeclarationError` at startup |
+| `transient` | Refused with `CacheDeclarationError`: a new instance per injection never reuses its cache |
 
 ```ts
 // Interface token ← proxy ← implementation class with decorators.
-// Works for both @Cacheable and @CacheableRedis (if the backend is configured).
-cachedScoped(IUserStore, UserService, [repositoryFor(User)]);
+scoped(IUserStore, UserService);
 ```
 
-### 10.0. Out of the box (auto-hook)
-
-`memory()` registers a hook on the core `singleton()` / `scoped()` providers: if a class
-carries `@Cacheable` / `@CacheableRedis`, the regular registration is **automatically**
-wrapped with a caching proxy. An explicit `cachedScoped` is needed only when you want to
-be completely explicit.
-
 ### 10.1. Interface vs implementation: a common question
 
 ```ts
@@ -659,7 +653,7 @@ class UserService implements IUserStore {
 }
 
 // ✅ correct
-cachedScoped(IUserStore, UserService, deps);
+scoped(IUserStore, UserService, deps);
 
 // ❌ a decorator on an interface does not work
 // With memory() connected, a plain singleton(IUserStore, UserService)
@@ -674,7 +668,7 @@ or a root import of `memory()`. A feature module registers only its own service:
 ```ts
 @Module({
   imports: [UsersDataModule],
-  providers: [cachedScoped(IUserStore, UserService, deps)],
+  providers: [scoped(IUserStore, UserService, deps)],
 })
 class UsersModule {}
 ```
@@ -1066,7 +1060,7 @@ class UserService implements IUserStore {
 
 // UsersModule:
 imports: [UsersDataModule],
-providers: [cachedScoped(IUserStore, UserService, deps)],
+providers: [scoped(IUserStore, UserService, deps)],
 ```
 
 `@CacheableRedis.findByName` uses the distributed level automatically when the backend is
@@ -1174,7 +1168,7 @@ Checklist:
 
 1. The decorator is on the **class `UserService`**, not on `interface IUserStore`.
 2. The root app installs `cache: memory()` or imports `memory()` (auto-hook + `ICache`, `CACHE_POLICIES`).
-3. The registration goes through `singleton`/`scoped` (the auto-hook wraps it) or explicitly `cachedScoped`/`cachedSingleton`.
+3. The registration goes through `singleton`/`scoped` (the cache hook wraps it); a scoped one needs an explicit `key`.
 4. The options have **`seconds`** (inline or in the `policy`).
 5. For `@CacheableRedis`, infra connects `redisConnect(redisConfig, { cache: "distributed" })`, otherwise the call throws.
 
@@ -1190,7 +1184,7 @@ Checklist:
 async byId(id: number) { ... }
 
 // UsersModule.ts: registration on the interface token
-cachedScoped(IUserStore, UserService, deps);
+scoped(IUserStore, UserService, deps);
 ```
 
 The controller gets the proxy registered as `IUserStore`. The metadata is read from the `UserService` class (`Symbol.metadata`), not from the interface.
@@ -1242,28 +1236,16 @@ Technically yes, but **do not**: a startup warning, and Redis wins. Pick one sto
 
 ### Can `@Cacheable` and `@CacheableRedis` be on one method?
 
-**No**: a runtime error. On **different** methods of one class use a regular `cachedScoped` (one proxy routes memory and distributed).
+**No**: a runtime error. On **different** methods of one class use a regular `scoped` registration (one proxy routes memory and distributed).
 
 ---
 
-### `cachedSingleton` or `cachedScoped`?
-
-| | singleton | scoped |
-| --- | --- | --- |
-| Proxy instance | one per DI registration in the container | one per DI registration in the scope |
-| `@Cacheable` cache | the shared ICache store, automatic keys are isolated per instance | the same ICache store, automatic keys are isolated per instance |
-| ORM `DbContext` | ⚠️ careful | ✅ the typical case |
-
-A `UserService` with an ORM → **`cachedScoped`**. A stateless read-only service without scoped deps → `cachedSingleton` is fine.
-An explicit `key` in `cachedScoped` and `cachedSingleton` is a sharing contract: include the
-tenant/user in it if the result is personalized. Without an explicit `key` the framework
-isolates the automatic key per instance, so hidden constructor state does not leak into the
-response of another registration or request. This also applies to `@CacheableRedis`:
-sharing between processes and reuse after a restart need an explicit application `key`.
-DI creates the object with a regular class provider and then applies the proxy;
-constructor deps and lifecycle are not bypassed.
+### `singleton` or `scoped`?
 
----
+A `UserService` with an ORM is **`scoped`**: give every cached method an explicit `key`
+that includes the user or tenant when the result depends on them. A stateless read-only
+service without scoped dependencies can be a `singleton`; its automatic keys work across
+calls.
 
 ### Is Redis needed for the application to work?
 

package/core/cache/decorators/Cacheable.ts

@@ -12,8 +12,9 @@ type ClassOrMethodDecorator = (
  * Caches the return value of a service/provider method in {@link ICache}.
  *
  * Mirrors Spring / FusionCache `@Cacheable`. Put the decorator on the
- * **implementation class**, then register via {@link cachedSingleton} or
- * {@link cachedScoped} so DI returns a caching proxy for the interface token.
+ * **implementation class** and register it as usual (`scoped`, `singleton`):
+ * with the cache module installed, DI returns a caching proxy. A scoped
+ * service needs an explicit `key`; a transient one cannot cache.
  *
  * ```ts
  * class UserService implements IUserStore {
@@ -21,7 +22,7 @@ type ClassOrMethodDecorator = (
  *   async byId(id: number) { ... }
  * }
  *
- * cachedScoped(IUserStore, UserService, [repositoryFor(User)])
+ * scoped(IUserStore, UserService)
  * ```
  */
 export function Cacheable(options: CacheableOptions): ClassOrMethodDecorator {

package/core/cache/decorators/CacheableRedis.ts

@@ -12,9 +12,8 @@ type ClassOrMethodDecorator = (
  * Shared service method cache backed by the distributed tier (multi-instance safe).
  *
  * Requires a distributed backend: add `redisConnect(redisConfig, { cache: "distributed" })`
- * to your `@Infra` manifest. Register the class with the usual `cachedScoped` /
- * `cachedSingleton` (or just `scoped` / `singleton` — the auto-hook wraps it). The distributed
- * tier activates automatically when a backend is configured.
+ * to your `@Infra` manifest. Register the class as usual (`scoped` / `singleton`):
+ * the cache module wraps it. Values must be plain JSON.
  *
  * ```ts
  * class UserService implements IUserStore {
@@ -22,7 +21,7 @@ type ClassOrMethodDecorator = (
  *   async byId(id: number) { ... }
  * }
  *
- * cachedScoped(IUserStore, UserService, [repositoryFor(User)]);
+ * scoped(IUserStore, UserService);
  * ```
  */
 export function CacheableRedis(options: CacheableRedisOptions): ClassOrMethodDecorator {

package/core/cache/di/classProviderHook.ts

@@ -1,4 +1,5 @@
 import type { Class, ClassProviderHook, Token } from "../../di";
+import { CacheDeclarationError } from "../errors/CacheError";
 import { cacheableMetaOf, hasCacheableMethods } from "../decorators/cacheableMetadata";
 import { cacheableRedisMetaOf, hasCacheableRedisMethods } from "../decorators/cacheableRedisMetadata";
 import { cachedScoped, cachedSingleton } from "../providers/cachedProviders";
@@ -16,6 +17,7 @@ export const cacheableClassProviderHook: ClassProviderHook = ({ lifetime, provid
   }
   const token = provide as Token<object>;
   const impl = useClass as Class<object>;
+  assertCacheableLifetime(impl, lifetime);
   if (lifetime === "scoped") {
     return cachedScoped(token, impl, deps);
   }
@@ -24,3 +26,32 @@ export const cacheableClassProviderHook: ClassProviderHook = ({ lifetime, provid
   }
   return undefined;
 };
+
+interface Declared { readonly key?: unknown; readonly policy?: unknown }
+
+/**
+ * A cache that can never hit is refused at startup, as an invalid registration
+ * (a DI error: the start prints it as a configuration error). The automatic key belongs
+ * to the service instance (a scoped result may depend on the request's user),
+ * so without an explicit `key` a scoped service caches only within one request,
+ * and a transient one — never.
+ */
+function assertCacheableLifetime(impl: Class<object>, lifetime: string): void {
+  const declarations: { decorator: string; classLevel?: Declared; methods: ReadonlyMap<string | symbol, Declared> }[] = [];
+  const memory = cacheableMetaOf(impl);
+  if (hasCacheableMethods(memory)) declarations.push({ decorator: "@Cacheable", classLevel: memory!.cacheable, methods: memory!.methods });
+  const shared = cacheableRedisMetaOf(impl);
+  if (hasCacheableRedisMethods(shared)) declarations.push({ decorator: "@CacheableRedis", classLevel: shared!.cacheableRedis, methods: shared!.methods });
+  for (const { decorator, classLevel, methods } of declarations) {
+    if (lifetime === "transient") {
+      throw new CacheDeclarationError(`${impl.name} uses ${decorator} but is registered transient: a new instance for every injection never reuses its cache. Register it as singleton or scoped.`);
+    }
+    if (lifetime !== "scoped") continue;
+    const names = methods.size > 0 ? [...methods.keys()] : ["(every method)"];
+    for (const name of names) {
+      const declared = { ...classLevel, ...(typeof name === "string" && name === "(every method)" ? {} : methods.get(name)) };
+      if (declared.key !== undefined || declared.policy !== undefined) continue;
+      throw new CacheDeclarationError(`${impl.name}.${String(name)}: ${decorator} without key on a scoped service caches only within one request (the automatic key belongs to the instance). Set key — include the user or tenant when the result depends on them — or register ${impl.name} as a singleton.`);
+    }
+  }
+}

package/core/cache/distributed/DistributedCache.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { CacheValueError } from "../errors/CacheError";
+import { CacheUnavailableError, CacheValueError } from "../errors/CacheError";
 import { assertCacheKey, measureStringBytes } from "../internal/CacheKeyGuard";
 import type { CacheCodec } from "./CacheCodec";
 import type {
@@ -36,8 +36,12 @@ export interface DistributedCacheConfig {
   readonly maxValueBytes?: number;
   /** Poll interval (ms) while waiting for a peer worker to fill the cache. */
   readonly pollIntervalMs?: number;
+  /** Bound of one store operation (ms); a hung store must not hang the caller. Default 1000. */
+  readonly operationTimeoutMs?: number;
 }
 
+const DEFAULT_OPERATION_TIMEOUT_MS = 1000;
+
 /**
  * Backend-agnostic distributed cache. Owns all caching policy and delegates raw
  * I/O to a {@link DistributedCacheDriver}. One instance per (connection × namespace).
@@ -52,6 +56,9 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
   private readonly fullPrefix: string;
   private readonly maxKeyLength: number;
   private readonly pollIntervalMs: number;
+  private readonly operationTimeoutMs: number;
+  /** The driver with every operation bounded by {@link io}. */
+  private readonly ioCall: DistributedCacheDriver;
 
   public readonly connectionName: string;
   public readonly keyPrefix: string;
@@ -71,6 +78,9 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     if (snapshot.maxValueBytes !== undefined && (!Number.isInteger(snapshot.maxValueBytes) || snapshot.maxValueBytes <= 0)) {
       throw new CacheValueError("maxValueBytes must be a positive integer");
     }
+    if (snapshot.operationTimeoutMs !== undefined && (!Number.isSafeInteger(snapshot.operationTimeoutMs) || snapshot.operationTimeoutMs <= 0 || snapshot.operationTimeoutMs > 2_147_483_647)) {
+      throw new CacheValueError("operationTimeoutMs must be a positive integer of milliseconds");
+    }
     if (snapshot.pollIntervalMs !== undefined && (!Number.isFinite(snapshot.pollIntervalMs) || snapshot.pollIntervalMs <= 0)) {
       throw new CacheValueError("pollIntervalMs must be a positive number");
     }
@@ -80,12 +90,40 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     this.fullPrefix = `${snapshot.keyPrefix}${snapshot.namespace ?? ""}`;
     this.maxKeyLength = snapshot.maxKeyLength ?? DEFAULT_DISTRIBUTED_MAX_KEY_LENGTH;
     this.pollIntervalMs = snapshot.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.operationTimeoutMs = snapshot.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
+    this.ioCall = new Proxy(driver, {
+      get: (target, property) => {
+        const member = (target as unknown as Record<PropertyKey, unknown>)[property];
+        return typeof member === "function"
+          ? (...args: unknown[]) => this.io(() => (member as (...values: unknown[]) => Promise<unknown>).apply(target, args))
+          : member;
+      },
+    });
+  }
+
+  /**
+   * One store operation, bounded by `operationTimeoutMs`. A timeout or a driver
+   * failure becomes {@link CacheUnavailableError}; the native operation is not
+   * cancelled (the driver has no cancellation), only no longer awaited.
+   */
+  private io<T>(work: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new CacheUnavailableError(
+        `Distributed cache "${this.connectionName}" did not answer within ${this.operationTimeoutMs} ms.`,
+      )), this.operationTimeoutMs);
+      let started: Promise<T>;
+      try { started = work(); } catch (error) { clearTimeout(timer); reject(unavailable(this.connectionName, error)); return; }
+      started.then(
+        (value) => { clearTimeout(timer); resolve(value); },
+        (error: unknown) => { clearTimeout(timer); reject(unavailable(this.connectionName, error)); },
+      );
+    });
   }
 
   public async get<T = TValue>(key: string): Promise<T | undefined> {
     assertCacheKey(key, this.maxKeyLength);
     const storageKey = this.storageKey(key);
-    const raw = await this.driver.read(storageKey);
+    const raw = await this.ioCall.read(storageKey);
     if (raw === null) {
       return undefined;
     }
@@ -93,7 +131,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       return this.codec.deserialize(decodeEnvelope(raw).payload) as unknown as T;
     } catch {
       try {
-        await this.driver.deleteIfValue(storageKey, raw);
+        await this.ioCall.deleteIfValue(storageKey, raw);
       } catch {
         // A corrupt cache entry is still a miss when backend cleanup fails.
         // Do not turn best-effort cache maintenance into a request failure.
@@ -108,7 +146,14 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     options: DistributedCacheSetOptions,
   ): Promise<T | undefined> {
     const normalizedOptions = this.normalizeSetOptions(options);
-    const hit = await this.get<T>(key);
+    let hit: T | undefined;
+    try {
+      hit = await this.get<T>(key);
+    } catch (error) {
+      // The cache is optional: an unavailable store means "compute it now".
+      if (error instanceof CacheUnavailableError) return factory();
+      throw error;
+    }
     if (hit !== undefined) {
       return hit;
     }
@@ -132,7 +177,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
   public async remove(key: string): Promise<boolean> {
     assertCacheKey(key, this.maxKeyLength);
     this.inFlight.delete(key);
-    return this.driver.invalidate(this.entryVersionKey(key), this.storageKey(key), this.lockKeyFor(key));
+    return this.ioCall.invalidate(this.entryVersionKey(key), this.storageKey(key), this.lockKeyFor(key));
   }
 
   public async evictByTag(tag: string): Promise<number> {
@@ -142,8 +187,8 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     }
     const versionKey = this.tagVersionKey(tag);
     const pendingKey = this.tagPendingKey(tag);
-    await this.driver.advanceTagGeneration(versionKey, pendingKey);
-    const generations = [...await this.driver.tagMembers(pendingKey)]
+    await this.ioCall.advanceTagGeneration(versionKey, pendingKey);
+    const generations = [...await this.ioCall.tagMembers(pendingKey)]
       .filter((value) => /^\d+$/.test(value))
       .sort((left, right) => Number(left) - Number(right));
     let removed = 0;
@@ -155,7 +200,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
 
   private async evictTagGeneration(tag: string, generation: string, pendingKey: string): Promise<number> {
     const tagKey = this.tagKey(tag, generation);
-    const members = await this.driver.tagMembers(tagKey);
+    const members = await this.ioCall.tagMembers(tagKey);
     let removed = 0;
     for (const member of members) {
       const parsed = decodeTagMember(member);
@@ -165,19 +210,19 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       if (!parsed.storageKey.startsWith(`${this.fullPrefix}entry:`)) {
         continue;
       }
-      const raw = await this.driver.read(parsed.storageKey);
+      const raw = await this.ioCall.read(parsed.storageKey);
       if (raw === null) {
         continue;
       }
       if (decodeEnvelope(raw).token !== parsed.token) {
         continue;
       }
-      if (await this.driver.deleteIfValue(parsed.storageKey, raw)) {
+      if (await this.ioCall.deleteIfValue(parsed.storageKey, raw)) {
         removed += 1;
       }
     }
-    await this.driver.delete([tagKey]);
-    await this.driver.removeTagMembers(pendingKey, [generation]);
+    await this.ioCall.delete([tagKey]);
+    await this.ioCall.removeTagMembers(pendingKey, [generation]);
     return removed;
   }
 
@@ -215,9 +260,21 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     const lockTtl = Math.max(1, Math.floor(options.lockSeconds ?? this.config.defaultLockSeconds));
     const token = randomUUID();
 
-    const acquired = await this.driver.acquireLock(lockKey, token, lockTtl);
+    let acquired: boolean;
+    try {
+      acquired = await this.ioCall.acquireLock(lockKey, token, lockTtl);
+    } catch (error) {
+      if (error instanceof CacheUnavailableError) return factory();
+      throw error;
+    }
     if (!acquired) {
-      const peerValue = await this.waitForPeerResult<T>(key, lockKey, lockTtl);
+      let peerValue: T | undefined;
+      try {
+        peerValue = await this.waitForPeerResult<T>(key, lockKey, lockTtl);
+      } catch (error) {
+        if (error instanceof CacheUnavailableError) return factory();
+        throw error;
+      }
       if (peerValue !== undefined) return peerValue;
       if (contentionAttempt < 2) {
         return this.runLockedFactory(key, factory, options, contentionAttempt + 1);
@@ -228,11 +285,18 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     }
 
     try {
-      const again = await this.get<T>(key);
-      if (again !== undefined) {
-        return again;
+      let versionChecks: readonly DistributedCacheVersionCheck[];
+      try {
+        const again = await this.get<T>(key);
+        if (again !== undefined) {
+          return again;
+        }
+        versionChecks = await this.captureVersions(key, options.tags);
+      } catch (error) {
+        // The store went away under the lock: compute, but do not write.
+        if (error instanceof CacheUnavailableError) return await factory();
+        throw error;
       }
-      const versionChecks = await this.captureVersions(key, options.tags);
       const value = await factory();
       if (value !== undefined) {
         await this.trySet(key, value, options, lockKey, token, versionChecks);
@@ -243,7 +307,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
         // Unlock is best effort: a transport error must not replace a fresh
         // service result or the factory's original exception. The lock still
         // has a bounded TTL, so another worker eventually makes progress.
-        await this.driver.releaseLock(lockKey, token, this.entryVersionKey(key));
+        await this.ioCall.releaseLock(lockKey, token, this.entryVersionKey(key));
       } catch {
         // Intentionally preserve the primary outcome.
       }
@@ -257,7 +321,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       if (hit !== undefined) {
         return hit;
       }
-      if (await this.driver.read(lockKey) === null) {
+      if (await this.ioCall.read(lockKey) === null) {
         break;
       }
       await Bun.sleep(this.pollIntervalMs);
@@ -273,8 +337,11 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     lockToken: string,
     versionChecks: readonly DistributedCacheVersionCheck[],
   ): Promise<void> {
+    // A value the codec refuses is a bug of the cached method, not a store
+    // outage: it surfaces instead of silently never being cached.
+    const serialized = this.codec.serialize(value as unknown as TValue);
     try {
-      await this.write(key, value as unknown as TValue, options, lockKey, lockToken, versionChecks);
+      await this.write(key, serialized, options, lockKey, lockToken, versionChecks);
     } catch {
       // Graceful degradation — the caller still receives the fresh value.
     }
@@ -282,14 +349,13 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
 
   private async write(
     key: string,
-    value: TValue,
+    serialized: string,
     options: DistributedCacheSetOptions,
     lockKey: string,
     lockToken: string,
     versionChecks: readonly DistributedCacheVersionCheck[],
   ): Promise<void> {
     assertCacheKey(key, this.maxKeyLength);
-    const serialized = this.codec.serialize(value);
 
     if (this.config.maxValueBytes !== undefined) {
       const bytes = measureStringBytes(serialized);
@@ -318,7 +384,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       tags[index] = { key: tag.key, member: encodeTagMember(storageKey, writeToken) };
     }
     const envelope = encodeEnvelope(writeToken, serialized);
-    await this.driver.writeIfLockOwner({
+    await this.ioCall.writeIfLockOwner({
       lockKey,
       lockToken,
       key: storageKey,
@@ -336,7 +402,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     const keys = [this.entryVersionKey(key), ...(tags ?? []).map((tag) => this.tagVersionKey(tag))];
     return Promise.all(keys.map(async (versionKey) => ({
       key: versionKey,
-      expected: await this.driver.read(versionKey),
+      expected: await this.ioCall.read(versionKey),
     })));
   }
 
@@ -401,3 +467,8 @@ function decodeTagMember(member: string): { readonly storageKey: string; readonl
   }
   return undefined;
 }
+
+function unavailable(connection: string, error: unknown): CacheUnavailableError {
+  if (error instanceof CacheUnavailableError) return error;
+  return new CacheUnavailableError(`Distributed cache "${connection}" failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}

package/core/cache/distributed/IDistributedCache.ts

@@ -1,3 +1,4 @@
+import { createToken, type InjectionToken } from "../../di";
 import type { CacheSetOptions } from "../types/CacheOptions";
 
 /** Default named connection used when a decorator omits `connection`. */
@@ -38,3 +39,11 @@ export interface IDistributedCache<TValue = unknown> {
   /** Removes all entries carrying `tag`; returns the number removed. */
   evictByTag(tag: string): Promise<number>;
 }
+
+/**
+ * The distributed cache by type: `constructor(private readonly shared: IDistributedCache)`.
+ * Registered by `redisConnect(config, { cache: "distributed" })` for its one
+ * connection; a custom backend with several connections keeps
+ * `DISTRIBUTED_SERVICE_CACHE.resolve(name)`.
+ */
+export const IDistributedCache = createToken<IDistributedCache>("IDistributedCache") as InjectionToken<IDistributedCache<unknown>>;

package/core/cache/distributed/codecs.ts

@@ -1,12 +1,59 @@
 import type { CachedHttpPayload } from "../http/CachedHttpPayload";
 import type { CacheCodec } from "./CacheCodec";
+import { CacheValueError } from "../errors/CacheError";
 
-/** JSON codec for arbitrary service values (`@Cacheable` distributed tier). */
+/**
+ * JSON codec for service values (`@CacheableRedis`, `IDistributedCache`). It
+ * refuses a value that JSON would change on the way back — a Date comes back
+ * as a string, a Set or Map as `{}` — instead of returning altered data on a
+ * cache hit.
+ */
 export const jsonCacheCodec: CacheCodec<unknown> = {
-  serialize: (value) => JSON.stringify(value),
+  serialize: (value) => {
+    const problem = notPlainJson(value, "value", new Set());
+    if (problem !== undefined) {
+      throw new CacheValueError(`Cache value is not plain JSON: ${problem}. Return plain data (an ISO string for a date, an array for a set), or cache it in memory with @Cacheable.`);
+    }
+    return JSON.stringify(value);
+  },
   deserialize: (raw) => JSON.parse(raw) as unknown,
 };
 
+/** Where `value` stops surviving JSON unchanged, or undefined when it does. */
+function notPlainJson(value: unknown, path: string, seen: Set<object>): string | undefined {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return undefined;
+  if (typeof value === "number") return Number.isFinite(value) ? undefined : `${path} is ${String(value)} (JSON writes null)`;
+  if (typeof value === "bigint") return `${path} is a bigint`;
+  if (typeof value !== "object") return `${path} is a ${typeof value}`;
+  if (seen.has(value)) return `${path} is a circular reference`;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        const item: unknown = value[index];
+        if (item === undefined) return `${path}[${index}] is undefined (JSON writes null)`;
+        const problem = notPlainJson(item, `${path}[${index}]`, seen);
+        if (problem !== undefined) return problem;
+      }
+      return undefined;
+    }
+    const prototype = Object.getPrototypeOf(value) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) {
+      const name = (value as { constructor?: { name?: string } }).constructor?.name || "object with a prototype";
+      return `${path} is a ${name}${value instanceof Date ? " (JSON returns a string)" : value instanceof Map || value instanceof Set ? " (JSON returns {})" : ""}`;
+    }
+    for (const key of Object.keys(value)) {
+      const item = (value as Record<string, unknown>)[key];
+      if (item === undefined) continue;                 // dropped and read back as undefined
+      const problem = notPlainJson(item, `${path}.${key}`, seen);
+      if (problem !== undefined) return problem;
+    }
+    return undefined;
+  } finally {
+    seen.delete(value);
+  }
+}
+
 interface SerializedHttpPayload {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;

package/core/cache/distributed/index.ts

@@ -3,7 +3,7 @@ export { jsonCacheCodec, httpPayloadCacheCodec } from "./codecs";
 export {
   DEFAULT_CACHE_CONNECTION,
   type DistributedCacheSetOptions,
-  type IDistributedCache,
+  IDistributedCache,
 } from "./IDistributedCache";
 export type {
   DistributedCacheDriver,

package/core/cache/errors/CacheError.ts

@@ -1,7 +1,8 @@
+import { DiError } from "../../di";
 /** Base error of the cache module. */
 export class CacheError extends Error {
-  public constructor(message: string) {
-    super(message);
+  public constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = new.target.name;
   }
 }
@@ -12,5 +13,19 @@ export class CacheKeyError extends CacheError {}
 /** Invalid value (size limit exceeded and the like). */
 export class CacheValueError extends CacheError {}
 
+/**
+ * The distributed store did not answer in time or failed. On the cache-aside
+ * path (`getOrCreateAsync`, `@CacheableRedis`) the value is computed without
+ * the cache; explicit operations (`get`, `remove`, `evictByTag`) throw it.
+ */
+export class CacheUnavailableError extends CacheError {}
+
 /** The limit of unfinished factories is exhausted; the new factory was not started. */
 export class CacheCapacityError extends CacheError {}
+
+/**
+ * A cache declaration that can never work, found while the container is built
+ * (a cached scoped method without a key, a cached transient service). A DI
+ * error, so the start prints it as a configuration error.
+ */
+export class CacheDeclarationError extends DiError {}

package/core/cache/http/outputRedisCacheMiddleware.ts

@@ -1,5 +1,5 @@
 import type { HttpMiddleware } from "../../http";
-import { CacheError } from "../errors/CacheError";
+import { CacheError, CacheUnavailableError } from "../errors/CacheError";
 import { DISTRIBUTED_OUTPUT_CACHE } from "../tokens/DISTRIBUTED_CACHE";
 import {
   DEFAULT_OUTPUT_CACHE_METHODS,
@@ -14,6 +14,7 @@ import {
   resolveCachedHttpPayloadReadOptions,
   responseAllowsServerCache,
   responseToCachedPayload,
+  type CachedHttpPayload,
 } from "./CachedHttpPayload";
 
 export interface OutputRedisCacheMiddlewareOptions {
@@ -81,7 +82,15 @@ export function outputRedisCacheMiddleware(options: OutputRedisCacheMiddlewareOp
     }
 
     const key = buildRedisOutputCacheKey(ctx, routeName, config);
-    const cached = await cache.get(key);
+    let cached: CachedHttpPayload | undefined;
+    try {
+      cached = await cache.get(key);
+    } catch (error) {
+      // The cache is optional: an unavailable store serves the route uncached.
+      if (!(error instanceof CacheUnavailableError)) throw error;
+      await next();
+      return;
+    }
     if (cached !== undefined) {
       ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached, { hit: true }), clientCache);
       return;

package/core/cache/index.ts

@@ -51,7 +51,7 @@ export {
   type DistributedCacheVersionCheck,
   type DistributedCachePing,
   type DistributedCacheSetOptions,
-  type IDistributedCache,
+  IDistributedCache,
 } from "./distributed";
 export {
   DISTRIBUTED_CACHE_BACKEND,
@@ -66,7 +66,7 @@ export {
   type CacheModuleConfig,
   type CacheOutputCacheOptions,
 } from "./internal/buildCacheProviders";
-export { CacheError, CacheKeyError, CacheValueError, CacheCapacityError } from "./errors/CacheError";
+export { CacheError, CacheKeyError, CacheValueError, CacheCapacityError, CacheDeclarationError, CacheUnavailableError } from "./errors/CacheError";
 
 export { OutputCache, type OutputCacheOptions as OutputCacheDecoratorOptions } from "./decorators/OutputCache";
 export {
@@ -91,7 +91,3 @@ export {
 } from "./internal/resolveCachePolicy";
 export { buildOutputCacheKey, OUTPUT_CACHE_PRINCIPAL_STATE_KEY } from "./http/buildOutputCacheKey";
 export { wrapCachedService, type CacheProxyOptions } from "./services/cacheProxy";
-export {
-  cachedSingleton,
-  cachedScoped,
-} from "./providers/cachedProviders";

package/core/cache/services/cacheProxy.ts

@@ -11,7 +11,7 @@ import {
 } from "../decorators/cacheableRedisMetadata";
 import type { IDistributedCache } from "../distributed/IDistributedCache";
 import type { NamedCacheRegistry } from "../distributed/NamedCacheRegistry";
-import { CacheError } from "../errors/CacheError";
+import { CacheError, CacheValueError } from "../errors/CacheError";
 import type { ICache } from "../ICache";
 import { normalizeCacheKey } from "../internal/normalizeCacheKey";
 import { AutomaticCacheKey } from "../internal/AutomaticCacheKey";
@@ -141,7 +141,11 @@ function wrapDistributedMethod(
         return result instanceof Promise ? await result : result;
       },
       { ttlSeconds: options.seconds, tags: options.tags, lockSeconds: options.lockSeconds },
-    );
+    ).catch((error: unknown) => {
+      // Name the method: "value.at is a Date" alone does not say where.
+      if (error instanceof CacheValueError) throw new CacheValueError(`${className}.${String(methodName)}: ${error.message}`, { cause: error });
+      throw error;
+    });
   };
 }
 

package/core/di/extensions/hosted-service.ts

@@ -22,7 +22,18 @@ export interface HostedServiceDiagnostics {
   warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
 }
 
+/** What a hosted service reports to `/health`. */
+export interface HostedServiceHealth {
+  readonly healthy: boolean;
+  readonly details?: string;
+}
+
 export interface HostedService {
+  /**
+   * The service's own state for `/health`. A `background` service of a module
+   * is reported as `background:<Class>`; without this method it is healthy.
+   */
+  checkHealth?(): HostedServiceHealth;
   /** Shared validators see real service identities, including inside supervised wrappers. */
   readonly planValidator?: HostedServicePlanValidator;
   /** Receives the application logger before start, when one is registered. */
@@ -39,6 +50,15 @@ export interface HostedService {
 
 export const HOSTED_SERVICE = createToken<HostedService>("IHostedService");
 
+/** A health check contributed by a hosted service; the kernel reports it next to its own checks. */
+export interface HostedServiceHealthCheck {
+  readonly name: string;
+  check(): HostedServiceHealth;
+}
+
+/** Enumerable: one entry per `background` service of the module graph. */
+export const HOSTED_SERVICE_HEALTH = createToken<HostedServiceHealthCheck>("BazisHostedServiceHealth");
+
 interface HostedServiceResolver {
   resolveAll(token: typeof HOSTED_SERVICE): readonly HostedService[];
 }

package/core/di/extensions/index.ts

@@ -1,6 +1,6 @@
 export { createInstance, type ActivatorDependency } from "./activator";
 export { Application, runApplication, type RunApplicationOptions } from "./application";
-export { addHostedService, HOSTED_SERVICE, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServicePlanValidator } from "./hosted-service";
+export { addHostedService, HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServiceHealth, type HostedServiceHealthCheck, type HostedServicePlanValidator } from "./hosted-service";
 export { SERVICE_PROVIDER } from "./service-provider-token";
 export {
   addOptions,

package/core/di/module/createContainer.ts

@@ -1,6 +1,6 @@
 import { DiContainer } from "../container";
 import { ServiceCollection } from "../ServiceCollection";
-import { HOSTED_SERVICE, type HostedService } from "../extensions/hosted-service";
+import { HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, type HostedService } from "../extensions/hosted-service";
 import { SERVICE_PROVIDER, SERVICE_PROVIDER_BY_TYPE } from "../extensions/service-provider-token";
 import { isClassProvider, ProviderDefinition, type Provider } from "../provider";
 import { getClassDeps } from "../internal/classDeps";
@@ -162,6 +162,13 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
         collection.add(
           DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass))),
         );
+        // `/health` sees a service that stopped for good, not only the process.
+        collection.add(
+          DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE_HEALTH, [], (resolver) => {
+            const service = resolver.resolve(ServiceClass);
+            return { name: `background:${ServiceClass.name}`, check: () => service.checkHealth?.() ?? { healthy: true } };
+          })),
+        );
       }
     }
 

package/core/infra/cache/RedisDistributedCacheBackend.ts

@@ -25,6 +25,8 @@ export interface RedisDistributedCacheTuning {
   readonly maxValueBytes?: number;
   /** Polling interval (ms) while waiting for another worker's result. */
   readonly pollIntervalMs?: number;
+  /** Bound of one Redis operation (ms); on expiry the method runs without the cache. Default 1000. */
+  readonly operationTimeoutMs?: number;
 }
 
 const DEFAULT_KEY_PREFIX = "bazis:cache:";
@@ -59,6 +61,7 @@ export class RedisDistributedCacheBackend implements DistributedCacheStores {
       maxKeyLength: tuning.maxKeyLength,
       maxValueBytes: tuning.maxValueBytes,
       pollIntervalMs: tuning.pollIntervalMs,
+      operationTimeoutMs: tuning.operationTimeoutMs,
     };
 
     const output = new DistributedCache<CachedHttpPayload>(driver, httpPayloadCacheCodec, {

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.32" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.34" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/infra/connectors/redis.ts

@@ -3,6 +3,7 @@ import {
   DISTRIBUTED_CACHE_BACKEND,
   DISTRIBUTED_OUTPUT_CACHE,
   DISTRIBUTED_SERVICE_CACHE,
+  IDistributedCache,
   type DistributedCacheStores,
 } from "../../cache";
 import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
@@ -60,6 +61,13 @@ function distributedCacheProviders(tuning: RedisDistributedCacheTuning, token: I
         backend.serviceCache,
       ),
     ),
+    // This connector's one connection by type, for services that evict tags or
+    // read values; its name may be "default" or the configured `connection`.
+    DI.singleton(
+      DI.factoryProvider(IDistributedCache, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) =>
+        backend.serviceCache.resolve(backend.serviceCache.connectionNames[0]),
+      ),
+    ),
   ];
 }
 
@@ -91,7 +99,7 @@ export function redisConnect<T extends RedisConfigShape>(
     token,
     config,
     providers: cacheProviders,
-    exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE] : undefined,
+    exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE, IDistributedCache] : undefined,
     create(configs) {
       return new RedisClient(redisUrl(reader(config, configs).get("url")));
     },

package/core/kernel/health/HealthService.ts

@@ -1,4 +1,4 @@
-import type { ServiceResolver } from "../../di";
+import { HOSTED_SERVICE_HEALTH, type ServiceResolver } from "../../di";
 import { redactSensitiveText } from "../../../library/redaction";
 import { awaitAbortable } from "../internal/awaitAbortable";
 import { KernelError } from "../errors";
@@ -21,7 +21,8 @@ export class HealthService {
     const timeoutMs = bounded(options.timeoutMs ?? 5000, "timeoutMs", 2147483647);
     const checkTimeoutMs = bounded(options.checkTimeoutMs ?? 1000, "checkTimeoutMs", 2147483647);
     const concurrency = bounded(options.concurrency ?? 4, "concurrency", 1024);
-    const checks = this.resolver.resolveAll(HEALTH_CHECK);
+    // Hosted services (background) report whether they still run.
+    const checks: readonly HealthCheck[] = [...this.resolver.resolveAll(HEALTH_CHECK), ...this.resolver.resolveAll(HOSTED_SERVICE_HEALTH)];
     const entries: HealthReportEntry[] = new Array(checks.length);
     const report = new AbortController();
     const timer = setTimeout(() => report.abort(new Error("Health report timed out.")), timeoutMs);

package/index.ts

@@ -204,8 +204,6 @@ export {
 export {
   Cacheable,
   OutputCache,
-  cachedScoped,
-  cachedSingleton,
   memory,
 } from "./core/cache";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.32",
+  "version": "0.98.34",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",

package/core/background/backgroundModule.ts

@@ -1,42 +0,0 @@
-import {
-  DI,
-  HOSTED_SERVICE,
-  Module,
-  singleton,
-  type Class,
-  type HostedService,
-  type BazisModule,
-  type ProviderDefinition,
-} from "../di";
-
-export interface BackgroundModuleConfig {
-  /**
-   * Background service classes (subclasses of `BackgroundService` /
-   * `PeriodicBackgroundService`). Each is registered as a singleton (with
-   * auto-resolved constructor dependencies) and exposed as a `HOSTED_SERVICE`,
-   * so the kernel starts and gracefully stops it with the rest of the app.
-   */
-  readonly services: readonly Class<HostedService>[];
-}
-
-/**
- * Registers background services in DI and wires them into the kernel lifecycle.
- *
- * ```ts
- * @Module({ imports: [backgroundModule({ services: [SessionCleanup, Heartbeat] })] })
- * class AppModule {}
- * ```
- */
-export function backgroundModule(config: BackgroundModuleConfig): BazisModule {
-  const providers: ProviderDefinition[] = config.services.flatMap((ServiceClass) => [
-    singleton(ServiceClass),
-    DI.singleton(
-      DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass)),
-    ),
-  ]);
-
-  @Module({ providers })
-  class BackgroundModule {}
-
-  return BackgroundModule;
-}