unikvs 0.0.13 → 0.0.14

package/src/unikvs.ts

@@ -33,7 +33,7 @@ import {
   StreamArgsSchema,
   VariablesArgsSchema,
 } from "./_unikvs.schemas.js";
-import { parseInput, parseOutput } from "./_valibot.js";
+import * as v from "./_valibot.js";
 import type {
   ValueSchemaInfo,
   $InferPlainValueData,
@@ -182,7 +182,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
    */
   public setVars(vars: VariablesInit): this;
   public setVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
     this.#baseVars = vars;
 
     return this;
@@ -193,7 +193,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
    */
   public assignVars(vars: VariablesInit): this;
   public assignVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
 
     const map = new Map(this.#baseVars);
 
@@ -211,7 +211,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
    */
   public defaultsVars(vars: VariablesInit): this;
   public defaultsVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
 
     const map = new Map(vars);
 
@@ -224,87 +224,6 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     return this;
   }
 
-  /**
-   * 基本変数と操作固有変数を結合した実行時変数マップを作成します。
-   *
-   * @param vars 操作固有の変数です。
-   *
-   * @returns 結合した変数マップを返します。
-   */
-  #createOperationVars(vars: readonly VariablesEntry[] | undefined): Map<string, unknown> {
-    const map = new Map(this.#baseVars);
-
-    if (vars) {
-      for (const [k, v] of vars) {
-        map.set(k, v);
-      }
-    }
-
-    return map;
-  }
-
-  /**
-   * 操作内で共有される変数ストアを作成します。
-   *
-   * 同一操作内の全コンテキスト (`use`/`encode`/`decode`/ ストレージ) で共有され、下流の `set` が上流の `await next()` 後の `get` に見えます。
-   *
-   * @param vars 操作固有の変数です。
-   *
-   * @returns 共有ストアを返します。
-   */
-  #createOperationStore(vars: readonly VariablesEntry[] | undefined): VariablesStore {
-    return createVariablesStore([...this.#baseVars, ...(vars ?? [])]);
-  }
-
-  /**
-   * キーに対応する値のスキーマ情報を解決します。
-   *
-   * @param key 解決するキーです。
-   *
-   * @returns 対応するスキーマ情報を返します。スキーマ未設定または対応する定義がない場合は `undefined` を返します。
-   */
-  #resolveValueSchema(key: string): ValueSchemaInfo | undefined {
-    return this.#valueSchemaResolver?.resolve(key);
-  }
-
-  /**
-   * すべての宛先で読み取りに失敗したときのエラーを組み立てます。
-   *
-   * @param key 読み取ったキーです。
-   * @param errors 収集した失敗です。
-   *
-   * @returns `KeyNotFoundError` を返します。
-   */
-  #notFound(key: string, errors: readonly PluginErrorRecord[]): KeyNotFoundError {
-    const args: KeyNotFoundErrorArgs = { key };
-
-    switch (errors.length) {
-      case 0: {
-        break;
-      }
-
-      case 1: {
-        const [firstError] = errors;
-
-        if (firstError !== undefined) {
-          args.cause = firstError.reason;
-        }
-
-        break;
-      }
-
-      default: {
-        args.cause = new PluginOperationAggregateError({
-          action: "read",
-          errors,
-          plugin: "storage",
-        });
-      }
-    }
-
-    return new KeyNotFoundError(args);
-  }
-
   public get isOpen(): boolean {
     return this.#con !== null;
   }
@@ -315,7 +234,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
       throw new UniKvsIsOpenError();
     }
 
-    const [options = {}] = parseInput(OpenArgsSchema, args);
+    const [options = {}] = v.parseInput(OpenArgsSchema, args);
     const { vars: varsOption, signal: signalOption } = options;
 
     const ac = new AbortController();
@@ -457,125 +376,10 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     }
   }
 
-  async #close(
-    operationVars: Map<string, unknown>,
-    signal: AbortSignal,
-    con: Connection,
-    progress: { pluginsStarted: boolean },
-  ): Promise<void> {
-    using _lock = await asyncmux(this, signal);
-    // ロック待機中に接続状態が変更されていないか再確認します。
-    if (this.#con !== con) {
-      throw new UniKvsIsNotOpenError();
-    }
-
-    const { io } = this.#con;
-    using _ioLock = await io.lock({ signal });
-    const closeFns: [
-      () => Promise<void>,
-      () => Promise<void>,
-      plugin: "storage" | "middleware",
-      name: string,
-      index: number,
-    ][] = [];
-
-    // ストレージのクローズ処理を登録します。
-    // open と同じ方針でプラグインごとに複製し、並列実行中の変更が互いに見えないようにします。
-    for (const [index, leaf] of this.#pipeline.leaves.entries()) {
-      const createContext = (): CloseContext =>
-        new CloseContext({
-          vars: new Map(operationVars).entries(),
-          signal,
-        });
-      // 再試行は通常 close の失敗 (操作 signal の abort など) に引きずられないよう、新しいタイムアウト signal を使います。
-      const createRetryContext = (): CloseContext =>
-        new CloseContext({
-          vars: new Map(operationVars).entries(),
-          signal: AbortSignal.timeout(10e3),
-        });
-      closeFns.push([
-        (): Promise<void> => leaf.storage.close(createContext()),
-        (): Promise<void> => leaf.storage.retryClose(createRetryContext()),
-        "storage",
-        leaf.name,
-        index,
-      ]);
-    }
-
-    // ミドルウェアのクローズ処理を登録します。
-    for (const [index, plugin] of this.#pipeline.middlewares.entries()) {
-      const createContext = (): CloseContext =>
-        new CloseContext({
-          vars: new Map(operationVars).entries(),
-          signal,
-        });
-      // 再試行は通常 close の失敗 (操作 signal の abort など) に引きずられないよう、新しいタイムアウト signal を使います。
-      const createRetryContext = (): CloseContext =>
-        new CloseContext({
-          vars: new Map(operationVars).entries(),
-          signal: AbortSignal.timeout(10e3),
-        });
-      closeFns.push([
-        (): Promise<void> => plugin.close(createContext()),
-        (): Promise<void> => plugin.retryClose(createRetryContext()),
-        "middleware",
-        plugin.name,
-        index,
-      ]);
-    }
-
-    // すべての処理を並列に実行し、エラーが発生した場合は集約します。
-    progress.pluginsStarted = true;
-    const errors: {
-      name: string;
-      index: number;
-      plugin: "storage" | "middleware";
-      reason: unknown;
-    }[] = [];
-    const retries: (() => Promise<void>)[] = [];
-    await Promise.all(
-      closeFns.map(async ([f, retry, plugin, name, index]) => {
-        try {
-          await f();
-        } catch (ex) {
-          errors.push({
-            name,
-            index,
-            plugin,
-            reason: ex,
-          });
-          // 通常の close で再試行すると、close 失敗後に別の利用者が引き継いだ参照まで解放してしまいます。
-          retries.push(retry);
-        }
-      }),
-    );
-
-    if (errors.length > 0) {
-      // 失敗したプラグインだけを 1 回再試行します。
-      // 成功済みのプラグインを再 close すると、参照カウントが二重に解放され、共有している他の利用者の実体まで閉じてしまうためです。
-      await Promise.all(
-        retries.map(async (f) => {
-          try {
-            await f();
-          } catch (ex) {
-            logger.error`Failed to retry closing a plugin: ${ex}`;
-          }
-        }),
-      );
-
-      throw new PluginOperationAggregateError({
-        action: "close",
-        errors,
-      });
-    }
-
-    this.#con = null;
-  }
-
   public close(options?: CloseOptions): Promise<void>;
   public close(...args: any): Promise<void> {
     try {
-      const [options = {}] = parseInput(CloseArgsSchema, args);
+      const [options = {}] = v.parseInput(CloseArgsSchema, args);
       const { vars: varsOption, signal = AbortSignal.timeout(10e3) } = options;
 
       const operationVars = this.#createOperationVars(varsOption);
@@ -644,7 +448,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     }
   }
 
