bazis 0.96.1

package/core/cache/providers/cachedProviders.ts

@@ -0,0 +1,68 @@
+import {
+  DI,
+  type Class,
+  type ProviderDefinition,
+  type ProviderDependencyList,
+  type ServiceResolver,
+  type Token,
+} from "../../di";
+import { randomUUID } from "node:crypto";
+import { ICache } from "../ICache";
+import { CACHE_POLICIES } from "../tokens/CACHE_POLICIES";
+import { DISTRIBUTED_SERVICE_CACHE } from "../tokens/DISTRIBUTED_CACHE";
+import { wrapCachedService } from "../services/cacheProxy";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+
+type CachedLifetime = "singleton" | "scoped";
+
+function cachedProvider<T extends object>(
+  lifetime: CachedLifetime,
+  provide: Token<T>,
+  useClass: Class<T>,
+  deps?: ProviderDependencyList,
+): ProviderDefinition<T> {
+  // Retain a class provider: DI owns constructor binding, arity validation,
+  // async dependencies and disposal. Cache only wraps the activated instance.
+  const definition = {
+    ...DI.classProvider(provide, useClass, deps),
+    activation: {
+      deps: [ICache, CACHE_POLICIES],
+      wrap(instance: T, resolver: ServiceResolver, ...values: unknown[]): T {
+        return wrapCachedService(instance, {
+          memoryCache: values[0] as ICache,
+          policies: values[1] as CachePolicyRegistry,
+          serviceCache: resolver.tryResolve(DISTRIBUTED_SERVICE_CACHE),
+          className: useClass.name,
+          // Every DI instance has its own implicit keys, including distinct
+          // singleton registrations of one class. Explicit keys opt into sharing.
+          cacheNamespace: randomUUID(),
+        });
+      },
+    },
+  };
+  return lifetime === "singleton" ? DI.singleton(definition) : DI.scoped(definition);
+}
+
+/**
+ * Singleton provider that wraps the implementation in a caching proxy.
+ *
+ * Decorate the **implementation class** (`@Cacheable` / `@CacheableRedis`) and
+ * register against the interface token. The distributed tier activates
+ * automatically when `redisConnect(...)` is configured.
+ */
+export function cachedSingleton<T extends object>(
+  provide: Token<T>,
+  useClass: Class<T>,
+  deps?: ProviderDependencyList,
+): ProviderDefinition<T> {
+  return cachedProvider("singleton", provide, useClass, deps);
+}
+
+/** Scoped caching provider (per-request DI scope). See {@link cachedSingleton}. */
+export function cachedScoped<T extends object>(
+  provide: Token<T>,
+  useClass: Class<T>,
+  deps?: ProviderDependencyList,
+): ProviderDefinition<T> {
+  return cachedProvider("scoped", provide, useClass, deps);
+}

