@wcstack/state 2.2.0 → 2.4.0

package/dist/index.d.ts

@@ -68,9 +68,210 @@ type PathInfoSource =
 "binding"
 /** `$watch` の宣言キー */
  | "watch"
+/** `$scan` の `from` / `resetOn`（docs/state-scan-design.md §2-4） */
+ | "scan"
 /** ランタイム内部のパス翻訳（mapped な bind-component の外向き伝播）。検査しない */
  | "internal";
 
+/**
+ * 単一の自己再帰宣言。初版はアンカーと反復サブパスとも「固定プロパティ列の末尾に
+ * `.*` がひとつ」の形に限定する（docs/state-recursive-path-impl-plan.md §1-1）。
+ *
+ * 例: `$recursion = { "nodes.*": "children.*" }`
+ * - `anchor`         … `"nodes.*"`（深さ 0 のノードパス）
+ * - `repeat`         … `"children.*"`（1 段深くする相対サブパス）
+ * - `recursiveAnchor` … `"nodes.**"`
+ * - `anchorList`     … `"nodes"`
+ * - `repeatList`     … `"children"`
+ *
+ * リスト側の 2 つは宣言時に確定させる（静的側の `RecursionSpec` と同じ構成）。
+ * 各所で `lastIndexOf(DELIMITER)` の slice を繰り返すと、綴りの取り違えが分散する。
+ */
+interface IRecursionSpec {
+    readonly anchor: string;
+    readonly repeat: string;
+    /** `anchor` の `**` 形（`"nodes.**"`）。オーサリング層のパス解析で使う。 */
+    readonly recursiveAnchor: string;
+    /** `anchor` のリスト側（`"nodes"` — 末尾の `.*` を落とした形）。 */
+    readonly anchorList: string;
+    /** `repeat` のリスト側（`"children"`）。 */
+    readonly repeatList: string;
+}
+/**
+ * 展開済みの再帰 getter 1 本ぶんの素性。生成アクセサに紐づくメタデータで、
+ * ランタイムが読むのは深さ（`**` の束縛）と元の宣言（診断の名指し）の 2 つだけ。
+ * 具体パスは台帳のキー、`PathInfo` は読む側が intern 済みのものを持つので、ここには
+ * 重ねて持たない。
+ */
+interface IRecursionAccessor {
+    /** 元の宣言（`"nodes.**.total"`） */
+    readonly recursivePath: string;
+    /** 反復の段数（0 origin） */
+    readonly depth: number;
+}
+
+/**
+ * recursion/registry.ts
+ *
+ * state 1 つぶんの再帰レジストリ。宣言・`**` getter の定義・展開済みアクセサの台帳を
+ * 持ち、「具体パスを読む直前に、その深さのアクセサを生やす」遅延実体化を担う。
+ *
+ * 遅延であることは実装の**不変条件**である（Phase A の A6/A7）。そのパスを一度でも
+ * 読んでから生やしても、`isCacheable` が `wildcardCount > 0` だけでキャッシュ可を返す
+ * ため `undefined` が `dirty:false` で固定され、以後どう書いても回復しない。
+ * したがって実体化は `getByAddress` のキャッシュ参照**前**に置く（E5）。
+ *
+ * 寿命は state の世代と共にする。`_state` の再セットで `getterPaths` / `listPaths` は
+ * クリアされるので、レジストリも作り直す（§1-3）。ただし**生やしたアクセサは state
+ * オブジェクトの側に残る**ので、同じ state を再セットすると `getStateInfo` がそれを
+ * `getterPaths` に復元する。そのとき「もう生えているから何もしない」と早期 return して
+ * しまうと `listPaths` の登録だけが抜け落ちるため、生成物は WeakSet で見分けて
+ * 登録だけをやり直す。
+ */
+
+declare class RecursionRegistry {
+    readonly spec: IRecursionSpec;
+    private readonly _definitions;
+    private readonly _accessors;
+    /**
+     * `recursiveGetterOwning` の記憶。キーは添字を `*` に畳んだ形（`nodes.1.total` と `nodes.2.total`
+     * は 1 つ）、値は「その具体パスを展開形（またはその値の内側）として持つ `**` getter」、
+     * 無ければ null。
+     *
+     * 有界である: キーは添字を畳んだワイルドカード形のパス文字列で、`PathInfo` が intern する集合
+     * （バインディング・getter・API 引数に綴られたパスと、その展開形）の部分集合にしかならない。
+     * intern 済みパスの集合が有界であることは D10 で受け入れ済みなので、ここも同じ上限に収まる。
+     * 文字列は WeakSet に入らないので、寿命はレジストリ（＝ state の世代）と共にする。
+     */
+    private readonly _ownerByPath;
+    /**
+     * 書き込みのホットパス（`setByAddress`）向けの記憶。キーは intern 済みの `PathInfo` なので
+     * 寿命と上限は PathInfo の intern 集合と同じ（WeakMap）。畳み（split + Number + join）は
+     * miss のときだけ払う — 宣言のある state では**アンカー外を含む全書き込み**がここを通る
+     * （第 4 サイクルで実測: 畳みを毎回払うと `s.counter = i` で +100ns/書き込み）。
+     */
+    private readonly _ownerByPathInfo;
+    /**
+     * 読みのホットパス（`getByAddress`）向けの記憶。`_ownerByPathInfo` と対称で、キーは
+     * intern 済みの `PathInfo`、値は「そのパスの展開アクセサ」、展開形でなければ null。
+     * 宣言のある state では**アンカー外を含む全読み**（親ウォークの各段を含む）がここを
+     * 通るので、文字列キーの `Map.get` + `Set.has` + `startsWith` を毎回払わせない
+     * （第 5 サイクルで実測）。
+     *
+     * 読みの否定判定の記憶は**ここ 1 つ**（第 5 サイクル再検証で文字列キーの `_nonAccessors` を撤去 —
+     * 前段にこの記憶を置いた後は、PathInfo とパス文字列が 1:1 なので二重に持つだけだった）。
+     * 否定を記憶してよい根拠は、定義集合が state の世代内で不変であること —
+     * 同じ `PathInfo` は同じパス文字列なので、いちど「展開形でない」と決まった PathInfo が
+     * 後から実体化されることはない。実体化した側は `materializeForPathInfo` が
+     * `_define` の戻り値でそのまま記憶を更新する（否定が実体化を隠さない）。
+     */
+    private readonly _accessorByPathInfo;
+    /** `concretePathAt` の記憶（接尾辞 → 深さ順の具体パス）。 */
+    private readonly _concreteBySuffix;
+    private readonly _registeredListPaths;
+    constructor(spec: IRecursionSpec, state: object);
+    /**
+     * 作者が手で書いた具体パス（`get "nodes.*.children.*.total"()` / データプロパティ）が、宣言済み
+     * `**` getter の展開形と同名でないことを**構築時に**確かめる。
+     *
+     * `_define` の衝突検査は「その深さを最初に読んだとき」にしか走らないので、データが浅い間は
+     * 通り、木が 1 段深くなった瞬間にバインディングが落ちていた（第 3 サイクルのレビューで実測）。
+     * 前世代の生成物（own に残った生成 getter）は衝突ではない — 同じ state の再セットで必ず居る。
+     */
+    private _assertNoConcreteCollision;
+    /**
+     * 2 本の `**` getter が同じ具体パスへ展開しないことを、宣言だけから静的に確かめる。
+     *
+     * 衝突するのは「片方の接尾辞がもう片方の接尾辞の末尾で、差分が反復語の整数倍」の
+     * ときだけ（`nodes.**.total` と `nodes.**.children.*.total` は深さ k と k+1 で
+     * 同じ `nodes.*.children.*.total` になる）。検出しないと `_definitions` の挿入順で
+     * 最初に一致した方が無言で勝つ。
+     */
+    private _assertNoColliding;
+    /**
+     * `**` getter を 1 本でも宣言しているか。
+     * **テスト・診断専用**（ランタイムの経路は `_definitions.size` を直接見る）。
+     */
+    get hasDefinitions(): boolean;
+    /**
+     * その接尾辞が宣言済みの `**` getter と衝突するなら、その getter のパスを返す。
+     *
+     * 完全一致だけでは足りない。①反復語の整数倍だけ違う接尾辞は同じ族を指す
+     * （`_assertNoColliding` が宣言どうしについて既に見ている条件）②getter の**下**を
+     * 指す形（`nodes.**.total.x` / 反復語ぶんずれた `nodes.**.children.*.total.x`）は、
+     * getter が返したオブジェクトへ書いてキャッシュを汚し、次の無効化で無言に戻る。
+     * どちらも書き込みの入口（列挙より前）で止める — 述語は expand.ts の `coversSuffix`。
+     */
+    conflictingRecursiveGetter(suffix: string): string | null;
+    /**
+     * `recursiveGetterOwning` の intern 済み `PathInfo` 版（書き込みのホットパス用）。
+     * WeakMap の hit なら畳みも照合も払わない。
+     */
+    recursiveGetterOwningPath(pathInfo: IPathInfo): string | null;
+    /**
+     * 具体パスを展開形（またはその値の内側）として持つ `**` getter のパス。無ければ null。
+     * **実体化はしない。**
+     *
+     * `conflictingRecursiveGetter` の**具体パス版**で、`**` を経ない 2 つの入口が使う:
+     *
+     *  - バインド確立時のパス存在検査（`checkDeclaredPath`）。あの時点ではまだ生えて
+     *    いないので、素の存在検査では必ず「解決できない」になる。展開形そのもの
+     *    （`nodes.*.total`）だけでなく、その値の中を指す形（`nodes.*.stats.count` で
+     *    `get "nodes.**.stats"()` がオブジェクトを返す）も、通常の getter の下と同じく
+     *    評価しないと分からないので黙る側に倒す。
+     *  - 書き込みの入口（`setByAddress`）。`$setAll("nodes.*.children.*.total", [], v)` や
+     *    `this["nodes.1.total"] = v` は `**` を含まないので `setAllRecursive` の
+     *    読み取り専用検査を通らず、未実体化なら fast path が行オブジェクトへ素の
+     *    プロパティとして書いてしまう（ノードを汚し、代入値が `dirty:false` で載って
+     *    以後 getter が評価されない）。展開形への書き込みは、実体化の前後に関わらず
+     *    `wcs/recursion-readonly` で止める。
+     */
+    recursiveGetterOwning(concretePath: string): string | null;
+    /** 具体パスが宣言済み `**` getter の展開形そのものなら、その getter のパス。 */
+    private _matchExpansion;
+    /**
+     * `materializeFor` の `PathInfo` 版。**読みのホットパス（`getByAddress`）専用**で、
+     * 判定そのものは `materializeFor` に委ね、結果（否定を含む）を PathInfo に記憶する。
+     * 書き側の `recursiveGetterOwningPath` と対称。
+     */
+    materializeForPathInfo(stateElement: IStateElement, pathInfo: IPathInfo): IRecursionAccessor | null;
+    /**
+     * 具体パスが再帰 getter の展開形なら、そのアクセサを（未登録なら生やして）返す。
+     * 該当しなければ null。読みは `materializeForPathInfo` を通るので、ここへ来るのは
+     * 記憶が外れたときだけ — 判定は接頭辞 1 回で抜け、ここでは否定を記憶しない（記憶は
+     * `materializeForPathInfo` の PathInfo キーの 1 か所）。
+     * （`**` getter の無い空レジストリを弾くのは呼び出し側の役目。）
+     */
+    materializeFor(stateElement: IStateElement, concretePath: string): IRecursionAccessor | null;
+    private _define;
+    /**
+     * 経路上のリストパスを `listPaths` に載せる（E4）。`setPathInfo(path, "for")` は
+     * 使えない — あちらは `elementPaths` にも入れて `setByAddress` の swap 経路
+     * （`isSwappable`）を変えてしまう。ここで要るのは「依存ウォークがこのパスを
+     * リストとして展開する」ことだけ。
+     */
+    private _registerListPaths;
+    /**
+     * この世代が生やしたもの（own の生成アクセサ・依存辺・キャッシュ）を忘れる（state の
+     * 再セット時、`getStateInfo` の再収集より**前**に呼ぶ）。実体は generation.ts。
+     */
+    forgetGenerated(stateElement: IStateElement, previousState: object): ReadonlySet<string>;
+    /**
+     * `**` 接尾辞の深さ `depth` の具体パス（`concretePathAt` の記憶付き版）。
+     * 束縛形の読み（`this["nodes.**.value"]` / 省略形 `$getAll`）は再帰 getter の評価ごとに
+     * ここを通るので、深さぶんの文字列連結とワイルドカード数えを毎回やり直さない。
+     * 上限は「接尾辞の種類 × 128」で有界（上限超過は `concretePathAt` が throw するので載らない）。
+     */
+    concretePathAt(suffix: string, depth: number): string;
+    /** 展開済みアクセサのメタデータ（深さ解決・診断・テスト用）。 */
+    accessorFor(concretePath: string): IRecursionAccessor | null;
+    /**
+     * これまでに実体化した具体パスの一覧。**テスト専用**（「読んだ深さだけが生える」という
+     * 遅延実体化の不変条件を外から確かめる口。ランタイムはどの経路からも呼ばない）。
+     */
+    get materializedPaths(): ReadonlySet<string>;
+}
+
 declare const setLoopContextSymbol: unique symbol;
 declare const getByAddressSymbol: unique symbol;
 declare const hasByAddressSymbol: unique symbol;