-  async [Symbol.asyncDispose](): Promise<void> {
+  public async [Symbol.asyncDispose](): Promise<void> {
     if (!this.isOpen) {
       return;
     }
@@ -654,664 +458,303 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     });
   }
 
-  /**
-   * 書き込み失敗の集約と、成功した宛先への通知を行います。
-   *
-   * @param targets 書き込みを試みた対象です。
-   * @param failed 失敗した葉の集合です。
-   * @param errors 集約する失敗です。
-   * @param signal 中断シグナルです。
-   */
-  async #finishWrites(
-    targets: readonly {
-      readonly key: string;
-      readonly leaf: PipelineLeaf;
-    }[],
-    store: VariablesStore,
-    failed: ReadonlySet<PipelineLeaf>,
-    errors: PluginErrorRecord[],
-    signal: AbortSignal,
-  ): Promise<void> {
-    if (errors.length === 0) {
-      return;
+  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    options: SetOptions<TKeyValueMapping, TKey>,
+  ): Promise<void>;
+  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    key: TKey,
+    value: SetValue<TKeyValueMapping[TKey]>,
+    options?: Omit<SetOptions, "key" | "value">,
+  ): Promise<void>;
+  public async set(...args: any): Promise<void> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
     }
 
-    const error = new PluginOperationAggregateError({
-      action: "write",
-      errors,
-      plugin: "storage",
-    });
-    const notifyErrors: unknown[] = [];
-    await Promise.all(
-      targets.map(async (target) => {
-        // 失敗した宛先を除いたすべての宛先へ通知します。通知に失敗しても元の集約エラーは置き換えません。
-        if (failed.has(target.leaf)) {
-          return;
-        }
+    const [options] = v.parseInput(SetArgsSchema, args);
+    const { key, vars: varsOption, signal: signalOption } = options;
 
-        try {
-          const c = new SetContext({
-            key: target.key,
-            store,
-            signal,
-          });
-          await target.leaf.storage.onOtherWriteError(c, error);
-        } catch (ex) {
-          notifyErrors.push(ex);
-        }
-      }),
-    );
+    const valueSchema = this.#resolveValueSchema(key);
+    // スキーマ検証はロック取得前に済ませ、無効な入力ではロックを取得しません。
+    const value = valueSchema ? parseSetValue(valueSchema, options.value) : options.value;
 
-    if (notifyErrors.length > 0) {
-      logger.error(new AggregateError(notifyErrors, "Failed to handle error"));
-    }
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, signalOption]);
 
-    throw error;
-  }
+    const store = this.#createOperationStore(varsOption);
 
-  /**
-   * ミドルウェアの `use` をオニオン実行し、失敗時は集約して投げます。
-   *
-   * 同一コンテキストオブジェクトを全ミドルウェアで共有し、`next` で下流をネスト実行するため、下流の `set` が上流の `await next()` 後の `get` に見えます。
-   * `encode`/`decode` と同じく `next()` の呼び出し規約を検証し、違反したときは操作を実行せず失敗させます (fail-close)。
-   * いずれかのミドルウェアが投げたときは即時に確定し、後段は実行しません (fail-fast)。
-   * 失敗は集約エラー (単一件) として投げます。
-   *
-   * @param action 集約エラーに付与する操作名です。
-   * @param c 共有の `use` コンテキストです。
-   */
-  async #use(
-    action: "read" | "write" | "delete" | "clear",
-    c: IMiddleware.UseContext,
-  ): Promise<void> {
-    throwIfAborted(c.signal);
+    // `#setStream` へ所有権を渡す前の失敗では、ソースをロックしたままにしないよう派生ストリームをキャンセルします。
+    const stream = isReadableStream(value) ? value : null;
+    let ownsStream = stream !== null;
 
-    const middlewares = this.#pipeline.middlewares;
-    const dispatch = async (index: number): Promise<void> => {
-      const maybeMiddleware = middlewares[index];
+    try {
+      using _lock = await asyncmux.readonly(this, signal);
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (this.#con === null) {
+        throw new UniKvsIsNotOpenError();
+      }
 
-      if (maybeMiddleware === undefined) {
-        return;
+      // 書き込み前の `use` による検証を行います。変異は後続のエンコード・書き込みに引き継がれます。
+      const useContext = new SetContext({
+        key,
+        store,
+        signal,
+      });
+      await this.#use("write", useContext);
+      // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
+      throwIfAborted(signal);
+      // `use` による変異を操作変数に反映します。
+      // ロックはインスタンス (読み取り) からキーの順で取得し、逆順で解放します。
+      if (stream !== null) {
+        // これ以降の後始末は `#setStream` が所有します。
+        ownsStream = false;
+        await this.#setStream(io, signal, key, store, stream);
+      } else {
+        await this.#setPlain(io, signal, key, store, value);
+      }
+    } catch (ex) {
+      if (ownsStream && stream !== null) {
+        // 消費されないストリームをキャンセルし、ソースの解放を伝播させます。
+        try {
+          await stream.cancel(ex);
+        } catch {
+          // キャンセルに失敗しても元の例外の伝播を優先します。
+        }
       }
 
-      const middleware: UniKvsMiddleware = maybeMiddleware;
+      throw ex;
+    }
+  }
 
-      let nextCalled = false;
-      let nextSettled = false;
-      let downstreamError: unknown;
-      let hasDownstreamError = false;
+  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
+    options: GetOptions<TKey>,
+  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
+  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
+    key: TKey,
+    options?: Omit<GetOptions, "key">,
+  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
+  public async get(...args: any): Promise<unknown> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
 
-      function next(): Promise<void> {
-        if (nextCalled) {
-          // 2 回目以降の `next()` は下流を実行せず拒否だけを返します。
-          const rejection = Promise.reject(
-            new MiddlewareNextCalledMultipleTimesError({
-              name: middleware.name,
-              operation: "use",
-            }),
-          );
-          // 呼び出し側が切り離した場合の未処理 rejection を防ぎます。await したときは従来どおり拒否されます。
-          // oxlint-disable-next-line promise/prefer-await-to-then
-          rejection.catch(() => {});
+    const [options] = v.parseInput(GetArgsSchema, args);
+    const {
+      key,
+      vars: varsOption,
+      repair = false,
+      signal: signalOption,
+      throwOnRepairDenied = false,
+    } = options;
 
-          return rejection;
-        }
+    const valueSchema = this.#resolveValueSchema(key);
 
-        nextCalled = true;
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, signalOption]);
 
-        const promise = Promise.try(async () => {
-          try {
-            await dispatch(index + 1);
-          } catch (ex) {
-            // 下流の失敗を親自身の失敗と取り違えないよう、由来を記録します。
-            downstreamError = ex;
-            hasDownstreamError = true;
-            throw ex;
-          } finally {
-            nextSettled = true;
+    const store = this.#createOperationStore(varsOption);
+
+    using _lock = await asyncmux.readonly(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    // 読み取り前の `use` による検証を行います。書き戻し要求は `repair` フィールドで伝えます。
+    const leafNames = this.#pipeline.leaves.map((leaf) => leaf.name);
+    const useContext = new GetContext({
+      key,
+      store,
+      repair: repair
+        ? {
+            enabled: true,
+            targets: leafNames as [string, ...string[]],
           }
-        });
-        // 呼び出し側が切り離した場合の未処理 rejection を防ぎます。await したときは従来どおり拒否されます。
-        // oxlint-disable-next-line promise/prefer-await-to-then
-        promise.catch(() => {});
+        : {
+            enabled: false,
+            targets: [],
+          },
+      signal,
+    });
+    await this.#use("read", useContext);
+    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
+    throwIfAborted(signal);
+    let data: unknown = undefined;
+    let hit: ResolvedLeaf | null = null;
+    const missing: PipelineLeaf[] = [];
+    const errors: PluginErrorRecord[] = [];
 
-        return promise;
-      }
+    // 書き戻し時は、読み取りから書き込みまでを同じキーの書き込みと直列化するため、書き込みロックを取得します。
+    {
+      using _ioLock = await (repair
+        ? io.lock({
+            key,
+            signal,
+          })
+        : io.rLock({
+            key,
+            signal,
+          }));
+      // 登録順が読み取りの優先順です。先頭で見つかればそこで終え、失敗したときは次の宛先を試します。
+      const resolver = this.#pipeline.createResolver({
+        key,
+        store,
+        signal,
+      });
 
-      try {
-        await middleware.use(c, next);
-        throwIfAborted(c.signal);
-        if (!nextCalled) {
-          throw new MiddlewareNextNotCalledError({
-            name: middleware.name,
-            operation: "use",
-          });
-        }
+      for (const leaf of this.#pipeline) {
+        const resolved = resolver.resolve(leaf);
+        const existsContext = new HasContext({
+          key: resolved.key,
+          store,
+          signal,
+        });
+        const readRepair = repair
+          ? {
+              enabled: true as const,
+              targets: leafNames as [string, ...string[]],
+            }
+          : {
+              enabled: false as const,
+              targets: [] as const,
+            };
+        const readContext = new GetContext({
+          key: resolved.key,
+          store,
+          repair: readRepair,
+          signal,
+        });
 
-        if (!nextSettled) {
-          throw new MiddlewareNextNotAwaitedError({
-            name: middleware.name,
-            operation: "use",
-          });
-        }
-      } catch (ex) {
-        // 中断による失敗はそのまま投げます。
-        if (c.signal.aborted && ex === c.signal.reason) {
-          throw ex;
-        }
+        try {
+          if (!(await leaf.storage.exists(existsContext))) {
+            missing.push(leaf);
+            continue;
+          }
 
-        // 規約違反はプログラミングエラーであり、集約せずに投げます。
-        if (
-          ex instanceof MiddlewareNextNotCalledError ||
-          ex instanceof MiddlewareNextNotAwaitedError ||
-          ex instanceof MiddlewareNextCalledMultipleTimesError
-        ) {
-          throw ex;
-        }
+          data = await leaf.storage.read(readContext);
+          hit = resolved;
+          break;
+        } catch (ex) {
+          if (signal.aborted) {
+            throw ex;
+          }
 
-        // `next()` から伝播した下流の失敗は再集約せず、そのまま投げます。
-        if (hasDownstreamError && ex === downstreamError) {
-          throw ex;
+          errors.push({
+            name: leaf.name,
+            index: leaf.index,
+            reason: ex,
+          });
+          logger.error`Failed to read from a storage: ${ex}`;
         }
+      }
 
-        throw new PluginOperationAggregateError({
-          action,
-          errors: [
-            {
-              name: middleware.name,
-              index,
-              reason: ex,
-            },
-          ],
-          plugin: "middleware",
-        });
+      if (hit === null) {
+        throw this.#notFound(key, errors);
       }
-    };
-    await dispatch(0);
-  }
 
-  /**
-   * プレーン値の並列書き込みを行います。
-   *
-   * @param io 多重化インスタンスです。
-   * @param signal 中断シグナルです。
-   * @param key 書き込みキーです。
-   * @param store 操作内で共有される変数ストアです。
-   * @param value 書き込む値です.
-   */
-  async #setPlain(
-    io: Asyncmux,
-    signal: AbortSignal,
-    key: string,
-    store: VariablesStore,
-    value: unknown,
-  ): Promise<void> {
-    const targets = await this.#pipeline.encode(
-      {
-        key,
-        store,
-        signal,
-      },
-      value,
-    );
-    using _ioLock = await io.lock({
-      key,
-      signal,
-    });
-    const errors: PluginErrorRecord[] = [];
-    const failed = new Set<PipelineLeaf>();
-    await Promise.all(
-      targets.map(async (target) => {
-        try {
-          const c = new SetContext({
-            key: target.key,
-            store,
-            signal,
-          });
-          await target.leaf.storage.write(c, target.data);
-        } catch (ex) {
-          errors.push({
-            name: target.leaf.name,
-            index: target.leaf.index,
-            reason: ex,
-          });
-          failed.add(target.leaf);
-        }
-      }),
-    );
-    await this.#finishWrites(targets, store, failed, errors, signal);
-  }
-
-  /**
-   * ストリーム値の並列書き込みを行います。
-   *
-   * @param io 多重化インスタンスです。
-   * @param signal 中断シグナルです。
-   * @param key 書き込みキーです。
-   * @param store 操作内で共有される変数ストアです。
-   * @param value 書き込むストリームです。
-   */
-  async #setStream(
-    io: Asyncmux,
-    signal: AbortSignal,
-    key: string,
-    store: VariablesStore,
-    value: IReadableStream,
-  ): Promise<void> {
-    const streams = new Set<IReadableStream>([value]);
-    let tree;
+      if (repair) {
+        // 後段で見つかったデータをすべてデコードして原データに戻します。
+        data = await this.#repairPlain(data, hit, missing, store, key, signal, throwOnRepairDenied);
+      }
+    }
 
