bazis 0.96.1

package/core/infra/Infra.ts

@@ -0,0 +1,158 @@
+import {
+  DI,
+  HOSTED_SERVICE,
+  Module,
+  createToken,
+  createModuleOwnedMetadataChannel,
+  registerModuleOwnedProviderContributor,
+  registerModuleOwnedContributionValidator,
+  type ModuleConfig,
+  type ModuleExport,
+  type BazisModuleRef,
+  type ProviderDefinition,
+} from "../di";
+import { ConfigRegistry, HEALTH_CHECK } from "../kernel";
+import { InfraError, type InfraConnector } from "./InfraConnector";
+import { InfraLifecycle } from "./InfraLifecycle";
+
+/**
+ * Infrastructure manifest: a readable "logical name → connector" map.
+ * The key (`db`, `cache`, `search`) is the instance name: it appears in the
+ * health check (`infra:db`) and in diagnostics, so the manifest file reads as
+ * the application's connection spec.
+ */
+export type InfraManifest = Readonly<Record<string, InfraConnector>>;
+
+const instances = new WeakMap<ProviderDefinition, { name: string; token: InfraConnector["token"] }>();
+const instanceChannel = createModuleOwnedMetadataChannel<{ name: string; token: InfraConnector["token"] }>("infra.instances");
+registerModuleOwnedProviderContributor((metadata, context) => {
+  for (const provider of metadata.providers ?? []) {
+    const instance = instances.get(provider);
+    if (instance) context.addMetadata(instanceChannel, instance);
+  }
+});
+registerModuleOwnedContributionValidator((snapshot) => {
+  const owners = new Map<InfraConnector["token"], string>();
+  for (const { ownerName, payload } of snapshot.getMetadataContributions(instanceChannel)) {
+    const name = `${ownerName}:${payload.name}`;
+    const previous = owners.get(payload.token);
+    if (previous !== undefined) {
+      throw new InfraError(`Infra instances "${previous}" and "${name}" share the same connector token; each instance needs a distinct token.`);
+    }
+    owners.set(payload.token, name);
+  }
+});
+
+function buildInfraDefinitions(manifest: InfraManifest): {
+  providers: ProviderDefinition[];
+  exports: ModuleExport[];
+  config: ModuleConfig[];
+} {
+  const providers: ProviderDefinition[] = [];
+  const exports: ModuleExport[] = [];
+  const config: ModuleConfig[] = [];
+  const seenConfig = new Set<ModuleConfig>();
+  // One token = one singleton client. Two instances under one token would give
+  // a shared client with two lifecycles (double connect/dispose), so fail loudly.
+  const seenTokens = new Map<InfraConnector["token"], string>();
+
+  for (const [name, connector] of Object.entries(manifest)) {
+    if (!name.trim() || name !== name.trim()) throw new InfraError("Infra instance names must be non-empty and trimmed.");
+    if (connector.phase !== undefined && !Number.isSafeInteger(connector.phase)) {
+      throw new InfraError(`Infra instance "${name}": phase must be a finite safe integer.`);
+    }
+    const previous = seenTokens.get(connector.token);
+    if (previous !== undefined) {
+      throw new InfraError(
+        `Infra manifest: instances "${previous}" and "${name}" share the same connector token; each instance needs a distinct token.`,
+      );
+    }
+    seenTokens.set(connector.token, name);
+
+    const connectorConfigs =
+      connector.config === undefined ? [] : Array.isArray(connector.config) ? connector.config : [connector.config];
+    for (let index = 0; index < connectorConfigs.length; index += 1) {
+      const item = connectorConfigs[index] as ModuleConfig;
+      if (!seenConfig.has(item)) {
+        seenConfig.add(item);
+        config.push(item);
+      }
+    }
+
+    // DI registers the owner before the client: even an early resolution or
+    // a failing factory elsewhere cannot leave a created resource without cleanup.
+    const ownerToken = createToken<InfraLifecycle<unknown>>(`infra:${name}:lifetime`);
+    const owner = DI.singleton(DI.factoryProviderWithResolver(ownerToken, [], (resolver) =>
+      new InfraLifecycle(name, connector, undefined, resolver.has(ConfigRegistry) ? resolver.resolve(ConfigRegistry) : undefined)));
+    instances.set(owner, { name, token: connector.token });
+    providers.push(owner);
+    providers.push(
+      DI.singleton(DI.externallyOwned(DI.factoryProvider(connector.token, [ownerToken], (lifetime) => lifetime.getClient()))),
+    );
+
+    // 2. Lifecycle: opens/closes the connection in the kernel phases.
+    providers.push(
+      DI.singleton(
+        DI.factoryProvider(HOSTED_SERVICE, [ownerToken], (lifetime) => lifetime),
+      ),
+    );
+
+    // 3. Health check: only if the connector supports it.
+    if (connector.healthCheck) {
+      const healthCheck = connector.healthCheck.bind(connector);
+      providers.push(
+        DI.singleton(
+          DI.factoryProvider(HEALTH_CHECK, [connector.token], (client) => ({
+            name: `infra:${name}`,
+            check: async (signal?: AbortSignal) => ({ healthy: await healthCheck(client, signal) }),
+          })),
+        ),
+      );
+    }
+
+    exports.push(connector.token);
+
+    // 4. Extra connector providers (for example a distributed cache on top of Redis).
+    if (connector.providers !== undefined) {
+      providers.push(...connector.providers);
+    }
+    if (connector.exports !== undefined) {
+      exports.push(...connector.exports);
+    }
+  }
+
+  return { providers, exports, config };
+}
+
+/**
+ * Dynamic infrastructure module (a plain metadata object): the same as
+ * `@Infra`, but without a class. Handy for `imports` or `runApp({ infra })`.
+ */
+export function infraModule(manifest: InfraManifest): BazisModuleRef {
+  const { providers, exports, config } = buildInfraDefinitions(manifest);
+  return { global: true, providers, exports, config };
+}
+
+/**
+ * Infrastructure decorator. Puts the metadata of a regular **global module**
+ * on the class, so the class becomes a valid `BazisModuleRef`: it can be passed
+ * to `runApp({ infra: AppInfra })` or to `imports`.
+ *
+ * The class stays pure metadata (like `@Module`) and is **never instantiated**:
+ * only the clients it lists live and hold state.
+ *
+ * ```ts
+ * @Infra({
+ *   db: postgres(dbConfig),
+ *   cache: redisConnect(redisConfig),
+ *   search: openSearchConnect(searchConfig),
+ * })
+ * export class AppInfra {}
+ * ```
+ */
+export function Infra(manifest: InfraManifest) {
+  const { providers, exports, config } = buildInfraDefinitions(manifest);
+  return (target: abstract new (...args: never) => unknown, _context: ClassDecoratorContext): void => {
+    Module({ global: true, providers, exports, config })(target, _context);
+  };
+}