@@ -111,6 +312,14 @@ interface IStateElement {
     readonly dynamicDependency: Map<string, string[]>;
     readonly staticDependency: Map<string, string[]>;
     readonly version: number;
+    /**
+     * state の世代。`_state` の差し替えごとに 1 つ進み、キャッシュ項目の印になる
+     * （cache/types.ts の `generation`）。`version`（更新サイクルの番号）とは別のカウンタ。
+     * optional なのはテスト用モック互換のため（undefined のモックが載せた項目は
+     * undefined 同士で一致し、従来どおりヒットする — `__tests__/proxy.getByAddress.test.ts`
+     * の「キャッシュがある場合はキャッシュを返すこと」が固定する）。
+     */
+    readonly stateGeneration?: number;
     readonly rootNode: Node;
     readonly boundComponentStateProp: string | null;
     /**
@@ -196,6 +405,12 @@ interface IStateElement {
      * optional なのはテスト用モック互換のため（undefined は「宣言なし」扱い）。
      */
     readonly watchPaths?: ReadonlySet<string> | null;
+    /**
+     * `$scan` の `from` パスの集合（docs/state-scan-design.md §2-1）。`watchPaths` と並んで
+     * setByAddress の旧値キャプチャのゲートになる（fold に `prev` を渡すため）。
+     * 宣言が無ければ null / undefined。optional なのはテスト用モック互換のため。
+     */
+    readonly scanPaths?: ReadonlySet<string> | null;
     /**
      * パスを依存グラフへ登録する。DOM バインディング登録（BindingSession）のほか、
      * `$watch` 宣言（processWatchDeclaration）からも呼ばれる — 静的依存グラフに
@@ -212,6 +427,32 @@ interface IStateElement {
     readonly hydratedFromSsr?: boolean;
     /** ボリュームのアクセサ登録（webComponent/volume.ts 専用） */
     defineTreeAccessor(path: string, descriptor: PropertyDescriptor): void;
+    /**
+     * リストパスとしてだけ登録する（`listPaths` に足す）。`setPathInfo(path, "for")` は
+     * `elementPaths` にも入れて `setByAddress` の swap 経路（`isSwappable`）を変えるので、
+     * 「依存ウォークがこのパスをリストとして展開する」ことだけが要る用途には使えない
+     * （docs/state-recursive-path-impl-plan.md §3-2 の E4）。
+     */
+    addListPath(path: string): void;
+    /**
+     * state オブジェクト自身＋プロトタイプチェーンから descriptor を引く（生成物と作者定義の
+     * 見分けに使う）。class 構文の getter は prototype に載るので own だけでは足りない。
+     */
+    findStateDescriptor(path: string): PropertyDescriptor | undefined;
+    /**
+     * この state に `$recursion` 宣言があるか。偽のとき getByAddress の遅延実体化と
+     * get トラップの `**` 解決は boolean 判定 1 個で抜ける（hasMounts と同じ D18 の形）。
+     * 読み手は必ずこのゲートを先に見て、真なら `recursionRegistry` を `!` で読む。
+     * 必須メンバー（実装は `State` のみ）。`any` 型のテスト用モックがフィールドを持たなくても
+     * 通るのは vitest が型検査をしないからで、その場合 `undefined === true` は偽なので再帰の
+     * 経路に入らないだけ — 型としては必須。
+     */
+    readonly hasRecursion: boolean;
+    /**
+     * 再帰レジストリ（宣言が無ければ null。`hasRecursion === true` なら非 null）。registry.ts は
+     * このファイルの IStateElement を参照するが、`import type` どうしなので実行時の循環にはならない。
+     */
+    readonly recursionRegistry: RecursionRegistry | null;
     setPathInfo(path: string, bindingType: BindingType, source?: PathInfoSource): void;
     addStaticDependency(parentPath: string, childPath: string): boolean;
     addDynamicDependency(fromPath: string, toPath: string): boolean;
@@ -683,6 +924,8 @@ interface WcsStateApi {
     readonly $7: number;
     readonly $8: number;
     readonly $9: number;
+    readonly [key: `${string}.**.${string}`]: any;
+    readonly [key: `${string}.**`]: any;
 }
 /**
  * state定義オブジェクト内の `this` の型。
@@ -933,9 +1176,13 @@ type DevtoolsEvent = {
     readonly stateElement?: IStateElement;
 } | {
     readonly type: "state:watch-error";
-    /** throw 元。cur の評価（getter）とハンドラ本体では原因も直し方も違う */
-    readonly phase: "prime" | "evaluate" | "handler";
-    /** `$watch` の宣言キー（ワイルドカードを含む生のパス） */
+    /**
+     * throw 元。cur の評価（getter）とハンドラ本体では原因も直し方も違う。
+     * `$scan`（scan/scanReport.ts）は `evaluate`（source / 出力の読み）・`fold`（fold の throw・
+     * Promise の戻り値・接ぎ木で getter になった from）・`write`（出力の書き込み）を使う
+     */
+    readonly phase: "prime" | "evaluate" | "handler" | "fold" | "write";
+    /** `$watch` の宣言キー（ワイルドカードを含む生のパス）。`$scan` は `$scan.<出力名>` */
     readonly path: string;
     readonly error: unknown;
 } | {
@@ -957,7 +1204,7 @@ type DevtoolsEvent = {
 } | {
     readonly type: "state:path-unresolved";
     /** 書き手が書いた面。診断 code が binding / watch で変わる */
-    readonly source: "binding" | "watch";
+    readonly source: "binding" | "watch" | "scan";
     /** 宣言されたパス（ワイルドカードを含む生の文字列） */
     readonly path: string;
     /** 解決に失敗したセグメント */
@@ -1075,6 +1322,20 @@ declare class State extends HTMLElementBase implements IStateElement {
     private _crossRowListPaths;
     private _indexDependentGetterPaths;
     private _initialized;
+    /**
+     * 初期化（`_initialize`）が失敗した（#257）。`_initialized` の裏返しではない —
+     * 「まだ初期化していない」と「もう初期化できない」を取り違えると、復旧不能の
+     * 要素に `setInitialState` が効いたように見える。真にするのは
+     * `_failInitializeLoudly` だけ。
+     */
+    private _initializeFailed;
+    /**
+     * この接続サイクルの失敗は**もう着地した**（#257）。設定エラーの fail-fast
+     * （`_failInitialization` と `initializeMountScope` の catch）は自分で promise を
+     * 解決してから raise する — connectedCallbackPromise を**解決**する側のクラスなので、
+     * 下の loud な着地（reject ＋ 診断）に載せ替えると意味論が変わる。接続ごとに畳む。
+     */
+    private _initializationLanded;
     private _initializePromise;
     private _resolveInitialize;
     private _connectedCallbackPromise;
@@ -1086,6 +1347,7 @@ declare class State extends HTMLElementBase implements IStateElement {
     private _resolveSetState;
     private _listPaths;
     private _listKeys;
+    private _recursionRegistry;
     private _elementPaths;
     private _getterPaths;
     private _setterPaths;
@@ -1093,7 +1355,39 @@ declare class State extends HTMLElementBase implements IStateElement {
     private _dynamicDependency;
     private _staticDependency;
     private _pathSet;
+    /**
+     * state の世代（issue #258 の X10）。`_state` の差し替えごとに 1 つ進み、キャッシュ項目の
+     * 印になる（cache/types.ts の `generation`）。`_version`（更新サイクルの番号）とは別の
+     * カウンタで、増える条件が違う — 再セットは世代だけを進める
+     * （`__tests__/integration.stateGenerationReset.test.ts` の
+     * 「再セットは世代だけを進め、version は動かさない」が固定する）。
+     */
+    private _stateGeneration;
+    /**
+     * この要素が受け取った `setPathInfo` の台帳（issue #258 の X7）。パス → 種別と呼び出し元。
+     *
+     * `_pathSet` / `_listPaths` / `_elementPaths` は再セットでクリアされるが、それらを登録した
+     * バインドは生き残る（再セットは DOM を作り直さない）。台帳が空のままだと依存ウォークが
+     * `items` をリストとして展開できず、全リスト書き込みが「非リストのアドレスにワイルドカードを
+     * 展開できない」で恒久的に throw する（値と DOM は追従するが、書き込みのたびに投げ続ける）。
+     * クリアのあと、この台帳から作り直す（`_rebuildPathInfo`）。
+     *
+     * `source === "internal"`（再帰の生成アクセサ・ボリュームのツリーアクセサ）は載せない。
+     * あれらは生やした機構が新しい世代で登録し直す（recursion/registry.ts の `_define`）。
+     */
+    private _pathRegistrations;
+    /**
+     * これまでのどの世代かで再帰レジストリが実体化した具体パス（`nodes.*.total` 等）の累積。
+     * 再セットのたびに `forgetGenerated` の戻り値を足し、`_rebuildPathInfo` の除外に使う。
+     *
+     * 除外は**世代を跨いで累積する**。読みを挟まない連続した再セットでも、生成アクセサの具体パスを
+     * 指す静的辺（`nodes.*` → `nodes.*.total`）が戻らないことは、
+     * `__tests__/integration.stateGenerationReset.test.ts` の
+     * 「読みを挟まない 3 連続の再セットで静的辺が戻らない」が固定する。
+     */
+    private _generatedPaths;
     private _watchPaths;
+    private _scanPaths;
     private _version;
     private _rootNode;
     private _boundComponent;
@@ -1125,6 +1419,10 @@ declare class State extends HTMLElementBase implements IStateElement {
      * ルートより先に接続されてもよい — ルート登録が保留分を引き取る（V5）。
      */
     private _initializeVolume;
+    /**
+     * 初回マウントのロードと登録。戻り値は「この接続で初期化を**完了**したか」で、
+     * `false` は失敗ではなく**中断**（ロード中に要素が剥がされた — 下の注記）。
+     */
     private _initialize;
     /**
      * 設定エラーでの fail-fast。initializePromise 等を解決してから raise する —
@@ -1134,6 +1432,54 @@ declare class State extends HTMLElementBase implements IStateElement {
      * として loud に残る。
      */
     private _failInitialization;
+    /**
+     * `_initialize` の失敗の着地（#257）。旧挙動は「throw が connectedCallback の外へ
+     * 出るだけ」で、`_initializePromise` も `_connectedCallbackPromise` も永久に未解決の
+     * まま残り、作者が受け取るのは診断ではなく無言のハングだった。載るのは
+     * `_initialize` が投げうるもの全部 — `_state` セッタの宣言検証（$recursion /
+     * $commandTokens / $eventTokens / $on / $streams / $listKeys / $watch）、
+     * `_loadStateFromSource` のロード失敗（src の拡張子・json のパース・内包スクリプト・
+     * 外部モジュール）、SSR データの merge、そして `setStateElement` の
+     * 「1 rootNode 1 ツリー」違反（**別の**要素が 2 本目に来た形 — 同じ要素の再登録は
+     * 冪等なので、ロード中の remove → append はここへ来ない）。
+     *
+     * 載**らない**もの: ロード中に要素が剥がされた形。作者のミスが 1 つも無いので
+     * 初期化失敗ではなく中断として扱う（`_initialize` が `false` を返す）。
+     *
+     * もう 1 つ載らないのがボリューム（`mount=`）の失敗。`_initializeVolume` の catch が
+     * 3 つの promise（initialize / loading / connectedCallback）を自分で解決してから raise し、
+     * `connectedCallback` のボリューム分岐はそれを包まないので、ボリュームはこの着地に
+     * 載らず connectedCallbackPromise を**拒否しない**。自前の報告が出るかどうかは失敗の
+     * 種類による。報告が無い形では、逃げ方は `name=`（`_failInitialization` の注記）と
+     * 同じで、throw はカスタム要素リアクションが捨てる戻り Promise へ出ていく
+     * （ブラウザのコンソールには "Uncaught (in promise)" として残るが、promise を待つ側
+     * ＝ renderToString・mount・テストレシピには届かない）。失敗箇所ごとの正確な挙動は
+     * `__tests__/integration.initFailureDiagnostics.test.ts` が固定している。挙動はこの
+     * PR では変えない（枠の寿命は別 Issue）。
+     *
+     * `connectedCallback` が `_initialize` より前に await する 2 つ
+     * （`_initializeDCC` / `_initializeBindWebComponent`）の raise も同じ着地に載る。
+     * 特に「初期化に失敗した要素の再接続」は `bindWebComponent` → `setInitialState` の
+     * 復旧不能 raise でそこへ来るので、包まないと診断ゼロで素通りする。
+     *
+     * `_failInitialization`（設定エラーの fail-fast）との違いは 1 つ:
+     * **connectedCallbackPromise を reject する**。ここまで来た要素は state を 1 つも
+     * 持たない ＝ このツリーは存在しない。resolve すると、それを待つ消費者
+     * （@wcstack/server の renderToString・@wcstack/testing の mount・README の
+     * テストレシピ）に「準備完了」と嘘をつく。下の SSR 経路（_rejectConnectedCallback）と
+     * 同じ規範で、そちらと同じく**元のエラーをそのまま**投げ直す。
+     *
+     * `initializePromise` は従来どおり**解決**する（reject しない）。
+     * `waitForStateInitialize` はページ中の全 `<wcs-state>` の initializePromise を
+     * `Promise.all` で待つので、reject にすると 1 要素の設定ミスが無関係な
+     * バインディングまで道連れになる（_failInitialization の注記と同じ理由）。
+     *
+     * 後始末はしない: `_initialized` を立てないので `disconnectedCallback` は初期化前
+     * ガードで抜ける。`$listKeys` / `$watch` のようにセッタの後半で落ちた形では
+     * `$on` の購読と stream registry が残るが、この要素は復旧不能（setInitialState が
+     * throw する）なので、残骸は要素ごと捨てる前提で放置する。
+     */
+    private _failInitializeLoudly;
     private _initializeBindWebComponent;
     private _callStateConnectedCallback;
     private _initializeDCC;
@@ -1145,7 +1491,10 @@ declare class State extends HTMLElementBase implements IStateElement {
     get connectedCallbackPromise(): Promise<void>;
     get listPaths(): Set<string>;
     get listKeys(): ListKeyMap | null;
+    get hasRecursion(): boolean;
+    get recursionRegistry(): RecursionRegistry | null;
     get watchPaths(): ReadonlySet<string> | null;
+    get scanPaths(): ReadonlySet<string> | null;
     get elementPaths(): Set<string>;
     /**
      * ボリューム（webComponent/volume.ts）のアクセサ登録: ツリーパスをキーにした
@@ -1161,6 +1510,8 @@ declare class State extends HTMLElementBase implements IStateElement {
     enableUpdatedCallback(): void;
     /** enable-ssr スナップショットから初期化されたか（D14 — webComponent/volume.ts が読む）。 */
     get hydratedFromSsr(): boolean;
+    addListPath(path: string): void;
+    findStateDescriptor(path: string): PropertyDescriptor | undefined;
     defineTreeAccessor(path: string, descriptor: PropertyDescriptor): void;
     get getterPaths(): Set<string>;
     get setterPaths(): Set<string>;
@@ -1168,6 +1519,8 @@ declare class State extends HTMLElementBase implements IStateElement {
     get dynamicDependency(): Map<string, string[]>;
     get staticDependency(): Map<string, string[]>;
     get version(): number;
+    /** state の世代（キャッシュ項目の印の正本 — cache/types.ts の `generation`）。 */
+    get stateGeneration(): number;
     get rootNode(): Node;
     get boundComponentStateProp(): string | null;
     get hasMounts(): boolean;
@@ -1208,6 +1561,24 @@ declare class State extends HTMLElementBase implements IStateElement {
      */
     addStaticDependency(sourcePath: string, targetPath: string): boolean;
     setPathInfo(path: string, bindingType: BindingType, source?: PathInfoSource): void;
+    /**
+     * 再セットで消した経路情報を、生き残ったバインドの登録から作り直す（issue #258 の X7）。
+     *
+     * `_pathSet.clear()` は残す。あのクリアには、`forgetGeneration` が外した静的辺を「行が
+     * 作り直されたときに登録し直させる」自己修復が乗っている（辺が戻ることは
+     * `__tests__/integration.stateGenerationReset.test.ts` の
+     * 「静的な辺 nodes.* → nodes.*.total が戻る」が固定する）。消したうえで、生きているバインド
+     * ぶんだけ `setPathInfo` をやり直す — `$recursion` のアンカーで既に同じことをしている手口を、
+     * バインド全体へ広げたもの。
+     *
+     * `_generatedPaths`（これまでの世代の生成アクセサの具体パス）は張り直さない。行バインドが
+     * 名指していても、新しい世代ではまだ実体化されていないため（recursion/generation.ts）。読みが
+     * 実体化したときに `defineTreeAccessor` が登録し直す。
+     *
+     * 反復中に `setPathInfo` が台帳へ書き戻す（既存キーの上書きのみで新キーは増えない）ので、
+     * 誤解を避けるためスナップショットを取ってから回す。
+     */
+    private _rebuildPathInfo;
     private _createState;
     createStateAsync(mutability: Mutability, callback: (state: IStateProxy) => Promise<void>): Promise<void>;
     createState(mutability: Mutability, callback: (state: IStateProxy) => void): void;