-    try {
-      tree = await this.#pipeline.buildEncodeTree(
+    if (!repair) {
+      // 見つかったストレージ専用の前段パイプラインを逆順に適用して、データをデコードします。
+      data = await this.#pipeline.decode(
+        hit.leaf,
         {
           key,
           store,
           signal,
         },
-        value,
-        streams,
+        data,
       );
-    } catch (ex) {
-      await cancelStreams(streams, ex);
-      throw ex;
     }
 
-    using _ioLock = await io
-      .lock({
-        key,
-        signal,
-      })
-      .catch(async (ex) => {
-        // キーロックの待機中に中断されたときも、構築済みのストリームをキャンセルします。
-        // ソースストリームをロックしたまま残さないためです。
-        await cancelStreams(streams, ex);
-        throw ex;
-      });
-
-    const errors: PluginErrorRecord[] = [];
-    const failed = new Set<PipelineLeaf>();
-    await Promise.all(
-      tree.targets.map(async (target) => {
-        try {
-          const c = new SetContext({
-            key: target.key,
-            store,
-            signal,
-          });
-          const w = await target.leaf.storage.getWritable(c);
-          await target.stream.pipeTo(w, { signal });
-        } catch (ex) {
-          // tee で分岐したストリームは、片方の分岐をキャンセルするまで他方が読み取ったチャンクを保持し続けるため、失敗時に放棄した分岐は確実にキャンセルします。
-          try {
-            await target.stream.cancel(ex);
-          } catch {
-            // キャンセルに失敗してもエラー集約を優先します。
-          }
+    // デコード後のデータを検証します。
+    if (valueSchema) {
+      data = v.parseOutput(valueSchema.schema, data);
+    }
 
-          errors.push({
-            name: target.leaf.name,
-            index: target.leaf.index,
-            reason: ex,
-          });
-          failed.add(target.leaf);
-        }
-      }),
-    );
-    await this.#finishWrites(tree.targets, store, failed, errors, signal);
+    return data;
   }
 
-  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
-    options: SetOptions<TKeyValueMapping, TKey>,
-  ): Promise<void>;
-  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
+    options: StreamOptions<TKey>,
+  ): Promise<IValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
+  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
     key: TKey,