package/core/infra/InfraConnector.ts

@@ -0,0 +1,86 @@
+import type { InjectionToken, ModuleConfig, ModuleExport, ProviderDefinition } from "../di";
+import { redactSensitiveText } from "../../library/redaction";
+import type { ConfigRegistry } from "../kernel/config/ConfigRegistry";
+
+/**
+ * Infrastructure connector contract: one shape for "a connection to something
+ * external" (a database, cache, search engine, bus). A connector encapsulates
+ * four things that would otherwise be hand-written in every integration module:
+ *
+ * 1. **creating the client** from the subsystem config ({@link create}): the
+ *    connector gets a typed `defineConfig` object and reads the declared keys
+ *    itself (secrets are revealed at the boundary, not read from `process.env`);
+ * 2. **opening the connection** at application start ({@link connect});
+ * 3. **closing the connection** at shutdown ({@link dispose}): graceful shutdown;
+ * 4. **health check** ({@link healthCheck}) for the built-in `/health`.
+ *
+ * The {@link Infra} decorator expands a set of connectors into a regular global
+ * module: the client is registered as a singleton under its {@link token}, the
+ * lifecycle as a `HOSTED_SERVICE` (the default phase is negative so that
+ * infrastructure starts before the servers), the health check as `HEALTH_CHECK`.
+ * The connector implementation defines the connection type; there is no common
+ * list of types. The manifest entry name is used for diagnostics; the client is
+ * identified by its DI token.
+ *
+ * @typeParam TClient Type of the client injected in the application by {@link token}.
+ */
+export interface InfraConnector<TClient = unknown> {
+  /** Token under which the client is available for injection into application services. */
+  readonly token: InjectionToken<TClient>;
+
+  /**
+   * Configs owned by the connector. `@Infra` lifts them into the module
+   * metadata, and `runApp` validates them before the application starts.
+   */
+  readonly config?: ModuleConfig | readonly ModuleConfig[];
+
+  /**
+   * Start phase of the hosted lifecycle. Lower starts earlier and stops later.
+   * Defaults to `-100`, so infrastructure is ready before the servers.
+   */
+  readonly phase?: number;
+
+  /**
+   * Creates the client (**not** connected yet: the connection is opened in
+   * {@link connect}). The connector keeps the subsystem config itself (it was
+   * passed to its factory, e.g. `postgres(dbConfig)`); this is where
+   * credentials are read and required keys are validated.
+   */
+  create(configs?: ConfigRegistry): TClient;
+
+  /** Opens the connection / warms up the pool. Called at application start. */
+  connect(client: TClient, signal?: AbortSignal): Promise<void> | void;
+
+  /** Closes the connection / releases resources. Called at shutdown. */
+  dispose(client: TClient): Promise<void> | void;
+
+  /**
+   * Connection liveness check for `/health`. If not set, no health check is
+   * registered for this connector.
+   */
+  healthCheck?(client: TClient, signal?: AbortSignal): Promise<boolean> | boolean;
+
+  /**
+   * Extra providers the connector adds to the infrastructure module besides
+   * the client itself (for example `redisConnect(cfg, { cache: "distributed" })`
+   * publishes a distributed cache backend on top of the client). Usually a
+   * `factoryProvider` that refers to {@link token}. Exposed through {@link exports}.
+   */
+  readonly providers?: readonly ProviderDefinition[];
+
+  /** Tokens from {@link providers} to make visible to the application. */
+  readonly exports?: readonly ModuleExport[];
+}
+
+/** Infrastructure configuration/connection error. */
+export class InfraError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "InfraError";
+  }
+}
+
+/** Safely extracts the error text (in case a non-`Error` was thrown). */
+export function errorMessage(error: unknown): string {
+  return redactSensitiveText(error instanceof Error ? error.message : String(error));
+}