package/core/cache/services/cacheProxy.ts

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import {
+  cacheableMetaOf,
+  resolveCacheableRequirement,
+  type CacheableClassMeta,
+} from "../decorators/cacheableMetadata";
+import {
+  cacheableRedisMetaOf,
+  resolveCacheableRedisRequirement,
+  type CacheableRedisClassMeta,
+} from "../decorators/cacheableRedisMetadata";
+import type { IDistributedCache } from "../distributed/IDistributedCache";
+import type { NamedCacheRegistry } from "../distributed/NamedCacheRegistry";
+import { CacheError } from "../errors/CacheError";
+import type { ICache } from "../ICache";
+import { normalizeCacheKey } from "../internal/normalizeCacheKey";
+import { AutomaticCacheKey } from "../internal/AutomaticCacheKey";
+import { resolveCacheableRedisOptions } from "../internal/resolveCacheableRedisPolicy";
+import {
+  requireCacheSeconds,
+  resolveCacheOptions,
+  type ResolvedCacheableOptions,
+} from "../internal/resolveCachePolicy";
+import type { CacheSetOptions } from "../types/CacheOptions";
+import type { ResolvedCacheableRedisOptions } from "../types/CacheableRedisOptions";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+
+type AnyMethod = (...args: unknown[]) => unknown;
+
+/** Wiring for a caching service proxy. */
+export interface CacheProxyOptions {
+  /** In-memory store for `@Cacheable` methods. */
+  readonly memoryCache: ICache;
+  /** Distributed stores for `@CacheableRedis` methods; absent when no backend configured. */
+  readonly serviceCache?: NamedCacheRegistry<IDistributedCache>;
+  readonly policies: CachePolicyRegistry;
+  readonly className?: string;
+  /** Per-instance namespace; DI supplies it for both singleton and scoped providers. */
+  readonly cacheNamespace?: string;
+}
+
+/** Decorator metadata for a class, read from `Symbol.metadata` once per class. */
+interface ClassCachePlan {
+  readonly memoryMeta: CacheableClassMeta | undefined;
+  readonly distributedMeta: CacheableRedisClassMeta | undefined;
+  readonly hasAny: boolean;
+}
+
+const classPlans = new WeakMap<Function, ClassCachePlan>();
+
+function planFor(ctor: Function): ClassCachePlan {
+  let plan = classPlans.get(ctor);
+  if (plan === undefined) {
+    const memoryMeta = cacheableMetaOf(ctor);
+    const distributedMeta = cacheableRedisMetaOf(ctor);
+    plan = {
+      memoryMeta,
+      distributedMeta,
+      hasAny: memoryMeta !== undefined || distributedMeta !== undefined,
+    };
+    classPlans.set(ctor, plan);
+  }
+  return plan;
+}
+
+function buildMethodCacheKey(
+  className: string,
+  methodName: string | symbol,
+  args: readonly unknown[],
+  automaticKey: AutomaticCacheKey,
+  options: ResolvedCacheableOptions | ResolvedCacheableRedisOptions,
+  cacheNamespace?: string,
+): string | undefined {
+  let userKey: string | undefined;
+  if (typeof options.key === "function") {
+    userKey = options.key(...args);
+  } else if (typeof options.key === "string") {
+    userKey = options.key;
+  } else {
+    userKey = automaticKey.build(args);
+    if (userKey === undefined) return undefined;
+  }
+  // An explicit key is an application-owned sharing contract and preserves the
+  // documented cross-scope/process cache behavior. Implicit keys are isolated
+  // per DI instance: constructor dependencies can carry state absent from args.
+  const namespace = options.key === undefined ? (cacheNamespace ?? "shared") : "explicit-shared";
+  const canonical = JSON.stringify([namespace, className, String(methodName), userKey]);
+  return `svc:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+function wrapMemoryMethod(
+  target: object,
+  methodName: string | symbol,
+  original: AnyMethod,
+  automaticKey: AutomaticCacheKey,
+  cache: ICache,
+  className: string,
+  options: ResolvedCacheableOptions,
+  cacheNamespace?: string,
+): AnyMethod {
+  return (...args) => {
+    if (options.unless !== undefined && options.unless(...args)) {
+      return original.apply(target, args);
+    }
+    const methodKey = buildMethodCacheKey(className, methodName, args, automaticKey, options, cacheNamespace);
+    if (methodKey === undefined) return original.apply(target, args);
+    const key = normalizeCacheKey(methodKey);
+    const setOptions: CacheSetOptions = { ttlSeconds: options.seconds, tags: options.tags };
+    return cache.getOrCreate(key, () => original.apply(target, args), setOptions);
+  };
+}
+
+function wrapDistributedMethod(
+  target: object,
+  methodName: string | symbol,
+  original: AnyMethod,
+  automaticKey: AutomaticCacheKey,
+  registry: NamedCacheRegistry<IDistributedCache> | undefined,
+  className: string,
+  options: ResolvedCacheableRedisOptions,
+  cacheNamespace?: string,
+): AnyMethod {
+  return (...args) => {
+    if (options.unless !== undefined && options.unless(...args)) {
+      return original.apply(target, args);
+    }
+    const methodKey = buildMethodCacheKey(className, methodName, args, automaticKey, options, cacheNamespace);
+    if (methodKey === undefined) return original.apply(target, args);
+    const key = normalizeCacheKey(methodKey);
+    if (registry === undefined) {
+      throw new CacheError(
+        `${className}.${String(methodName)} uses @CacheableRedis but no distributed cache backend is configured — `
+          + 'add redisConnect(redisConfig, { cache: "distributed" }) to your @Infra manifest',
+      );
+    }
+    const cache = registry.resolve(options.connection);
+    return cache.getOrCreateAsync(
+      key,
+      async () => {
+        const result = original.apply(target, args);
+        return result instanceof Promise ? await result : result;
+      },
+      { ttlSeconds: options.seconds, tags: options.tags, lockSeconds: options.lockSeconds },
+    );
+  };
+}
+
+function buildMethod(
+  target: object,
+  prop: string | symbol,
+  original: AnyMethod,
+  automaticKey: AutomaticCacheKey,
+  plan: ClassCachePlan,
+  options: CacheProxyOptions,
+  className: string,
+): AnyMethod {
+  const distributedReq = resolveCacheableRedisRequirement(plan.distributedMeta, prop);
+  const memoryReq = resolveCacheableRequirement(plan.memoryMeta, prop);
+
+  if (distributedReq !== undefined && memoryReq !== undefined) {
+    throw new CacheError(
+      `${className}.${String(prop)} has both @Cacheable and @CacheableRedis — use one decorator per method`,
+    );
+  }
+
+  if (distributedReq !== undefined) {
+    const resolved = resolveCacheableRedisOptions(distributedReq, options.policies);
+    if (resolved.enabled === false || resolved.noStore === true) {
+      return original.bind(target);
+    }
+    const seconds = requireCacheSeconds(resolved, `@CacheableRedis on ${className}.${String(prop)}`);
+    return wrapDistributedMethod(
+      target,
+      prop,
+      original,
+      automaticKey,
+      options.serviceCache,
+      className,
+      { ...resolved, seconds },
+      options.cacheNamespace,
+    );
+  }
+
+  if (memoryReq !== undefined) {
+    const resolved = resolveCacheOptions(memoryReq, options.policies);
+    if (resolved.enabled === false || resolved.noStore === true) {
+      return original.bind(target);
+    }
+    const seconds = requireCacheSeconds(resolved, `@Cacheable on ${className}.${String(prop)}`);
+    return wrapMemoryMethod(
+      target,
+      prop,
+      original,
+      automaticKey,
+      options.memoryCache,
+      className,
+      { ...resolved, seconds },
+      options.cacheNamespace,
+    );
+  }
+
+  return original.bind(target);
+}
+
+/**
+ * Wraps a service instance so `@Cacheable` methods use {@link ICache} and
+ * `@CacheableRedis` methods use the distributed {@link NamedCacheRegistry}.
+ * Returns the instance unchanged when it carries no cache metadata.
+ */
+export function wrapCachedService<T extends object>(target: T, options: CacheProxyOptions): T {
+  const ctor = target.constructor;
+  const plan = planFor(ctor);
+  if (!plan.hasAny) {
+    return target;
+  }
+  const className = options.className ?? ctor.name;
+  const methodCache = new Map<string | symbol, AnyMethod>();
+  const automaticKey = new AutomaticCacheKey();
+
+  const handler: ProxyHandler<T> = {
+    get(obj, prop) {
+      if (prop === "constructor") {
+        return Reflect.get(obj, prop, obj);
+      }
+      const value = Reflect.get(obj, prop, obj);
+      if (typeof value !== "function" || (typeof prop !== "string" && typeof prop !== "symbol")) {
+        return value;
+      }
+      const memoized = methodCache.get(prop);
+      if (memoized !== undefined) {
+        return memoized;
+      }
+      const wrapped = buildMethod(obj, prop, value as AnyMethod, automaticKey, plan, options, className);
+      methodCache.set(prop, wrapped);
+      return wrapped;
+    },
+    set(obj, prop, value) {
+      return Reflect.set(obj, prop, value, obj);
+    },
+  };
+
+  return new Proxy(target, handler);
+}

package/core/cache/tokens/CACHE_POLICIES.ts

@@ -0,0 +1,5 @@
+import { createToken } from "../../di";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+
+/** Named cache policies from cache module configuration, e.g. `memory({ policies })`. */
+export const CACHE_POLICIES = createToken<CachePolicyRegistry>("CachePolicies");

package/core/cache/tokens/DISTRIBUTED_CACHE.ts

@@ -0,0 +1,30 @@
+import { createToken, registerModuleOwnedContributionValidator } from "../../di";
+import { CacheError } from "../errors/CacheError";
+import type { CachedHttpPayload } from "../http/CachedHttpPayload";
+import type { DistributedCacheStores } from "../distributed/DistributedCacheStores";
+import type { IDistributedCache } from "../distributed/IDistributedCache";
+import type { NamedCacheRegistry } from "../distributed/NamedCacheRegistry";
+
+/** One global backend per application; named connections belong to that backend. */
+export const DISTRIBUTED_CACHE_BACKEND = createToken<DistributedCacheStores>("DistributedCacheStores");
+
+registerModuleOwnedContributionValidator((snapshot) => {
+  const count = snapshot.countProviders(DISTRIBUTED_CACHE_BACKEND);
+  if (count > 1) {
+    throw new CacheError(
+      `Only one distributed cache backend may be registered per application; found ${count}. ` +
+      'Enable cache: "distributed" on one Redis connector, or register one custom backend. ' +
+      "Other Redis connectors may use distinct client tokens without cache mode.",
+    );
+  }
+});
+
+/** Named HTTP output payload stores (`@OutputRedisCache`). */
+export const DISTRIBUTED_OUTPUT_CACHE = createToken<NamedCacheRegistry<IDistributedCache<CachedHttpPayload>>>(
+  "DistributedOutputCacheRegistry",
+);
+
+/** Named service value stores (`@CacheableRedis`). */
+export const DISTRIBUTED_SERVICE_CACHE = createToken<NamedCacheRegistry<IDistributedCache>>(
+  "DistributedServiceCacheRegistry",
+);

package/core/cache/types/CacheEntry.ts

@@ -0,0 +1,7 @@
+/** One cache entry returned by {@link ICache.list}. */
+export interface CacheEntry<TValue> {
+  readonly key: string;
+  readonly value: TValue;
+  /** Expiry Unix timestamp (ms); absent means the entry never expires. */
+  readonly expiresAt?: number;
+}

package/core/cache/types/CacheOptions.ts

@@ -0,0 +1,60 @@
+import { createOptionsToken } from "../../di";
+
+/** In-memory cache options. */
+export interface CacheOptions {
+  /** Maximum number of entries; the LRU entry is evicted when full. */
+  readonly maxEntries?: number;
+  /** Maximum number of factories running at once; 1024 by default.
+   * When full, a new cache miss gets CacheCapacityError before the factory starts.
+   */
+  readonly maxInFlight?: number;
+  /** Default TTL for {@link ICache.set} (seconds). */
+  readonly defaultTtlSeconds?: number;
+  /** Maximum key length (characters). 256 by default. */
+  readonly maxKeyLength?: number;
+  /** Size limit of a string value (UTF-8 bytes). Unset means no limit. */
+  readonly maxValueBytes?: number;
+}
+
+/** Per-entry write options. */
+export interface CacheSetOptions {
+  /** TTL of this entry (seconds); overrides the default from {@link CacheOptions}. */
+  readonly ttlSeconds?: number;
+  /** Tags for group invalidation via {@link ICache.evictByTag}. */
+  readonly tags?: readonly string[];
+}
+
+export const DEFAULT_MAX_KEY_LENGTH = 256;
+export const DEFAULT_MAX_IN_FLIGHT = 1024;
+
+/** DI token of the validated cache options. */
+export const CACHE_OPTIONS = createOptionsToken<CacheOptions>("Cache");
+
+export function validateCacheOptions(options: CacheOptions): readonly string[] {
+  const issues: string[] = [];
+  if (options.maxInFlight !== undefined && (!Number.isSafeInteger(options.maxInFlight) || options.maxInFlight < 1)) {
+    issues.push("maxInFlight must be a positive safe integer");
+  }
+  if (options.maxEntries !== undefined && (!Number.isInteger(options.maxEntries) || options.maxEntries < 1)) {
+    issues.push("maxEntries must be a positive integer");
+  }
+  if (
+    options.defaultTtlSeconds !== undefined
+    && (!Number.isFinite(options.defaultTtlSeconds) || options.defaultTtlSeconds <= 0)
+  ) {
+    issues.push("defaultTtlSeconds must be a positive number");
+  }
+  if (
+    options.maxKeyLength !== undefined
+    && (!Number.isInteger(options.maxKeyLength) || options.maxKeyLength < 1)
+  ) {
+    issues.push("maxKeyLength must be a positive integer");
+  }
+  if (
+    options.maxValueBytes !== undefined
+    && (!Number.isInteger(options.maxValueBytes) || options.maxValueBytes < 1)
+  ) {
+    issues.push("maxValueBytes must be a positive integer");
+  }
+  return issues;
+}

package/core/cache/types/CachePolicy.ts

@@ -0,0 +1,74 @@
+import type { HttpContext } from "../../http";
+
+/** Shared cache policy fields for HTTP output cache and service method cache. */
+export interface CachePolicyBase {
+  /** TTL in seconds. */
+  readonly seconds?: number;
+  /** Tags for group invalidation via {@link ICache.evictByTag}. */
+  readonly tags?: readonly string[];
+  /** When false, caching is skipped (metadata kept). Default true. */
+  readonly enabled?: boolean;
+  /** Disable caching for this entry. */
+  readonly noStore?: boolean;
+}
+
+/** Named policy registry entry (module-level defaults). */
+export type CachePolicy = CachePolicyBase & OutputCachePolicyFields & CacheablePolicyFields;
+
+/** HTTP output cache options (ASP.NET Core Output Cache). */
+export interface OutputCachePolicyFields {
+  /** Maximum response body buffered for one cache entry. Default 16 MiB; 0 disables the limit. */
+  readonly maxBodyBytes?: number;
+  /** Total time allowed to materialize a response body. Default 5000ms; 0 disables the timeout. */
+  readonly bodyReadTimeoutMs?: number;
+  readonly varyByQuery?: readonly string[] | "*";
+  readonly varyByRoute?: readonly string[];
+  readonly varyByHeader?: readonly string[];
+  /** Separate cache entry per authenticated user (`sub`). */
+  readonly varyByUser?: boolean;
+  /** Separate cache entry per JWT claim value. */
+  readonly varyByClaim?: string;
+  /** HTTP methods allowed for caching (default GET, HEAD). */
+  readonly methods?: readonly string[];
+  /** Status codes to store (default 200). */
+  readonly statusCodes?: readonly number[];
+  /** Skip cache when the request is authenticated. */
+  readonly unlessAuthenticated?: boolean;
+  /**
+   * Explicitly share one server/client cache entry with authenticated callers
+   * when the response is guaranteed not to depend on the principal.
+   * Default false: optional-auth requests bypass a non-personalized policy.
+   */
+  readonly allowAuthenticatedShared?: boolean;
+  /** Client/proxy Cache-Control headers (Response Cache layer). */
+  readonly clientCache?: ClientCacheOptions;
+  /** Custom predicate; return false to skip cache read/write. */
+  readonly when?: (ctx: HttpContext) => boolean | Promise<boolean>;
+}
+
+/** Service method cache options (IMemoryCache / @Cacheable). */
+export interface CacheablePolicyFields {
+  /** Static key prefix or builder from method arguments. */
+  readonly key?: string | ((...args: readonly unknown[]) => string);
+  /** Skip cache when predicate returns true. */
+  readonly unless?: (...args: readonly unknown[]) => boolean;
+}
+
+export interface ClientCacheOptions {
+  readonly maxAge?: number;
+  readonly public?: boolean;
+  readonly private?: boolean;
+  readonly noCache?: boolean;
+}
+
+/** Options for {@link OutputCache} decorator. */
+export type OutputCacheOptions = CachePolicyBase & OutputCachePolicyFields & {
+  readonly policy?: string;
+};
+
+/** Options for {@link Cacheable} decorator. */
+export type CacheableOptions = CachePolicyBase & CacheablePolicyFields & {
+  readonly policy?: string;
+};
+
+export type CachePolicyRegistry = Readonly<Record<string, CachePolicy>>;

package/core/cache/types/CacheableRedisOptions.ts

@@ -0,0 +1,23 @@
+import type { CachePolicyBase, CacheablePolicyFields } from "./CachePolicy";
+
+/** Redis-specific options for {@link CacheableRedis}. */
+export interface CacheableRedisPolicyFields {
+  /** Named connection of the distributed backend. Default `default`. */
+  readonly connection?: string;
+  /** Override distributed lock TTL for anti-stampede across pods. */
+  readonly lockSeconds?: number;
+}
+
+/** Options for {@link CacheableRedis} decorator. */
+export type CacheableRedisOptions = CachePolicyBase &
+  CacheablePolicyFields &
+  CacheableRedisPolicyFields & {
+    readonly policy?: string;
+  };
+
+export type ResolvedCacheableRedisOptions = CacheableRedisOptions & {
+  readonly seconds: number;
+  readonly connection: string;
+  /** Lock TTL override; when absent the store's default is used. */
+  readonly lockSeconds?: number;
+};

package/core/cache/types/OutputRedisCacheOptions.ts

@@ -0,0 +1,25 @@
+import type { CachePolicyBase, OutputCachePolicyFields } from "./CachePolicy";
+
+/** Redis-specific options for {@link OutputRedisCache}. */
+export interface OutputRedisCachePolicyFields {
+  /** Named connection of the distributed backend. Default `default`. */
+  readonly connection?: string;
+  /** Extra key prefix for this route (after connection prefix). */
+  readonly keyPrefix?: string;
+  /** Override connection lock TTL for anti-stampede across pods. */
+  readonly lockSeconds?: number;
+}
+
+/** Options for {@link OutputRedisCache} decorator. */
+export type OutputRedisCacheOptions = CachePolicyBase &
+  OutputCachePolicyFields &
+  OutputRedisCachePolicyFields & {
+    readonly policy?: string;
+  };
+
+export type ResolvedOutputRedisCacheOptions = OutputRedisCacheOptions & {
+  readonly seconds: number;
+  readonly connection: string;
+  /** Lock TTL override; when absent the store's default is used. */
+  readonly lockSeconds?: number;
+};

package/core/di/README.md

@@ -0,0 +1,104 @@
+# DI Folder Map
+
+A map of the `src/bazis/core/di` structure. The core's responsibility boundaries and
+contracts are described in [MODULE.md](MODULE.md).
+
+## Public API
+
+- `index.ts`: the single public DI entry point.
+- `MODULE.md`: the contracts, boundaries and checks of the DI core.
+
+## Container core
+
+- `ServiceProvider.ts`: resolve coordination, dependency plans and object creation.
+- `ServiceCollection.ts`: service registration.
+- `ServiceScope.ts`: scoped resolve and scoped dispose.
+- `container.ts`: a compatible alias wrapper over `ServiceProvider`.
+- `token.ts`: DI tokens (`createToken`, open generic family).
+
+## Internals (do not use directly)
+
+- `internal/`:
+  - `ServiceRegistry.ts`: registration identity, keyed lookup and generic materialization.
+  - `ResolutionTracker.ts`: active object creations, the wait graph and cycle detection.
+  - `ScopeLifecycle.ts`: ownership of scopes and resources, lifetime rules and dispose completion.
+  - `classDeps.ts`: the runtime map of class deps.
+  - `ResolutionScopeState.ts`: root/scope state.
+  - `ServiceRegistration.ts`: the internal registration record.
+  - `ResolutionPlan.ts`: the normalized dependency list of a provider (hot-path cache).
+  - `NamedTokenIndex.ts`: the "type name → token" index for name-based auto deps.
+  - `GraphValidator.ts`: build-time graph validation (cycles, missing/captive deps, class arity).
+  - `OpenGenericRegistration.ts`: the internal model of an open generic registration.
+  - `disposal.ts`: the dispose/disposeAsync helper.
+
+## Module layer
+
+- `module/DI.ts`: low-level provider constructors.
+- `module/shortcuts.ts`: the short API (`singleton/scoped/transient`).
+- `module/createContainer.ts`: builds a container from modules.
+- `module/encapsulation.ts`: build-time check of module isolation (`exports`).
+- `module/ModuleRegistrar.ts`: the helper registrar for `configure(di)`.
+- `module/types/`: module contracts (`BazisModule`, `DiRegistrar`).
+- `module/autoDeps.ts`: picks up deps from the generated map.
+
+## Providers and types
+
+- `provider/`:
+  - `index.ts`: provider exports.
+  - `providerGuards.ts`: type guards.
+  - `types/`: all provider contracts (`Provider`, `ClassProvider`, `FactoryProvider`, ...).
+
+## Errors
+
+- `errors/`: all DI errors (one class = one file).
+
+## Extensions
+
+- `extensions/`: options, hosted services, application startup and object creation with manual arguments.
+- `extensions/options.ts`: options + validated options (`addValidatedOptions`, fail-fast at startup).
+- `extensions/options-reloadable.ts`: reloadable options (`OptionsMonitor`/`OptionsSnapshot`, `addReloadableOptions`), the counterpart of .NET `IOptionsMonitor`/`IOptionsSnapshot`.
+- `extensions/application.ts`: `Application`/`runApplication`: starts hosted services and shuts down gracefully.
+- `extensions/activator.ts`: `createInstance`: creates an object from a mix of DI dependencies and manual arguments (the counterpart of .NET `ActivatorUtilities`).
+
+## Codegen
+
+- `src/generated/bazis/deps.ts` in the application: the generated class dependency map.
+- `../scripts/di-generate.ts`: the map generator.
+
+> ⚠️ Do not edit `src/generated/bazis/deps.ts` by hand.
+
+## Structure rules
+
+- One class, one file.
+- Types live next to their domain in `types/`.
+- External code imports DI through `bazis` for the common path or through
+  `bazis/core/di` for targeted access.
+- `internal/` is the container's private layer.
+
+## Style Rule (DI usage)
+
+- By default use only the short shortcuts:
+  - `singleton(...)`
+  - `scoped(...)`
+  - `transient(...)`
+- Use the low-level path (`DI.classProvider(...)`, `DI.factoryProvider(...)`) only for rare cases that really need manual setup.
+
+## Contributing Checklist
+
+Before committing DI changes, check:
+
+1. **File structure**
+   - runtime classes in domain folders (`module/`, `errors/`, `extensions/`, the root core);
+   - internal service details only in `internal/`;
+   - type-only contracts in the nearest `types/`.
+
+2. **Public API**
+   - if you add an external API, export it from `src/bazis/core/di/index.ts`;
+   - do not export `internal/*` in the external contract.
+
+3. **Codegen**
+   - set up the pinned Bun as in the [toolchain notes](../../../../toolchain/README.md);
+   - after changing service constructors run `./scripts/bazis-bun run di:generate`;
+   - do not edit `src/generated/bazis/` by hand;
+   - run tests and builds through `./scripts/bazis-bun run test` and
+     `./scripts/bazis-bun run build:bin` (they run the generation).