-    value: SetValue<TKeyValueMapping[TKey]>,
-    options?: Omit<SetOptions, "key" | "value">,
-  ): Promise<void>;
-  public async set(...args: any): Promise<void> {
+    options?: Omit<StreamOptions, "key">,
+  ): Promise<IValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
+  public async stream(...args: any): Promise<IValueStream> {
     if (this.#con === null) {
       throw new UniKvsIsNotOpenError();
     }
 
-    const [options] = parseInput(SetArgsSchema, args);
-    const { key, vars: varsOption, signal: signalOption } = options;
+    const [options] = v.parseInput(StreamArgsSchema, args);
+    const {
+      key,
+      vars: varsOption,
+      repair = false,
+      signal: signalOption,
+      throwOnRepairDenied = false,
+    } = options;
 
     const valueSchema = this.#resolveValueSchema(key);
-    // スキーマ検証はロック取得前に済ませ、無効な入力ではロックを取得しません。
-    const value = valueSchema ? parseSetValue(valueSchema, options.value) : options.value;
 
     const { ac, io } = this.#con;
     const signal = combineSignals([ac.signal, signalOption]);
 
     const store = this.#createOperationStore(varsOption);
 
-    // `#setStream` へ所有権を渡す前の失敗では、ソースをロックしたままにしないよう派生ストリームをキャンセルします。
-    const stream = isReadableStream(value) ? value : null;
-    let ownsStream = stream !== null;
-
-    try {
+    {
       using _lock = await asyncmux.readonly(this, signal);
       // ロック待機中に接続状態が変更されていないか再確認します。
       if (this.#con === null) {
         throw new UniKvsIsNotOpenError();
       }
 
-      // 書き込み前の `use` による検証を行います。変異は後続のエンコード・書き込みに引き継がれます。
-      const useContext = new SetContext({
+      // 読み取り前の `use` による検証を行います。書き戻し要求は `repair` フィールドで伝えます。
+      const leafNames = this.#pipeline.leaves.map((leaf) => leaf.name);
+      const useContext = new StreamContext({
         key,
         store,
+        repair: repair
+          ? {
+              enabled: true,
+              targets: leafNames as [string, ...string[]],
+            }
+          : {
+              enabled: false,
+              targets: [],
+            },
         signal,
       });
-      await this.#use("write", useContext);
+      await this.#use("read", useContext);
       // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
       throwIfAborted(signal);
-      // `use` による変異を操作変数に反映します。
-      // ロックはインスタンス (読み取り) からキーの順で取得し、逆順で解放します。
-      if (stream !== null) {
-        // これ以降の後始末は `#setStream` が所有します。
-        ownsStream = false;
-        await this.#setStream(io, signal, key, store, stream);
-      } else {
-        await this.#setPlain(io, signal, key, store, value);
-      }
-    } catch (ex) {
-      if (ownsStream && stream !== null) {
-        // 消費されないストリームをキャンセルし、ソースの解放を伝播させます。
-        try {
-          await stream.cancel(ex);
-        } catch {
-          // キャンセルに失敗しても元の例外の伝播を優先します。
-        }
-      }
+      // NONE は getReadable の呼び出し前を表す番兵値です。
+      const NONE: any = {};
+      let r: IReadableStream = NONE;
+      let hit: ResolvedLeaf | null = null;
+      const missing: PipelineLeaf[] = [];
+      const errors: PluginErrorRecord[] = [];
+      const fillBranches: IReadableStream[] = [];
+      const fillTasks: Promise<void>[] = [];
+      let repairAc: AbortController | null = null;
+      let cancelFills: ((reason: unknown) => Promise<void>) | null = null;
 
-      throw ex;
-    }
-  }
-
-  /**
-   * 読み取り元のチェーン全体を逆順にデコードし、書き戻し対象向けに再エンコードして書き込みます。
-   *
-   * @param data 読み取ったデータです。
-   * @param hit 読み取り元の葉です。
-   * @param missing 読み取りに失敗または不在だった葉です。
-   * @param store 操作内で共有される変数ストアです。
-   * @param key キーです。
-   * @param signal 中断シグナルです。
-   * @param throwOnRepairDenied 書き戻し拒否をエラーとして投げるかどうかです。
-   *
-   * @returns デコード済みの原データを返します。
-   */
-  async #repairPlain(
-    data: unknown,
-    hit: ResolvedLeaf,
-    missing: readonly PipelineLeaf[],
-    store: VariablesStore,
-    key: string,
-    signal: AbortSignal,
-    throwOnRepairDenied: boolean,
-  ): Promise<unknown> {
-    const raw = await this.#pipeline.decode(
-      hit.leaf,
-      {
-        key,
-        store,
-        signal,
-      },
-      data,
-    );
-    await this.#pipeline.repair(
-      {
-        key,
-        store,
-        signal,
-      },
-      missing,
-      throwOnRepairDenied,
-      raw,
-      async (leaf, writeKey, input) => {
-        const c = new SetContext({
-          key: writeKey,
-          store,
-          signal,
-        });
-        await leaf.storage.write(c, input);
-      },
-    );
-
-    throwIfAborted(signal);
-
-    return raw;
-  }
-
-  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
-    options: GetOptions<TKey>,
-  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
-  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
-    key: TKey,
-    options?: Omit<GetOptions, "key">,
-  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
-  public async get(...args: any): Promise<unknown> {
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
-
-    const [options] = parseInput(GetArgsSchema, args);
-    const {
-      key,
-      vars: varsOption,
-      repair = false,
-      signal: signalOption,
-      throwOnRepairDenied = false,
-    } = options;
-
-    const valueSchema = this.#resolveValueSchema(key);
-
-    const { ac, io } = this.#con;
-    const signal = combineSignals([ac.signal, signalOption]);
-
-    const store = this.#createOperationStore(varsOption);
-
-    using _lock = await asyncmux.readonly(this, signal);
-    // ロック待機中に接続状態が変更されていないか再確認します。
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
-
-    // 読み取り前の `use` による検証を行います。書き戻し要求は `repair` フィールドで伝えます。
-    const leafNames = this.#pipeline.leaves.map((leaf) => leaf.name);
-    const useContext = new GetContext({
-      key,
-      store,
-      repair: repair
-        ? {
-            enabled: true,
-            targets: leafNames as [string, ...string[]],
-          }
-        : {
-            enabled: false,
-            targets: [],
-          },
-      signal,
-    });
-    await this.#use("read", useContext);
-    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
-    throwIfAborted(signal);
-    let data: unknown = undefined;
-    let hit: ResolvedLeaf | null = null;
-    const missing: PipelineLeaf[] = [];
-    const errors: PluginErrorRecord[] = [];
-
-    // 書き戻し時は、読み取りから書き込みまでを同じキーの書き込みと直列化するため、書き込みロックを取得します。
-    {
-      using _ioLock = await (repair
-        ? io.lock({
-            key,
-            signal,
-          })
-        : io.rLock({
-            key,
-            signal,
-          }));
-      // 登録順が読み取りの優先順です。先頭で見つかればそこで終え、失敗したときは次の宛先を試します。
-      const resolver = this.#pipeline.createResolver({
-        key,
-        store,
-        signal,
-      });
-
-      for (const leaf of this.#pipeline) {
-        const resolved = resolver.resolve(leaf);
-        const existsContext = new HasContext({
-          key: resolved.key,
-          store,
-          signal,
-        });
-        const readRepair = repair
-          ? {
-              enabled: true as const,
-              targets: leafNames as [string, ...string[]],
-            }
-          : {
-              enabled: false as const,
-              targets: [] as const,
-            };
-        const readContext = new GetContext({
-          key: resolved.key,
-          store,
-          repair: readRepair,
-          signal,
-        });
-
-        try {
-          if (!(await leaf.storage.exists(existsContext))) {
-            missing.push(leaf);
-            continue;
-          }
-
-          data = await leaf.storage.read(readContext);
-          hit = resolved;
-          break;
-        } catch (ex) {
-          if (signal.aborted) {
-            throw ex;
-          }
-
-          errors.push({
-            name: leaf.name,
-            index: leaf.index,
-            reason: ex,
-          });
-          logger.error`Failed to read from a storage: ${ex}`;
-        }
-      }
-
-      if (hit === null) {
-        throw this.#notFound(key, errors);
-      }
-
-      if (repair) {
-        // 後段で見つかったデータをすべてデコードして原データに戻します。
-        data = await this.#repairPlain(data, hit, missing, store, key, signal, throwOnRepairDenied);
-      }
-    }
-
-    if (!repair) {
-      // 見つかったストレージ専用の前段パイプラインを逆順に適用して、データをデコードします。
-      data = await this.#pipeline.decode(
-        hit.leaf,
-        {
-          key,
-          store,
-          signal,
-        },
-        data,
-      );
-    }
-
-    // デコード後のデータを検証します。
-    if (valueSchema) {
-      data = parseOutput(valueSchema.schema, data);
-    }
-
-    return data;
-  }
-
-  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
-    options: StreamOptions<TKey>,
-  ): Promise<IValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
-  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
-    key: TKey,
-    options?: Omit<StreamOptions, "key">,
-  ): Promise<IValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
-  public async stream(...args: any): Promise<IValueStream> {
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
-
-    const [options] = parseInput(StreamArgsSchema, args);
-    const {
-      key,
-      vars: varsOption,
-      repair = false,
-      signal: signalOption,
-      throwOnRepairDenied = false,
-    } = options;
-
-    const valueSchema = this.#resolveValueSchema(key);
-
-    const { ac, io } = this.#con;
-    const signal = combineSignals([ac.signal, signalOption]);
-
-    const store = this.#createOperationStore(varsOption);
-
-    {
-      using _lock = await asyncmux.readonly(this, signal);
-      // ロック待機中に接続状態が変更されていないか再確認します。
-      if (this.#con === null) {
-        throw new UniKvsIsNotOpenError();
-      }
-
-      // 読み取り前の `use` による検証を行います。書き戻し要求は `repair` フィールドで伝えます。
-      const leafNames = this.#pipeline.leaves.map((leaf) => leaf.name);
-      const useContext = new StreamContext({
-        key,
-        store,
-        repair: repair
-          ? {
-              enabled: true,
-              targets: leafNames as [string, ...string[]],
-            }
-          : {
-              enabled: false,
-              targets: [],
-            },
-        signal,
-      });
-      await this.#use("read", useContext);
-      // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
-      throwIfAborted(signal);
-      // NONE は getReadable の呼び出し前を表す番兵値です。
-      const NONE: any = {};
-      let r: IReadableStream = NONE;
-      let hit: ResolvedLeaf | null = null;
-      const missing: PipelineLeaf[] = [];
-      const errors: PluginErrorRecord[] = [];
-      const fillBranches: IReadableStream[] = [];
-      const fillTasks: Promise<void>[] = [];
-      let repairAc: AbortController | null = null;
-      let cancelFills: ((reason: unknown) => Promise<void>) | null = null;
-
-      // 書き戻し時は、読み取りから書き込みまでを同じキーの書き込みと直列化するため、書き込みロックを取得します。
-      // キーロックは ValueStream の dispose まで保持するため、明示的に解放します。
-      const ioLock = await (repair
-        ? io.lock({
-            key,
-            signal,
-          })
-        : io.rLock({
-            key,
-            signal,
-          }));
+      // 書き戻し時は、読み取りから書き込みまでを同じキーの書き込みと直列化するため、書き込みロックを取得します。
+      // キーロックは ValueStream の dispose まで保持するため、明示的に解放します。
+      const ioLock = await (repair
+        ? io.lock({
+            key,
+            signal,
+          })
+        : io.rLock({
+            key,
+            signal,
+          }));
 
       try {
         // 登録順が読み取りの優先順です。先頭で見つかればそこで終え、失敗したときは次の宛先を試します。
@@ -1515,7 +958,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
           r = r.pipeThrough(
             new TransformStream({
               transform(chunk, controller): void {
-                controller.enqueue(parseOutput(valueSchema.schema, chunk));
+                controller.enqueue(v.parseOutput(valueSchema.schema, chunk));
               },
             }),
           );
@@ -1591,249 +1034,806 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
       } catch (ex) {
         await cancelFills?.(ex);
 
-        if (r !== NONE) {
-          // getReadable の成功後にセットアップで失敗したときは、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するためキャンセルします。
+        if (r !== NONE) {
+          // getReadable の成功後にセットアップで失敗したときは、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するためキャンセルします。
+          try {
+            await r.cancel(ex);
+          } catch {
+            // キャンセルに失敗しても元の例外の伝播を優先します。
+          }
+        }
+
+        ioLock.release();
+
+        throw ex;
+      }
+    }
+  }
+
+  public has(options: HasOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<boolean>;
+  public has(
+    key: KeyofKeyValueMapping<TKeyValueMapping>,
+    options?: Omit<HasOptions, "key">,
+  ): Promise<boolean>;
+  public async has(...args: any): Promise<boolean> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = v.parseInput(HasArgsSchema, args);
+    const { key, vars: varsOption, signal: signalOption } = options;
+
+    // キーがキースキーマに一致するかを検証します。
+    this.#resolveValueSchema(key);
+
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, signalOption]);
+
+    const store = this.#createOperationStore(varsOption);
+
+    using _lock = await asyncmux.readonly(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    // 存在確認に先立ち、各ミドルウェアの `use` を実行します。
+    // `use` による vars の変更は後続の解決・走査に引き継がれます。
+    const useContext = new HasContext({
+      key,
+      store,
+      signal,
+    });
+    await this.#use("read", useContext);
+    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
+    throwIfAborted(signal);
+
+    using _ioLock = await io.rLock({
+      key,
+      signal,
+    });
+    // 登録順に走査し、いずれかのストレージに存在すれば true を返します。
+    // exists に失敗したときは次のストレージを試します。
+    const errors: PluginErrorRecord[] = [];
+    const resolver = this.#pipeline.createResolver({
+      key,
+      store,
+      signal,
+    });
+
+    for (const leaf of this.#pipeline) {
+      const resolved = resolver.resolve(leaf);
+
+      try {
+        const c = new HasContext({
+          key: resolved.key,
+          store,
+          signal,
+        });
+
+        if (await leaf.storage.exists(c)) {
+          return true;
+        }
+      } catch (ex) {
+        if (signal.aborted) {
+          throw ex;
+        }
+
+        errors.push({
+          name: leaf.name,
+          index: leaf.index,
+          reason: ex,
+        });
+
+        logger.error`Failed to check existence in a storage: ${ex}`;
+      }
+    }
+
+    // すべてのストレージで存在を確認できなかったときは結果が不明なため、get() と同様にエラーとして報告します。
+    if (errors.length > 0) {
+      throw this.#notFound(key, errors);
+    }
+
+    return false;
+  }
+
+  public delete(options: DeleteOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<void>;
+  public delete(
+    key: KeyofKeyValueMapping<TKeyValueMapping>,
+    options?: Omit<DeleteOptions, "key">,
+  ): Promise<void>;
+  public async delete(...args: any): Promise<void> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = v.parseInput(DeleteArgsSchema, args);
+    const { key, vars: varsOption, signal: signalOption } = options;
+
+    // キーがキースキーマに一致するかを検証します。
+    this.#resolveValueSchema(key);
+
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, signalOption]);
+
+    const store = this.#createOperationStore(varsOption);
+
+    using _lock = await asyncmux.readonly(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    // 削除に先立ち、各ミドルウェアの `use` を実行します。
+    // `use` による vars の変更は後続の解決・削除に引き継がれます。
+    const useContext = new DeleteContext({
+      key,
+      store,
+      signal,
+    });
+    await this.#use("delete", useContext);
+
+    using _ioLock = await io.lock({
+      key,
+      // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
+      signal,
+    });
+    // 全宛先を並列に削除し、失敗は宛先の index 付きで集約します。
+    const errors: PluginErrorRecord[] = [];
+    const resolver = this.#pipeline.createResolver({
+      key,
+      store,
+      signal,
+    });
+    await Promise.all(
+      this.#pipeline.leaves.map(async (leaf) => {
+        const resolved = resolver.resolve(leaf);
+        const existsContext = new HasContext({
+          key: resolved.key,
+          store,
+          signal,
+        });
+        const deleteContext = new DeleteContext({
+          key: resolved.key,
+          store,
+          signal,
+        });
+
+        try {
+          if (await leaf.storage.exists(existsContext)) {
+            await leaf.storage.delete(deleteContext);
+          }
+        } catch (ex) {
+          errors.push({
+            name: leaf.name,
+            index: leaf.index,
+            reason: ex,
+          });
+        }
+      }),
+    );
+
+    if (errors.length > 0) {
+      throw new PluginOperationAggregateError({
+        action: "delete",
+        errors,
+        plugin: "storage",
+      });
+    }
+  }
+
+  public async clear(options?: ClearOptions): Promise<void>;
+  public async clear(...args: any): Promise<void> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options = {}] = v.parseInput(ClearArgsSchema, args);
+    const { vars: varsOption, signal: signalOption } = options;
+
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, signalOption]);
+
+    const store = this.#createOperationStore(varsOption);
+
+    using _lock = await asyncmux.readonly(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    using _ioLock = await io.lock({ signal });
+    // 全ミドルウェアの `use` を実行します。
+    const useContext = new ClearContext({
+      store,
+      signal,
+    });
+    await this.#use("clear", useContext);
+    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
+    throwIfAborted(signal);
+    // 一括削除は全宛先で並列に実行し、失敗は宛先の index 付きで集約します。
+    const errors: PluginErrorRecord[] = [];
+    await Promise.all(
+      this.#pipeline.leaves.map(async (leaf, index) => {
+        try {
+          const c = new ClearContext({
+            store,
+            signal,
+          });
+          await leaf.storage.clear(c);
+        } catch (ex) {
+          errors.push({
+            name: leaf.name,
+            index,
+            reason: ex,
+          });
+        }
+      }),
+    );
+
+    if (errors.length > 0) {
+      throw new PluginOperationAggregateError({
+        action: "clear",
+        errors,
+        plugin: "storage",
+      });
+    }
+  }
+
+  /**
+   * 基本変数と操作固有変数を結合した実行時変数マップを作成します。
+   *
+   * @param vars 操作固有の変数です。
+   *
+   * @returns 結合した変数マップを返します。
+   */
+  #createOperationVars(vars: readonly VariablesEntry[] | undefined): Map<string, unknown> {
+    const map = new Map(this.#baseVars);
+
+    if (vars) {
+      for (const [k, value] of vars) {
+        map.set(k, value);
+      }
+    }
+
+    return map;
+  }
+
+  /**
+   * 操作内で共有される変数ストアを作成します。
+   *
+   * 同一操作内の全コンテキスト (`use`/`encode`/`decode`/ ストレージ) で共有され、下流の `set` が上流の `await next()` 後の `get` に見えます。
+   *
+   * @param vars 操作固有の変数です。
+   *
+   * @returns 共有ストアを返します。
+   */
+  #createOperationStore(vars: readonly VariablesEntry[] | undefined): VariablesStore {
+    return createVariablesStore([...this.#baseVars, ...(vars ?? [])]);
+  }
+
+  /**
+   * キーに対応する値のスキーマ情報を解決します。
+   *
+   * @param key 解決するキーです。
+   *
+   * @returns 対応するスキーマ情報を返します。スキーマ未設定または対応する定義がない場合は `undefined` を返します。
+   */
+  #resolveValueSchema(key: string): ValueSchemaInfo | undefined {
+    return this.#valueSchemaResolver?.resolve(key);
+  }
+
+  /**
+   * すべての宛先で読み取りに失敗したときのエラーを組み立てます。
+   *
+   * @param key 読み取ったキーです。
+   * @param errors 収集した失敗です。
+   *
+   * @returns `KeyNotFoundError` を返します。
+   */
+  #notFound(key: string, errors: readonly PluginErrorRecord[]): KeyNotFoundError {
+    const args: KeyNotFoundErrorArgs = { key };
+
+    switch (errors.length) {
+      case 0: {
+        break;
+      }
+
+      case 1: {
+        const [firstError] = errors;
+
+        if (firstError !== undefined) {
+          args.cause = firstError.reason;
+        }
+
+        break;
+      }
+
+      default: {
+        args.cause = new PluginOperationAggregateError({
+          action: "read",
+          errors,
+          plugin: "storage",
+        });
+      }
+    }
+
+    return new KeyNotFoundError(args);
+  }
+
+  async #close(
+    operationVars: Map<string, unknown>,
+    signal: AbortSignal,
+    con: Connection,
+    progress: { pluginsStarted: boolean },
+  ): Promise<void> {
+    using _lock = await asyncmux(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con !== con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const { io } = this.#con;
+    using _ioLock = await io.lock({ signal });
+    const closeFns: [
+      () => Promise<void>,
+      () => Promise<void>,
+      plugin: "storage" | "middleware",
+      name: string,
+      index: number,
+    ][] = [];
+
+    // ストレージのクローズ処理を登録します。
+    // open と同じ方針でプラグインごとに複製し、並列実行中の変更が互いに見えないようにします。
+    for (const [index, leaf] of this.#pipeline.leaves.entries()) {
+      const createContext = (): CloseContext =>
+        new CloseContext({
+          vars: new Map(operationVars).entries(),
+          signal,
+        });
+      // 再試行は通常 close の失敗 (操作 signal の abort など) に引きずられないよう、新しいタイムアウト signal を使います。
+      const createRetryContext = (): CloseContext =>
+        new CloseContext({
+          vars: new Map(operationVars).entries(),
+          signal: AbortSignal.timeout(10e3),
+        });
+      closeFns.push([
+        (): Promise<void> => leaf.storage.close(createContext()),
+        (): Promise<void> => leaf.storage.retryClose(createRetryContext()),
+        "storage",
+        leaf.name,
+        index,
+      ]);
+    }
+
+    // ミドルウェアのクローズ処理を登録します。
+    for (const [index, plugin] of this.#pipeline.middlewares.entries()) {
+      const createContext = (): CloseContext =>
+        new CloseContext({
+          vars: new Map(operationVars).entries(),
+          signal,
+        });
+      // 再試行は通常 close の失敗 (操作 signal の abort など) に引きずられないよう、新しいタイムアウト signal を使います。
+      const createRetryContext = (): CloseContext =>
+        new CloseContext({
+          vars: new Map(operationVars).entries(),
+          signal: AbortSignal.timeout(10e3),
+        });
+      closeFns.push([
+        (): Promise<void> => plugin.close(createContext()),
+        (): Promise<void> => plugin.retryClose(createRetryContext()),
+        "middleware",
+        plugin.name,
+        index,
+      ]);
+    }
+
+    // すべての処理を並列に実行し、エラーが発生した場合は集約します。
+    progress.pluginsStarted = true;
+    const errors: {
+      name: string;
+      index: number;
+      plugin: "storage" | "middleware";
+      reason: unknown;
+    }[] = [];
+    const retries: (() => Promise<void>)[] = [];
+    await Promise.all(
+      closeFns.map(async ([f, retry, plugin, name, index]) => {
+        try {
+          await f();
+        } catch (ex) {
+          errors.push({
+            name,
+            index,
+            plugin,
+            reason: ex,
+          });
+          // 通常の close で再試行すると、close 失敗後に別の利用者が引き継いだ参照まで解放してしまいます。
+          retries.push(retry);
+        }
+      }),
+    );
+
+    if (errors.length > 0) {
+      // 失敗したプラグインだけを 1 回再試行します。
+      // 成功済みのプラグインを再 close すると、参照カウントが二重に解放され、共有している他の利用者の実体まで閉じてしまうためです。
+      await Promise.all(
+        retries.map(async (f) => {
           try {
-            await r.cancel(ex);
-          } catch {
-            // キャンセルに失敗しても元の例外の伝播を優先します。
+            await f();
+          } catch (ex) {
+            logger.error`Failed to retry closing a plugin: ${ex}`;
           }
-        }
-
-        ioLock.release();
+        }),
+      );
 
-        throw ex;
-      }
+      throw new PluginOperationAggregateError({
+        action: "close",
+        errors,
+      });
     }