package/core/infra/InfraLifecycle.ts

@@ -0,0 +1,86 @@
+import type { HostedService } from "../di";
+import { InfraError, type InfraConnector } from "./InfraConnector";
+import { bindConnectorLifecycle } from "./connectorIdentity";
+import { awaitAbortable } from "../kernel/internal/awaitAbortable";
+import type { ConfigRegistry } from "../kernel/config/ConfigRegistry";
+
+const DEFAULT_INFRA_PHASE = -100;
+
+/**
+ * Hosted service that wraps an {@link InfraConnector} into the kernel
+ * lifecycle: opens the connection at start and closes it at shutdown. One
+ * lifecycle per connector. DI owns the lifecycle even when the client is
+ * resolved before start.
+ *
+ * The phase comes from the connector (negative by default), so connections
+ * come up before the HTTP server and background tasks and go down after them.
+ */
+export class InfraLifecycle<TClient> implements HostedService {
+  public readonly phase: number;
+  private client?: TClient;
+  private created = false;
+  private disposed = false;
+  private startPromise?: Promise<void>;
+  private disposePromise?: Promise<void>;
+
+  public constructor(
+    private readonly name: string,
+    private readonly connector: InfraConnector<TClient>,
+    client?: TClient,
+    private readonly configs?: ConfigRegistry,
+  ) {
+    this.client = client;
+    this.created = client !== undefined;
+    this.phase = connector.phase ?? DEFAULT_INFRA_PHASE;
+    bindConnectorLifecycle(connector, this);
+  }
+
+  public getClient(): TClient {
+    if (this.disposed) throw new InfraError(`Infra connector "${this.name}" is already disposed.`);
+    if (!this.created) {
+      this.client = this.connector.create(this.configs);
+      this.created = true;
+    }
+    return this.client as TClient;
+  }
+
+  public start(signal?: AbortSignal): Promise<void> {
+    this.startPromise ??= Promise.resolve().then(() => this.connect(signal));
+    return this.startPromise;
+  }
+
+  private async connect(signal?: AbortSignal): Promise<void> {
+    try {
+      signal?.throwIfAborted();
+      const client = this.getClient();
+      await awaitAbortable(Promise.resolve(this.connector.connect(client, signal)), signal);
+    } catch (error) {
+      try {
+        await this.dispose();
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          `Infra connector "${this.name}" failed to start and rollback also failed.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  public stop(): Promise<void> {
+    return this.dispose();
+  }
+
+  public dispose(): Promise<void> {
+    this.disposed = true;
+    this.disposePromise ??= Promise.resolve().then(async () => {
+      if (this.created) await this.connector.dispose(this.client as TClient);
+    });
+    return this.disposePromise;
+  }
+
+  /** Infrastructure instance name (the key in the `@Infra` manifest), for diagnostics. */
+  public get instanceName(): string {
+    return this.name;
+  }
+}

package/core/infra/cache/RedisDistributedCacheBackend.ts

@@ -0,0 +1,88 @@
+import {
+  DistributedCache,
+  NamedCacheRegistry,
+  httpPayloadCacheCodec,
+  jsonCacheCodec,
+  type CachedHttpPayload,
+  type DistributedCacheStores,
+  type DistributedCachePing,
+  type IDistributedCache,
+} from "../../cache";
+import type { RedisCommandClient } from "./RedisDistributedCacheDriver";
+import { RedisDistributedCacheDriver } from "./RedisDistributedCacheDriver";
+
+/** Tuning of the Redis-backed distributed cache (all optional). */
+export interface RedisDistributedCacheTuning {
+  /** Connection name for the decorators (`connection`). Defaults to `"default"`. */
+  readonly connection?: string;
+  /** Prefix of all keys; isolates the application cache in a shared Redis. */
+  readonly keyPrefix?: string;
+  /** TTL of the anti-stampede lock on a miss (seconds). */
+  readonly defaultLockSeconds?: number;
+  /** Maximum key length. */
+  readonly maxKeyLength?: number;
+  /** Size limit of a serialized value (bytes); `set` degrades gracefully. */
+  readonly maxValueBytes?: number;
+  /** Polling interval (ms) while waiting for another worker's result. */
+  readonly pollIntervalMs?: number;
+}
+
+const DEFAULT_KEY_PREFIX = "bazis:cache:";
+const DEFAULT_LOCK_SECONDS = 10;
+const DEFAULT_CONNECTION = "default";
+
+/**
+ * Distributed cache backend on top of one Redis connection. Builds two stores
+ * (HTTP responses and method values) with separate namespaces and codecs and
+ * exposes them as a {@link NamedCacheRegistry}. The `redisConnect(...)`
+ * connector opens and closes the connection.
+ */
+export class RedisDistributedCacheBackend implements DistributedCacheStores {
+  public readonly connectionNames: readonly string[];
+  public readonly outputCache: NamedCacheRegistry<IDistributedCache<CachedHttpPayload>>;
+  public readonly serviceCache: NamedCacheRegistry<IDistributedCache>;
+
+  private readonly connection: string;
+
+  public constructor(
+    private readonly client: RedisCommandClient,
+    tuning: RedisDistributedCacheTuning = {},
+  ) {
+    this.connection = tuning.connection ?? DEFAULT_CONNECTION;
+    this.connectionNames = [this.connection];
+
+    const driver = new RedisDistributedCacheDriver(client);
+    const base = {
+      connectionName: this.connection,
+      keyPrefix: tuning.keyPrefix ?? DEFAULT_KEY_PREFIX,
+      defaultLockSeconds: tuning.defaultLockSeconds ?? DEFAULT_LOCK_SECONDS,
+      maxKeyLength: tuning.maxKeyLength,
+      maxValueBytes: tuning.maxValueBytes,
+      pollIntervalMs: tuning.pollIntervalMs,
+    };
+
+    const output = new DistributedCache<CachedHttpPayload>(driver, httpPayloadCacheCodec, {
+      ...base,
+      namespace: "out:",
+    });
+    const service = new DistributedCache(driver, jsonCacheCodec, { ...base, namespace: "svc:" });
+
+    this.outputCache = new NamedCacheRegistry(new Map([[this.connection, output]]));
+    this.serviceCache = new NamedCacheRegistry(new Map([[this.connection, service]]));
+  }
+
+  public async ping(): Promise<readonly DistributedCachePing[]> {
+    try {
+      const reply = await this.client.send("PING", []);
+      return [{ connection: this.connection, healthy: reply === "PONG" }];
+    } catch (error) {
+      return [
+        {
+          connection: this.connection,
+          healthy: false,
+          detail: error instanceof Error ? error.message : String(error),
+        },
+      ];
+    }
+  }
+}

package/core/infra/cache/RedisDistributedCacheDriver.ts

@@ -0,0 +1,186 @@
+import type { DistributedCacheDriver, DistributedCacheFencedWrite } from "../../cache";
+
+/**
+ * The narrow Redis client contract the driver needs. Bun `RedisClient`
+ * satisfies it structurally, and the interface lets the driver be tested
+ * without a live server (any fake implementing these five methods).
+ */
+export interface RedisCommandClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...options: string[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  send(command: string, args: string[]): Promise<unknown>;
+}
+
+/**
+ * Releases the lock only if it still holds our fencing token (atomically).
+ * Otherwise a slow worker could delete a lock already re-acquired by another.
+ */
+const RELEASE_LOCK_SCRIPT =
+  "if redis.call('get', KEYS[1]) == ARGV[1] then redis.call('del', KEYS[1]); if KEYS[2] then redis.call('del', KEYS[2]) end; return 1 else return 0 end";
+
+const DELETE_IF_VALUE_SCRIPT =
+  "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end";
+
+const INVALIDATE_SCRIPT =
+  "redis.call('incr', KEYS[1]); return redis.call('del', KEYS[2])";
+
+const INVALIDATE_WHILE_LOCKED_SCRIPT =
+  "if redis.call('exists', KEYS[3]) == 1 then local lockTtl = redis.call('pttl', KEYS[3]); redis.call('incr', KEYS[1]); if lockTtl > 0 then redis.call('pexpire', KEYS[1], lockTtl + 60000) end else redis.call('del', KEYS[1]) end; return redis.call('del', KEYS[2])";
+
+const ADVANCE_TAG_GENERATION_SCRIPT =
+  "local next = redis.call('incr', KEYS[1]); redis.call('sadd', KEYS[2], tostring(next - 1)); return next";
+
+const ADD_TAG_MEMBERS_SCRIPT = `
+local previousTtl = redis.call('ttl', KEYS[1])
+for i = 2, #ARGV do redis.call('sadd', KEYS[1], ARGV[i]) end
+if ARGV[1] == '' then
+  redis.call('persist', KEYS[1])
+elseif previousTtl == -2 or (previousTtl >= 0 and previousTtl < tonumber(ARGV[1])) then
+  redis.call('expire', KEYS[1], ARGV[1])
+end
+return 1`;
+
+const WRITE_IF_LOCK_OWNER_SCRIPT = `
+if redis.call('get', KEYS[1]) ~= ARGV[1] then return 0 end
+local versionCount = tonumber(ARGV[4])
+local tagCount = tonumber(ARGV[5])
+for i = 1, versionCount do
+  local actual = redis.call('get', KEYS[2 + i])
+  local expected = ARGV[5 + i]
+  if expected == '__BAZIS_MISSING_VERSION__' then
+    if actual then return 0 end
+  elseif actual ~= expected then
+    return 0
+  end
+end
+if ARGV[3] == '' then
+  redis.call('set', KEYS[2], ARGV[2])
+else
+  redis.call('set', KEYS[2], ARGV[2], 'EX', ARGV[3])
+end
+for i = 1, tagCount do
+  local tagKey = KEYS[2 + versionCount + i]
+  local previousTtl = redis.call('ttl', tagKey)
+  redis.call('sadd', tagKey, ARGV[5 + versionCount + i])
+  if ARGV[3] == '' then
+    redis.call('persist', tagKey)
+  elseif previousTtl == -2 or (previousTtl >= 0 and previousTtl < tonumber(ARGV[3])) then
+    redis.call('expire', tagKey, ARGV[3])
+  end
+end
+return 1`;
+
+/**
+ * {@link DistributedCacheDriver} implementation on top of Redis/Valkey (the
+ * native Bun `RedisClient`). Low-level primitives only: the whole cache policy
+ * (anti-stampede, tags, limits) lives in the kernel `DistributedCache`.
+ */
+export class RedisDistributedCacheDriver implements DistributedCacheDriver {
+  public constructor(private readonly client: RedisCommandClient) {}
+
+  public read(key: string): Promise<string | null> {
+    return this.client.get(key);
+  }
+
+  public async write(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    if (ttlSeconds !== undefined) {
+      await this.client.set(key, value, "EX", String(ttlSeconds));
+    } else {
+      await this.client.set(key, value);
+    }
+  }
+
+  public delete(keys: readonly string[]): Promise<number> {
+    if (keys.length === 0) {
+      return Promise.resolve(0);
+    }
+    return this.client.del(...keys);
+  }
+
+  public async acquireLock(lockKey: string, token: string, ttlSeconds: number): Promise<boolean> {
+    const reply = await this.client.set(lockKey, token, "NX", "EX", String(ttlSeconds));
+    return reply === "OK";
+  }
+
+  public async releaseLock(lockKey: string, token: string, entryVersionKey?: string): Promise<void> {
+    const keys = entryVersionKey === undefined ? [lockKey] : [lockKey, entryVersionKey];
+    await this.client.send("EVAL", [RELEASE_LOCK_SCRIPT, String(keys.length), ...keys, token]);
+  }
+
+  public async writeIfLockOwner(request: DistributedCacheFencedWrite): Promise<boolean> {
+    const versionKeys = request.versionChecks.map((check) => check.key);
+    const tagKeys = request.tags.map((tag) => tag.key);
+    const expectedVersions = request.versionChecks.map((check) => check.expected ?? "__BAZIS_MISSING_VERSION__");
+    const tagMembers = request.tags.map((tag) => tag.member);
+    const keys = [request.lockKey, request.key, ...versionKeys, ...tagKeys];
+    const args = [
+      request.lockToken,
+      request.value,
+      request.ttlSeconds === undefined ? "" : String(request.ttlSeconds),
+      String(versionKeys.length),
+      String(tagKeys.length),
+      ...expectedVersions,
+      ...tagMembers,
+    ];
+    const reply = await this.client.send("EVAL", [WRITE_IF_LOCK_OWNER_SCRIPT, String(keys.length), ...keys, ...args]);
+    return Number(reply) === 1;
+  }
+
+  public async deleteIfValue(key: string, expectedValue: string): Promise<boolean> {
+    const reply = await this.client.send("EVAL", [DELETE_IF_VALUE_SCRIPT, "1", key, expectedValue]);
+    return Number(reply) === 1;
+  }
+
+  public async increment(key: string): Promise<number> {
+    const reply = await this.client.send("INCR", [key]);
+    const value = Number(reply);
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new Error("Redis returned an invalid cache invalidation generation");
+    }
+    return value;
+  }
+
+  public async invalidate(versionKey: string, valueKey: string, lockKey?: string): Promise<boolean> {
+    const reply = lockKey === undefined
+      ? await this.client.send("EVAL", [INVALIDATE_SCRIPT, "2", versionKey, valueKey])
+      : await this.client.send(
+        "EVAL",
+        [INVALIDATE_WHILE_LOCKED_SCRIPT, "3", versionKey, valueKey, lockKey],
+      );
+    return Number(reply) > 0;
+  }
+
+  public async advanceTagGeneration(versionKey: string, pendingKey: string): Promise<number> {
+    const reply = await this.client.send("EVAL", [ADVANCE_TAG_GENERATION_SCRIPT, "2", versionKey, pendingKey]);
+    const value = Number(reply);
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new Error("Redis returned an invalid tag invalidation generation");
+    }
+    return value;
+  }
+
+  public async addTagMembers(tagKey: string, members: readonly string[], ttlSeconds?: number): Promise<void> {
+    if (members.length === 0) {
+      return;
+    }
+    await this.client.send("EVAL", [
+      ADD_TAG_MEMBERS_SCRIPT,
+      "1",
+      tagKey,
+      ttlSeconds === undefined ? "" : String(ttlSeconds),
+      ...members,
+    ]);
+  }
+
+  public async removeTagMembers(tagKey: string, members: readonly string[]): Promise<void> {
+    if (members.length === 0) return;
+    await this.client.send("SREM", [tagKey, ...members]);
+  }
+
+  public async tagMembers(tagKey: string): Promise<readonly string[]> {
+    const reply = await this.client.send("SMEMBERS", [tagKey]);
+    return Array.isArray(reply) ? (reply as string[]) : [];
+  }
+}

package/core/infra/cache/index.ts

@@ -0,0 +1,7 @@
+// Distributed cache backend on top of Redis. It implements the `@/core/cache`
+// abstractions (DistributedCacheDriver/Backend), so the cache core stays backend-agnostic.
+export {
+  RedisDistributedCacheBackend,
+  type RedisDistributedCacheTuning,
+} from "./RedisDistributedCacheBackend";
+export { RedisDistributedCacheDriver, type RedisCommandClient } from "./RedisDistributedCacheDriver";

package/core/infra/connectorConfig.ts

@@ -0,0 +1,29 @@
+import { InfraError } from "./InfraConnector";
+import type { AppConfig } from "../kernel/config/defineConfig";
+import type { ConfigRegistry } from "../kernel/config/ConfigRegistry";
+
+/**
+ * Minimal dynamic access to a declarative subsystem config.
+ *
+ * Connectors accept a typed config (`AppConfig<...Shape>`): at the call site
+ * this guarantees that the required keys are declared with the right types.
+ * Inside, the connector reads them by name; the runtime shape is known from
+ * `Shape`, so a narrow cast to this reader is acceptable here.
+ */
+export interface ConfigReader {
+  get(key: string): unknown;
+  has(key: string): boolean;
+}
+
+/** Narrow cast of a config to the dynamic reader (the shape is type-checked at the input). */
+export function reader(config: object, configs?: ConfigRegistry): ConfigReader {
+  return (configs?.get(config as AppConfig<object>) ?? config) as ConfigReader;
+}
+
+/** Reads a required non-empty string value or fails with a clear error. */
+export function requireValue(value: unknown, field: string, kind: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new InfraError(`Infra connector "${kind}": "${field}" is required and must be a non-empty string.`);
+  }
+  return value;
+}

package/core/infra/connectorIdentity.ts

@@ -0,0 +1,39 @@
+import type { HostedService } from "../di";
+import type { InfraConnector } from "./InfraConnector";
+
+type ConnectorIdentity = Readonly<{ role: string; fingerprint: readonly unknown[] }>;
+type LifecycleBinding = Readonly<{ connector: InfraConnector; identity?: ConnectorIdentity }>;
+
+const identities = new WeakMap<object, ConnectorIdentity>();
+const lifecycles = new WeakMap<object, LifecycleBinding>();
+const values = (c: InfraConnector) => [c.token, c.config, c.phase, c.create, c.connect, c.dispose, c.healthCheck, c.providers, c.exports] as const;
+const unchanged = (c: InfraConnector, identity: ConnectorIdentity) => values(c).every((value, index) => Object.is(value, identity.fingerprint[index]));
+
+/** @internal A factory identifies its original connector; copies inherit no identity. */
+export function identifyConnector<T>(connector: InfraConnector<T>, role: string): InfraConnector<T> {
+  identities.set(connector, Object.freeze({ role, fingerprint: values(connector) }));
+  return connector;
+}
+
+/** @internal Records resource ownership without interpreting role, token or phase. */
+export function bindConnectorLifecycle(connector: InfraConnector, lifecycle: HostedService): void {
+  const identity = identities.get(connector);
+  lifecycles.set(lifecycle, Object.freeze({
+    connector,
+    identity: identity !== undefined && unchanged(connector, identity) ? identity : undefined,
+  }));
+}
+
+/** @internal Read-only evidence for the owning integration's plan validator. */
+export function getLifecycleConnector(lifecycle: HostedService): InfraConnector | undefined {
+  return lifecycles.get(lifecycle)?.connector;
+}
+
+/** @internal Both binding-time and current fingerprints must match the original factory result. */
+export function getLifecycleConnectorRole(lifecycle: HostedService): string | undefined {
+  const binding = lifecycles.get(lifecycle);
+  if (binding?.identity === undefined) return undefined;
+  return identities.get(binding.connector) === binding.identity && unchanged(binding.connector, binding.identity)
+    ? binding.identity.role
+    : undefined;
+}