+
+    this.#con = null;
   }
 
-  public has(options: HasOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<boolean>;
-  public has(
-    key: KeyofKeyValueMapping<TKeyValueMapping>,
-    options?: Omit<HasOptions, "key">,
-  ): Promise<boolean>;
-  public async has(...args: any): Promise<boolean> {
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
+  /**
+   * 書き込み失敗の集約と、成功した宛先への通知を行います。
+   *
+   * @param targets 書き込みを試みた対象です。
+   * @param failed 失敗した葉の集合です。
+   * @param errors 集約する失敗です。
+   * @param signal 中断シグナルです。
+   */
+  async #finishWrites(
+    targets: readonly {
+      readonly key: string;
+      readonly leaf: PipelineLeaf;
+    }[],
+    store: VariablesStore,
+    failed: ReadonlySet<PipelineLeaf>,
+    errors: PluginErrorRecord[],
+    signal: AbortSignal,
+  ): Promise<void> {
+    if (errors.length === 0) {
+      return;
     }
 
-    const [options] = parseInput(HasArgsSchema, args);
-    const { key, vars: varsOption, signal: signalOption } = options;
-
-    // キーがキースキーマに一致するかを検証します。
-    this.#resolveValueSchema(key);
-
-    const { ac, io } = this.#con;
-    const signal = combineSignals([ac.signal, signalOption]);
+    const error = new PluginOperationAggregateError({
+      action: "write",
+      errors,
+      plugin: "storage",
+    });
+    const notifyErrors: unknown[] = [];
+    await Promise.all(
+      targets.map(async (target) => {
+        // 失敗した宛先を除いたすべての宛先へ通知します。通知に失敗しても元の集約エラーは置き換えません。
+        if (failed.has(target.leaf)) {
+          return;
+        }
 
-    const store = this.#createOperationStore(varsOption);
+        try {
+          const c = new SetContext({
+            key: target.key,
+            store,
+            signal,
+          });
+          await target.leaf.storage.onOtherWriteError(c, error);
+        } catch (ex) {
+          notifyErrors.push(ex);
+        }
+      }),
+    );
 
-    using _lock = await asyncmux.readonly(this, signal);
-    // ロック待機中に接続状態が変更されていないか再確認します。
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
+    if (notifyErrors.length > 0) {
+      logger.error(new AggregateError(notifyErrors, "Failed to handle error"));
     }
 
-    // 存在確認に先立ち、各ミドルウェアの `use` を実行します。
-    // `use` による vars の変更は後続の解決・走査に引き継がれます。
-    const useContext = new HasContext({
-      key,
-      store,
-      signal,
-    });
-    await this.#use("read", useContext);
-    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
-    throwIfAborted(signal);
+    throw error;
+  }
 
-    using _ioLock = await io.rLock({
-      key,
-      signal,
-    });
-    // 登録順に走査し、いずれかのストレージに存在すれば true を返します。
-    // exists に失敗したときは次のストレージを試します。
-    const errors: PluginErrorRecord[] = [];
-    const resolver = this.#pipeline.createResolver({
-      key,
-      store,
-      signal,
-    });
+  /**
+   * ミドルウェアの `use` をオニオン実行し、失敗時は集約して投げます。
+   *
+   * 同一コンテキストオブジェクトを全ミドルウェアで共有し、`next` で下流をネスト実行するため、下流の `set` が上流の `await next()` 後の `get` に見えます。
+   * `encode`/`decode` と同じく `next()` の呼び出し規約を検証し、違反したときは操作を実行せず失敗させます (fail-close)。
+   * いずれかのミドルウェアが投げたときは即時に確定し、後段は実行しません (fail-fast)。
+   * 失敗は集約エラー (単一件) として投げます。
+   *
+   * @param action 集約エラーに付与する操作名です。
+   * @param c 共有の `use` コンテキストです。
+   */
+  async #use(
+    action: "read" | "write" | "delete" | "clear",
+    c: IMiddleware.UseContext,
+  ): Promise<void> {
+    throwIfAborted(c.signal);
 
-    for (const leaf of this.#pipeline) {
-      const resolved = resolver.resolve(leaf);
+    const middlewares = this.#pipeline.middlewares;
+    const dispatch = async (index: number): Promise<void> => {
+      const maybeMiddleware = middlewares[index];
 
-      try {
-        const c = new HasContext({
-          key: resolved.key,
-          store,
-          signal,
-        });
+      if (maybeMiddleware === undefined) {
+        return;
+      }
 
-        if (await leaf.storage.exists(c)) {
-          return true;
-        }
-      } catch (ex) {
-        if (signal.aborted) {
-          throw ex;
-        }
+      const middleware: UniKvsMiddleware = maybeMiddleware;
 
-        errors.push({
-          name: leaf.name,
-          index: leaf.index,
-          reason: ex,
-        });
+      let nextCalled = false;
+      let nextSettled = false;
+      let downstreamError: unknown;
+      let hasDownstreamError = false;
 
-        logger.error`Failed to check existence in a storage: ${ex}`;
-      }
-    }
+      function next(): Promise<void> {
+        if (nextCalled) {
+          // 2 回目以降の `next()` は下流を実行せず拒否だけを返します。
+          const rejection = Promise.reject(
+            new MiddlewareNextCalledMultipleTimesError({
+              name: middleware.name,
+              operation: "use",
+            }),
+          );
+          // 呼び出し側が切り離した場合の未処理 rejection を防ぎます。await したときは従来どおり拒否されます。
+          // oxlint-disable-next-line promise/prefer-await-to-then
+          rejection.catch(() => {});
 
-    // すべてのストレージで存在を確認できなかったときは結果が不明なため、get() と同様にエラーとして報告します。
-    if (errors.length > 0) {
-      throw this.#notFound(key, errors);
-    }
+          return rejection;
+        }
 
-    return false;
-  }
+        nextCalled = true;
 
-  public delete(options: DeleteOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<void>;
-  public delete(
-    key: KeyofKeyValueMapping<TKeyValueMapping>,
-    options?: Omit<DeleteOptions, "key">,
-  ): Promise<void>;
-  public async delete(...args: any): Promise<void> {
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
+        const promise = Promise.try(async () => {
+          try {
+            await dispatch(index + 1);
+          } catch (ex) {
+            // 下流の失敗を親自身の失敗と取り違えないよう、由来を記録します。
+            downstreamError = ex;
+            hasDownstreamError = true;
+            throw ex;
+          } finally {
+            nextSettled = true;
+          }
+        });
+        // 呼び出し側が切り離した場合の未処理 rejection を防ぎます。await したときは従来どおり拒否されます。
+        // oxlint-disable-next-line promise/prefer-await-to-then
+        promise.catch(() => {});
 
-    const [options] = parseInput(DeleteArgsSchema, args);
-    const { key, vars: varsOption, signal: signalOption } = options;
+        return promise;
+      }
 
-    // キーがキースキーマに一致するかを検証します。
-    this.#resolveValueSchema(key);
+      try {
+        await middleware.use(c, next);
+        throwIfAborted(c.signal);
+        if (!nextCalled) {
+          throw new MiddlewareNextNotCalledError({
+            name: middleware.name,
+            operation: "use",
+          });
+        }
 
-    const { ac, io } = this.#con;
-    const signal = combineSignals([ac.signal, signalOption]);
+        if (!nextSettled) {
+          throw new MiddlewareNextNotAwaitedError({
+            name: middleware.name,
+            operation: "use",
+          });
+        }
+      } catch (ex) {
+        // 中断による失敗はそのまま投げます。
+        if (c.signal.aborted && ex === c.signal.reason) {
+          throw ex;
+        }
 
-    const store = this.#createOperationStore(varsOption);
+        // 規約違反はプログラミングエラーであり、集約せずに投げます。
+        if (
+          ex instanceof MiddlewareNextNotCalledError ||
+          ex instanceof MiddlewareNextNotAwaitedError ||
+          ex instanceof MiddlewareNextCalledMultipleTimesError
+        ) {
+          throw ex;
+        }
 
-    using _lock = await asyncmux.readonly(this, signal);
-    // ロック待機中に接続状態が変更されていないか再確認します。
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
+        // `next()` から伝播した下流の失敗は再集約せず、そのまま投げます。
+        if (hasDownstreamError && ex === downstreamError) {
+          throw ex;
+        }
 
-    // 削除に先立ち、各ミドルウェアの `use` を実行します。
-    // `use` による vars の変更は後続の解決・削除に引き継がれます。
-    const useContext = new DeleteContext({
-      key,
-      store,
-      signal,
-    });
-    await this.#use("delete", useContext);
+        throw new PluginOperationAggregateError({
+          action,
+          errors: [
+            {
+              name: middleware.name,
+              index,
+              reason: ex,
+            },
+          ],
+          plugin: "middleware",
+        });
+      }
+    };
+    await dispatch(0);
+  }
 
+  /**
+   * プレーン値の並列書き込みを行います。
+   *
+   * @param io 多重化インスタンスです。
+   * @param signal 中断シグナルです。
+   * @param key 書き込みキーです。
+   * @param store 操作内で共有される変数ストアです。
+   * @param value 書き込む値です.
+   */
+  async #setPlain(
+    io: Asyncmux,
+    signal: AbortSignal,
+    key: string,
+    store: VariablesStore,
+    value: unknown,
+  ): Promise<void> {
+    const targets = await this.#pipeline.encode(
+      {
+        key,
+        store,
+        signal,
+      },
+      value,
+    );
     using _ioLock = await io.lock({
       key,
-      // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
       signal,
     });
-    // 全宛先を並列に削除し、失敗は宛先の index 付きで集約します。
     const errors: PluginErrorRecord[] = [];
-    const resolver = this.#pipeline.createResolver({
-      key,
-      store,
-      signal,
-    });
+    const failed = new Set<PipelineLeaf>();
     await Promise.all(
-      this.#pipeline.leaves.map(async (leaf) => {
-        const resolved = resolver.resolve(leaf);
-        const existsContext = new HasContext({
-          key: resolved.key,
-          store,
-          signal,
-        });
-        const deleteContext = new DeleteContext({
-          key: resolved.key,
-          store,
-          signal,
-        });
-
+      targets.map(async (target) => {
         try {
-          if (await leaf.storage.exists(existsContext)) {
-            await leaf.storage.delete(deleteContext);
-          }
+          const c = new SetContext({
+            key: target.key,
+            store,
+            signal,
+          });
+          await target.leaf.storage.write(c, target.data);
         } catch (ex) {
           errors.push({
-            name: leaf.name,
-            index: leaf.index,
+            name: target.leaf.name,
+            index: target.leaf.index,
             reason: ex,
           });
+          failed.add(target.leaf);
         }
       }),
     );
-
-    if (errors.length > 0) {
-      throw new PluginOperationAggregateError({
-        action: "delete",
-        errors,
-        plugin: "storage",
-      });
-    }
+    await this.#finishWrites(targets, store, failed, errors, signal);
   }
 
-  public async clear(options?: ClearOptions): Promise<void>;
-  public async clear(...args: any): Promise<void> {
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
-    }
-
-    const [options = {}] = parseInput(ClearArgsSchema, args);
-    const { vars: varsOption, signal: signalOption } = options;
-
-    const { ac, io } = this.#con;
-    const signal = combineSignals([ac.signal, signalOption]);
-
-    const store = this.#createOperationStore(varsOption);
+  /**
+   * ストリーム値の並列書き込みを行います。
+   *
+   * @param io 多重化インスタンスです。
+   * @param signal 中断シグナルです。
+   * @param key 書き込みキーです。
+   * @param store 操作内で共有される変数ストアです。
+   * @param value 書き込むストリームです。
+   */
+  async #setStream(
+    io: Asyncmux,
+    signal: AbortSignal,
+    key: string,
+    store: VariablesStore,
+    value: IReadableStream,
+  ): Promise<void> {
+    const streams = new Set<IReadableStream>([value]);
+    let tree;
 
-    using _lock = await asyncmux.readonly(this, signal);
-    // ロック待機中に接続状態が変更されていないか再確認します。
-    if (this.#con === null) {
-      throw new UniKvsIsNotOpenError();
+    try {
+      tree = await this.#pipeline.buildEncodeTree(
+        {
+          key,
+          store,
+          signal,
+        },
+        value,
+        streams,
+      );
+    } catch (ex) {
+      await cancelStreams(streams, ex);
+      throw ex;
     }
 
-    using _ioLock = await io.lock({ signal });
-    // 全ミドルウェアの `use` を実行します。
-    const useContext = new ClearContext({
-      store,
-      signal,
-    });
-    await this.#use("clear", useContext);
-    // `use` の完了直後に中断を確認し、後続処理での検出に依存しないようにします。
-    throwIfAborted(signal);
-    // 一括削除は全宛先で並列に実行し、失敗は宛先の index 付きで集約します。
+    using _ioLock = await io
+      .lock({
+        key,
+        signal,
+      })
+      .catch(async (ex) => {
+        // キーロックの待機中に中断されたときも、構築済みのストリームをキャンセルします。
+        // ソースストリームをロックしたまま残さないためです。
+        await cancelStreams(streams, ex);
+        throw ex;
+      });
+
     const errors: PluginErrorRecord[] = [];
+    const failed = new Set<PipelineLeaf>();
     await Promise.all(
-      this.#pipeline.leaves.map(async (leaf, index) => {
+      tree.targets.map(async (target) => {
         try {
-          const c = new ClearContext({
+          const c = new SetContext({
+            key: target.key,
             store,
             signal,
           });
-          await leaf.storage.clear(c);
+          const w = await target.leaf.storage.getWritable(c);
+          await target.stream.pipeTo(w, { signal });
         } catch (ex) {
+          // tee で分岐したストリームは、片方の分岐をキャンセルするまで他方が読み取ったチャンクを保持し続けるため、失敗時に放棄した分岐は確実にキャンセルします。
+          try {
+            await target.stream.cancel(ex);
+          } catch {
+            // キャンセルに失敗してもエラー集約を優先します。
+          }
+
           errors.push({
-            name: leaf.name,
-            index,
+            name: target.leaf.name,
+            index: target.leaf.index,
             reason: ex,
           });
+          failed.add(target.leaf);
         }
       }),
     );
+    await this.#finishWrites(tree.targets, store, failed, errors, signal);
+  }
 
-    if (errors.length > 0) {
-      throw new PluginOperationAggregateError({
-        action: "clear",
-        errors,
-        plugin: "storage",
-      });
-    }
+  /**
+   * 読み取り元のチェーン全体を逆順にデコードし、書き戻し対象向けに再エンコードして書き込みます。
+   *
+   * @param data 読み取ったデータです。
+   * @param hit 読み取り元の葉です。
+   * @param missing 読み取りに失敗または不在だった葉です。
+   * @param store 操作内で共有される変数ストアです。
+   * @param key キーです。
+   * @param signal 中断シグナルです。
+   * @param throwOnRepairDenied 書き戻し拒否をエラーとして投げるかどうかです。
+   *
+   * @returns デコード済みの原データを返します。
+   */
+  async #repairPlain(
+    data: unknown,
+    hit: ResolvedLeaf,
+    missing: readonly PipelineLeaf[],
+    store: VariablesStore,
+    key: string,
+    signal: AbortSignal,
+    throwOnRepairDenied: boolean,
+  ): Promise<unknown> {
+    const raw = await this.#pipeline.decode(
+      hit.leaf,
+      {
+        key,
+        store,
+        signal,
+      },
+      data,
+    );
+    await this.#pipeline.repair(
+      {
+        key,
+        store,
+        signal,
+      },
+      missing,
+      throwOnRepairDenied,
+      raw,
+      async (leaf, writeKey, input) => {
+        const c = new SetContext({
+          key: writeKey,
+          store,
+          signal,
+        });
+        await leaf.storage.write(c, input);
+      },
+    );
+
+    throwIfAborted(signal);
+
+    return raw;
   }
 }