@wcstack/state 1.23.0 → 1.25.0

package/dist/index.esm.js

@@ -1918,7 +1918,6 @@ function setLastListValueByAbsoluteStateAddress(address, value) {
     lastListValueByAbsoluteStateAddress.set(address, value);
 }
 
-const setLoopContextAsyncSymbol = Symbol("$$setLoopContextAsync");
 const setLoopContextSymbol = Symbol("$$setLoopContext");
 const getByAddressSymbol = Symbol("$$getByAddress");
 const hasByAddressSymbol = Symbol("$$hasByAddress");
@@ -2489,6 +2488,54 @@ function detachCheckboxEventHandler(binding) {
     return false;
 }
 
+/**
+ * captureHandlerRejection.ts
+ *
+ * state 側ハンドラ（`$on` の event-token subscriber、`onXxx:` の state メソッド、
+ * DOM イベント起点の command-token emit）の戻り値を受け取り、Promise が混ざって
+ * いれば reject を捕捉して報告する。
+ *
+ * なぜ必要か:
+ * 発火経路はハンドラの完了を待たない。戻り値は `Token.emit` の結果配列にしか現れず、
+ * 呼び出し側（eventTokenHandler / handler）はそれを捨てている。そのため **async
+ * ハンドラが reject すると unhandled rejection になり**、しかも「どのハンドラで
+ * 落ちたか」の手掛かりがスタックにしか残らない（特性化:
+ * `__tests__/poc.asyncOnLoopContext.test.ts`）。
+ *
+ * 握り潰しではない:
+ * 可視性は `console.error` で保たれ、state 名・ハンドラ名が付く分むしろ特定は容易に
+ * なる。非同期の失敗を「例外の伝播」ではなく「診断可能な報告」に落とすのは
+ * never-throw（async-io-node-guidelines.md §3.6）と同じ方針であり、I/O ノードが
+ * `error` プロパティへ流すのと同じ位置づけの、state 側ハンドラ版にあたる。
+ *
+ * 同期 throw はここを通らない（従来どおり呼び出し元へ伝播する）。プログラマエラーを
+ * loud に落とす `raiseError` の挙動は一切変えない。
+ */
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
+/**
+ * @param result   ハンドラ呼び出しの戻り値。`Token.emit` の結果配列（subscriber ごとの
+ *                 戻り値）と、単一ハンドラの戻り値の両方を受ける。
+ * @param describe 報告に載せるハンドラの識別名（例: `$on."rowFailed" of state "default"`）。
+ */
+function captureHandlerRejection(result, describe) {
+    // emit は subscriber ごとの戻り値配列。単一ハンドラの戻り値はそのまま届く。
+    const values = Array.isArray(result) ? result : [result];
+    for (const value of values) {
+        if (!isThenable(value)) {
+            continue;
+        }
+        // Promise.resolve は native Promise をそのまま返すため、catch の登録によって
+        // 元の Promise が handled になる（thenable は同値の Promise に包まれる）。
+        Promise.resolve(value).catch((error) => {
+            console.error(`[wcstack/state] ${describe} rejected.`, error);
+        });
+    }
+}
+
 // command-token / event-token が共有する pub/sub プリミティブ。
 // _subscribers は Set のため挿入順を保持する。
 // emit() は subscribe() された順に呼び出され、戻り値配列も同じ順序で返る。
@@ -2654,11 +2701,14 @@ function attachEventTokenHandler(binding) {
         }
         const loopContext = getLoopContextByNode(element);
         stateElement.createStateAsync("writable", async (state) => {
-            state[setLoopContextSymbol](loopContext, () => {
+            const results = state[setLoopContextSymbol](loopContext, () => {
                 const indexes = loopContext?.listIndex.indexes ?? [];
                 const token = getOrCreateEventToken(stateElement, tokenName);
                 return token.emit(state, event, ...indexes);
             });
+            // この経路はハンドラの完了を待たない（emit の戻り値はここでしか見えない）。
+            // async な $on ハンドラの reject を unhandled にせず報告へ落とす。
+            captureHandlerRejection(results, `$on."${tokenName}" of state "${stateName}"`);
         });
     };
     element.addEventListener(eventName, handler);
@@ -2736,7 +2786,7 @@ const stateEventHandlerFunction = (stateName, handlerName, modifiers, statePathI
     const loopContext = getLoopContextByNode(node);
     const isCommand = isCommandTokenPath(handlerName);
     stateElement.createStateAsync("writable", async (state) => {
-        state[setLoopContextSymbol](loopContext, () => {
+        const results = state[setLoopContextSymbol](loopContext, () => {
             const indexes = loopContext?.listIndex.indexes ?? [];
             if (isCommand) {
                 // command token を解決して emit。引数はハンドラ呼び出しと同じく (event, ...listIndexes) を透過する。
@@ -2752,6 +2802,9 @@ const stateEventHandlerFunction = (stateName, handlerName, modifiers, statePathI
             }
             return Reflect.apply(handler, state, [event, ...indexes]);
         });
+        // eventTokenHandler と同じく、この経路もハンドラの完了を待たない。async な
+        // state メソッド / command subscriber の reject を unhandled にせず報告へ落とす。
+        captureHandlerRejection(results, `"${handlerName}" of state "${stateName}"`);
     });
 };
 function attachEventHandler(binding) {
@@ -3026,14 +3079,53 @@ function matchWriteReceipt(node, member) {
     return null;
 }
 
+/**
+ * occurrenceWrite.ts
+ *
+ * wc-bindable の `semantics: "event"` を宣言した property から届いた値を state へ書き込む
+ * 間だけ、same-value guard（`config.sameValueGuard`・既定 ON）を 1 回分だけ無効化する
+ * one-shot トークン。
+ *
+ * 背景:
+ * same-value guard は primitive が `Object.is` 同値なら set / enqueue / 依存伝播 / DOM 適用 /
+ * `$updatedCallback` をまるごとスキップする。current value（state）にとっては正しい最適化だが、
+ * occurrence（同じ payload でも「もう一度起きた」ことに意味がある）へ適用すると発生を取りこぼす。
+ * どちらであるかは producer の declaration が `semantics` で宣言する
+ * （docs/architecture-hardening/12-wc-bindable-observable-inventory.md）。
+ *
+ * one-shot にしている理由:
+ * フラグを書き込みの呼び出しスタック全体へ張ると、その内側で走る `$updatedCallback` や
+ * 依存伝播が行う無関係な書き込みまでガードを失う。`setByAddress` が最初のガード評価で
+ * トークンを消費するため、影響は目的の 1 write に閉じる。
+ */
+let pending = false;
+/** 直後の 1 write を occurrence として扱う。必ず `endOccurrenceWrite` と対で使う。 */
+function beginOccurrenceWrite() {
+    pending = true;
+}
+/** 未消費のトークンを破棄する（write が setByAddress へ到達しなかった場合の後始末）。 */
+function endOccurrenceWrite() {
+    pending = false;
+}
+/**
+ * ガード評価側が呼ぶ。`true` を返したら、その 1 回だけ same-value guard を飛ばす。
+ * トークンは呼んだ時点で消費される。
+ */
+function consumeOccurrenceWrite() {
+    if (!pending)
+        return false;
+    pending = false;
+    return true;
+}
+
 const handlerByHandlerKey = new Map();
 // binding を強参照しない台帳（handlerBindingRegistry.ts のリーク解説を参照）
 const bindingRegistry = createHandlerBindingRegistry();
 const producerValueObserversByNode = new WeakMap();
 const DEFAULT_GETTER = (e) => e.detail;
-function getHandlerKey(binding, eventName, hasGetter) {
+function getHandlerKey(binding, eventName, hasGetter, isOccurrence) {
     const filterKey = binding.inFilters.map(f => f.filterName + '(' + f.args.join(',') + ')').join('|');
-    return `${binding.stateName}::${binding.propName}::${binding.statePathName}::${eventName}::${filterKey}::${hasGetter ? 'g' : 'n'}`;
+    return `${binding.stateName}::${binding.propName}::${binding.statePathName}::${eventName}::${filterKey}::${hasGetter ? 'g' : 'n'}::${isOccurrence ? 'o' : 's'}`;
 }
 function getEventName(binding) {
     const tagName = binding.node.tagName.toLowerCase();
@@ -3069,7 +3161,20 @@ function getValueGetter(binding) {
     }
     return null;
 }
-const twowayEventHandlerFunction = (stateName, propName, statePathName, inFilters, valueGetter) => (event) => {
+/**
+ * producer が `semantics: "event"` を宣言した property か。occurrence は同じ payload でも
+ * 「もう一度起きた」ことに意味があるため、state への書き込みで same-value guard を通さない
+ * （docs/async-io-node-guidelines.md §3.3.1 の `event`）。宣言が無い property は従来どおり
+ * — 未指定は「未指定」であって state ではないので、挙動は変えない。
+ */
+function isOccurrenceProperty(binding) {
+    const customTagName = getCustomElement(binding.node);
+    if (customTagName === null)
+        return false;
+    const propDesc = readBindableDeclaration(binding.node)?.knownProperties.get(binding.propName);
+    return propDesc?.semantics === "event";
+}
+const twowayEventHandlerFunction = (stateName, propName, statePathName, inFilters, valueGetter, isOccurrence) => (event) => {
     const node = event.target;
     if (node === null) {
         console.warn(`[@wcstack/state] event.target is null.`);
@@ -3155,11 +3260,21 @@ const twowayEventHandlerFunction = (stateName, propName, statePathName, inFilter
     }
     const loopContext = getLoopContextByNode(node);
     const commitToState = () => {
-        stateElement.createState("writable", (state) => {
-            state[setLoopContextSymbol](loopContext, () => {
-                state[statePathName] = filteredNewValue;
+        // occurrence は同値でも取りこぼしてはならない（§3.3.1 `event`）。トークンは
+        // setByAddress の最初のガード評価で消費されるため、この write 1 回だけに効く。
+        if (isOccurrence)
+            beginOccurrenceWrite();
+        try {
+            stateElement.createState("writable", (state) => {
+                state[setLoopContextSymbol](loopContext, () => {
+                    state[statePathName] = filteredNewValue;
+                });
             });
-        });
+        }
+        finally {
+            if (isOccurrence)
+                endOccurrenceWrite();
+        }
     };
     if (propagationContext !== null) {
         runWithPropagationContext(propagationContext, commitToState);
@@ -3203,10 +3318,11 @@ function attachTwowayEventHandler(binding) {
     if (isPossibleTwoWay(binding.node, binding.propName) && binding.propModifiers.indexOf('ro') === -1) {
         const eventName = getEventName(binding);
         const valueGetter = getValueGetter(binding);
-        const key = getHandlerKey(binding, eventName, valueGetter !== null);
+        const isOccurrence = isOccurrenceProperty(binding);
+        const key = getHandlerKey(binding, eventName, valueGetter !== null, isOccurrence);
         let twowayEventHandler = handlerByHandlerKey.get(key);
         if (typeof twowayEventHandler === "undefined") {
-            twowayEventHandler = twowayEventHandlerFunction(binding.stateName, binding.propName, binding.statePathName, binding.inFilters, valueGetter);
+            twowayEventHandler = twowayEventHandlerFunction(binding.stateName, binding.propName, binding.statePathName, binding.inFilters, valueGetter, isOccurrence);
             handlerByHandlerKey.set(key, twowayEventHandler);
         }
         binding.node.addEventListener(eventName, twowayEventHandler);
@@ -3228,7 +3344,7 @@ function detachTwowayEventHandler(binding) {
     if (isPossibleTwoWay(binding.node, binding.propName) && binding.propModifiers.indexOf('ro') === -1) {
         const eventName = getEventName(binding);
         const valueGetter = getValueGetter(binding);
-        const key = getHandlerKey(binding, eventName, valueGetter !== null);
+        const key = getHandlerKey(binding, eventName, valueGetter !== null, isOccurrenceProperty(binding));
         const twowayEventHandler = handlerByHandlerKey.get(key);
         if (typeof twowayEventHandler === "undefined") {
             return;
@@ -6986,7 +7102,7 @@ async function buildBindings(root) {
     }
 }
 
-var version = "1.23.0";
+var version = "1.25.0";
 var pkg = {
 	version: version};
 
@@ -9854,6 +9970,108 @@ function setSwapInfoByAddress(address, swapInfo) {
     }
 }
 
+/**
+ * topologicalRank.ts — 依存グラフ（パス単位）のトポロジカル順位。
+ *
+ * 依存ウォークは list → list.* を展開するために途中でリスト実体を読む。この読み取りが
+ * 正しい値を返すには「そのパスの入力（先行パス）がすべて dirty 化済み」である必要がある。
+ * DFS ではダイヤモンド依存で片腕しか dirty 化していない段階で合流点を評価してしまうため、
+ * パス単位の rank（= 最長経路長）を先に求め、rank の昇順で訪問する。
+ *
+ * rank の定義から、辺 (u → v) が存在すれば必ず rank(u) < rank(v) となる。したがって
+ * rank r のバケットを処理する時点で rank < r のパスはすべて訪問（dirty 化）済みであり、
+ * 同じバケット内のパス同士は互いに先行関係を持たない。
+ *
+ * 値を読まないグラフ走査なので、ウォーク 1 回あたりの追加コストは実測で誤差に
+ * 収まる（メモ化しても差が出なかったため、キャッシュは持たない）。
+ */
+function getTopologicalRanks(startPath, staticMap, dynamicMap, maxDepth) {
+    // 1) startPath から到達可能なパス部分グラフと入次数を求める（値は一切読まない）
+    const adjacency = new Map();
+    const inDegree = new Map();
+    const pending = [startPath];
+    inDegree.set(startPath, 0);
+    while (pending.length > 0) {
+        const path = pending.pop();
+        if (adjacency.has(path)) {
+            continue;
+        }
+        const staticDeps = staticMap.get(path);
+        const dynamicDeps = dynamicMap.get(path);
+        let deps;
+        if (staticDeps === undefined) {
+            deps = dynamicDeps ?? [];
+        }
+        else if (dynamicDeps === undefined) {
+            deps = staticDeps;
+        }
+        else {
+            deps = staticDeps.concat(dynamicDeps);
+        }
+        adjacency.set(path, deps);
+        for (let i = 0; i < deps.length; i++) {
+            const dep = deps[i];
+            inDegree.set(dep, (inDegree.get(dep) ?? 0) + 1);
+            if (!adjacency.has(dep)) {
+                pending.push(dep);
+            }
+        }
+    }
+    // 2) Kahn 法。rank は最長経路長（rank[v] = max(rank[u]) + 1）。
+    //    入次数が 0 に落ちて queue に入ったパスだけが「確定」で、緩和の途中で
+    //    暫定値が入っただけのパス（= 循環の一部）は確定扱いにしない。
+    const ranks = new Map();
+    const settled = new Set();
+    const queue = [];
+    for (const [path, degree] of inDegree) {
+        if (degree === 0) {
+            ranks.set(path, 0);
+            settled.add(path);
+            queue.push(path);
+        }
+    }
+    for (let i = 0; i < queue.length; i++) {
+        const path = queue[i];
+        const nextRank = ranks.get(path) + 1;
+        if (nextRank > maxDepth) {
+            raiseError(`Maximum dependency depth of ${maxDepth} exceeded. Possible circular dependency detected at path: ${path}`);
+        }
+        const deps = adjacency.get(path);
+        for (let j = 0; j < deps.length; j++) {
+            const dep = deps[j];
+            if (nextRank > (ranks.get(dep) ?? -1)) {
+                ranks.set(dep, nextRank);
+            }
+            const remaining = inDegree.get(dep) - 1;
+            inDegree.set(dep, remaining);
+            if (remaining === 0) {
+                settled.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    // 3) 循環に含まれるパスは rank が決まらない（入次数が 0 に落ちない）。
+    //    そもそも正しい評価順が存在しないので、順序保証を諦めて確定済みの
+    //    最大 rank の次にまとめる。打ち切りは従来どおり visited が担う。
+    //    暫定値が残っていると確定パスとの前後関係を誤って表すため、必ず上書きする。
+    if (settled.size !== adjacency.size) {
+        let maxRank = -1;
+        for (const path of settled) {
+            const rank = ranks.get(path);
+            if (rank > maxRank) {
+                maxRank = rank;
+            }
+        }
+        const cycleRank = maxRank + 1;
+        for (const path of adjacency.keys()) {
+            if (!settled.has(path)) {
+                ranks.set(path, cycleRank);
+            }
+        }
+    }
+    return ranks;
+}
+
 const MAX_DEPENDENCY_DEPTH = 1000;
 function getIndexes(listDiff, searchType) {
     switch (searchType) {
@@ -9960,152 +10178,178 @@ function getMovedRowExpansionPaths(context, wildcardPath, depPathInfo) {
     return result ?? EMPTY_PATH_INFOS;
 }
 function _walkDependency(context, startAddress, callback) {
-    const stack = [{ address: startAddress, depth: 0 }];
-    while (stack.length > 0) {
-        const { address, depth } = stack.pop();
-        if (depth > MAX_DEPENDENCY_DEPTH) {
-            raiseError(`Maximum dependency depth of ${MAX_DEPENDENCY_DEPTH} exceeded. Possible circular dependency detected at path: ${address.pathInfo.path}`);
-        }
-        if (context.visited.has(address)) {
+    // rank ごとのバケットで訪問する。辺 (u → v) では必ず rank(u) < rank(v) なので、
+    // バケット r を処理する時点で rank < r のパスは全て dirty 化済みになる
+    // ＝ ここでリスト実体を読んでも入力が揃っている（topologicalRank.ts 参照）。
+    const buckets = [];
+    const ranks = context.ranks;
+    const enqueue = (address, minRank) => {
+        let rank = ranks.get(address.pathInfo.path) ?? minRank;
+        if (rank < minRank) {
+            // 循環など rank が先行関係を表せないケース。現在のバケットに載せて
+            // 同一ループ内で処理する（打ち切りは visited が担う）。
+            rank = minRank;
+        }
+        (buckets[rank] ??= []).push(address);
+    };
+    enqueue(startAddress, 0);
+    // 依存アドレスを収集するための一時バッファ（アドレスごとに使い回す）
+    const nextEntries = [];
+    for (let rank = 0; rank < buckets.length; rank++) {
+        const bucket = buckets[rank];
+        if (bucket === undefined) {
             continue;
         }
-        context.visited.add(address);
-        callback(address);
-        const sourcePath = address.pathInfo.path;
-        const nextDepth = depth + 1;
-        // 依存アドレスを逆順でpushするための一時バッファ
-        const nextEntries = [];
-        /**
-         * パスから依存関係をたどる
-         * users.*.name <= users.* <= users
-         * ただし、users がリストであれば users.* の依存関係は展開する
-         */
-        const staticDeps = context.staticMap.get(sourcePath);
-        if (staticDeps) {
-            for (const dep of staticDeps) {
-                const depPathInfo = getPathInfo(dep);
-                if (context.listPathSet.has(sourcePath) && depPathInfo.lastSegment === WILDCARD) {
-                    //expand indexes
-                    const newValue = context.stateProxy[getByAddressSymbol](address);
-                    const absPathInfo = getAbsolutePathInfo(context.stateElement, address.pathInfo);
-                    const absAddress = createAbsoluteStateAddress(absPathInfo, address.listIndex);
-                    const lastValue = getLastListValueByAbsoluteStateAddress(absAddress);
-                    const listDiff = createListDiff(address.listIndex, lastValue, newValue);
-                    const selection = selectExpansionIndexes(context, sourcePath, lastValue, newValue, listDiff);
-                    for (const listIndex of selection.fullRows) {
-                        const depAddress = createStateAddress(depPathInfo, listIndex);
-                        context.result.add(depAddress);
-                        nextEntries.push({ address: depAddress, depth: nextDepth });
+        // 同一バケットへの push（循環時）で伸びるため length は都度読む
+        for (let cursor = 0; cursor < bucket.length; cursor++) {
+            const address = bucket[cursor];
+            if (context.visited.has(address)) {
+                continue;
+            }
+            context.visited.add(address);
+            callback(address);
+            nextEntries.length = 0;
+            _collectDependencies(context, address, nextEntries);
+            for (let i = 0; i < nextEntries.length; i++) {
+                enqueue(nextEntries[i], rank + 1);
+            }
+        }
+    }
+}
+/**
+ * address の依存アドレスを nextEntries に集め、context.result にも登録する。
+ * リスト展開（list → list.*）と動的依存のワイルドカード展開はここで値を読むが、
+ * 呼び出し元がトポロジカル順を保証しているため入力は揃っている。
+ */
+function _collectDependencies(context, address, nextEntries) {
+    const sourcePath = address.pathInfo.path;
+    /**
+     * パスから依存関係をたどる
+     * users.*.name <= users.* <= users
+     * ただし、users がリストであれば users.* の依存関係は展開する
+     */
+    const staticDeps = context.staticMap.get(sourcePath);
+    if (staticDeps) {
+        for (const dep of staticDeps) {
+            const depPathInfo = getPathInfo(dep);
+            if (context.listPathSet.has(sourcePath) && depPathInfo.lastSegment === WILDCARD) {
+                //expand indexes
+                const newValue = context.stateProxy[getByAddressSymbol](address);
+                const absPathInfo = getAbsolutePathInfo(context.stateElement, address.pathInfo);
+                const absAddress = createAbsoluteStateAddress(absPathInfo, address.listIndex);
+                const lastValue = getLastListValueByAbsoluteStateAddress(absAddress);
+                const listDiff = createListDiff(address.listIndex, lastValue, newValue);
+                const selection = selectExpansionIndexes(context, sourcePath, lastValue, newValue, listDiff);
+                for (const listIndex of selection.fullRows) {
+                    const depAddress = createStateAddress(depPathInfo, listIndex);
+                    context.result.add(depAddress);
+                    nextEntries.push(depAddress);
+                }
+                if (selection.movedRows !== null) {
+                    const movedPathInfos = getMovedRowExpansionPaths(context, dep, depPathInfo);
+                    if (movedPathInfos === null) {
+                        // ネスト配下に index 依存 getter: 安全側で行全体を展開（従来挙動）
+                        for (const listIndex of selection.movedRows) {
+                            const depAddress = createStateAddress(depPathInfo, listIndex);
+                            context.result.add(depAddress);
+                            nextEntries.push(depAddress);
+                        }
                     }
-                    if (selection.movedRows !== null) {
-                        const movedPathInfos = getMovedRowExpansionPaths(context, dep, depPathInfo);
-                        if (movedPathInfos === null) {
-                            // ネスト配下に index 依存 getter: 安全側で行全体を展開（従来挙動）
-                            for (const listIndex of selection.movedRows) {
-                                const depAddress = createStateAddress(depPathInfo, listIndex);
+                    else if (movedPathInfos.length > 0) {
+                        // 位置のみ変わった行は index 依存 getter のパスだけを展開する
+                        for (const listIndex of selection.movedRows) {
+                            for (const pathInfo of movedPathInfos) {
+                                const depAddress = createStateAddress(pathInfo, listIndex);
                                 context.result.add(depAddress);
-                                nextEntries.push({ address: depAddress, depth: nextDepth });
-                            }
-                        }
-                        else if (movedPathInfos.length > 0) {
-                            // 位置のみ変わった行は index 依存 getter のパスだけを展開する
-                            for (const listIndex of selection.movedRows) {
-                                for (const pathInfo of movedPathInfos) {
-                                    const depAddress = createStateAddress(pathInfo, listIndex);
-                                    context.result.add(depAddress);
-                                    nextEntries.push({ address: depAddress, depth: nextDepth });
-                                }
+                                nextEntries.push(depAddress);
                             }
                         }
-                        // movedPathInfos が空: index を読む getter が subtree に無い =
-                        // 位置のみ変わった行の値は不変。展開・dirty 化とも不要。
                     }
-                }
-                else {
-                    const depAddress = createStateAddress(depPathInfo, address.listIndex);
-                    context.result.add(depAddress);
-                    nextEntries.push({ address: depAddress, depth: nextDepth });
+                    // movedPathInfos が空: index を読む getter が subtree に無い =
+                    // 位置のみ変わった行の値は不変。展開・dirty 化とも不要。
                 }
             }
+            else {
+                const depAddress = createStateAddress(depPathInfo, address.listIndex);
+                context.result.add(depAddress);
+                nextEntries.push(depAddress);
+            }
         }
-        /**
-         * 動的依存関係をたどる
-         * 動的依存関係は、getterの実行時に決定される
-         *
-         * source,           target
-         *
-         * products.*.price => products.*.tax
-         * get "products.*.tax"() { return this["products.*.price"] * 0.1; }
-         *
-         * products.*.price => products.summary
-         * get "products.summary"() { return this.$getAll("products.*.price", []).reduce(sum); }
-         *
-         * categories.*.name => categories.*.products.*.categoryName
-         * get "categories.*.products.*.categoryName"() { return this["categories.*.name"]; }
-         */
-        const dynamicDeps = context.dynamicMap.get(sourcePath);
-        if (dynamicDeps) {
-            for (const dep of dynamicDeps) {
-                const depPathInfo = getPathInfo(dep);
-                const listIndexes = [];
-                if (depPathInfo.wildcardCount > 0) {
-                    // ワイルドカードを含む依存関係の処理
-                    // 同じ親を持つかをパスの集合積で判定する
-                    // polyfills.tsにてSetのintersectionメソッドを定義している
-                    const wildcardLen = calcWildcardLen(address.pathInfo, depPathInfo);
-                    const expandable = (depPathInfo.wildcardCount - wildcardLen) >= 1;
-                    if (expandable) {
-                        let listIndex;
-                        if (wildcardLen > 0) {
-                            // categories.*.name => categories.*.products.*.categoryName
-                            // ワイルドカードを含む同じ親（products.*）を持つのが、
-                            // さらに下位にワイルドカードがあるので展開する
-                            if (address.listIndex === null) {
-                                raiseError(`Cannot expand dynamic dependency with wildcard for non-list address: ${address.pathInfo.path}`);
-                            }
-                            listIndex = address.listIndex.at(wildcardLen - 1);
-                        }
-                        else {
-                            // selectedIndex => items.*.selected
-                            // 同じ親を持たない場合はnullから開始
-                            listIndex = null;
-                        }
-                        const expandContext = {
-                            stateElement: context.stateElement,
-                            targetListIndexes: [],
-                            wildcardPaths: depPathInfo.wildcardPaths,
-                            wildcardParentPaths: depPathInfo.wildcardParentPaths,
-                            stateProxy: context.stateProxy,
-                            searchType: context.searchType,
-                        };
-                        _walkExpandWildcard(expandContext, wildcardLen, listIndex);
-                        listIndexes.push(...expandContext.targetListIndexes);
-                    }
-                    else {
-                        // products.*.price => products.*.tax
-                        // ワイルドカードを含む同じ親（products.*）を持つので、リストインデックスは引き継ぐ
+    }
+    /**
+     * 動的依存関係をたどる
+     * 動的依存関係は、getterの実行時に決定される
+     *
+     * source,           target
+     *
+     * products.*.price => products.*.tax
+     * get "products.*.tax"() { return this["products.*.price"] * 0.1; }
+     *
+     * products.*.price => products.summary
+     * get "products.summary"() { return this.$getAll("products.*.price", []).reduce(sum); }
+     *
+     * categories.*.name => categories.*.products.*.categoryName
+     * get "categories.*.products.*.categoryName"() { return this["categories.*.name"]; }
+     */
+    const dynamicDeps = context.dynamicMap.get(sourcePath);
+    if (dynamicDeps) {
+        for (const dep of dynamicDeps) {
+            const depPathInfo = getPathInfo(dep);
+            const listIndexes = [];
+            if (depPathInfo.wildcardCount > 0) {
+                // ワイルドカードを含む依存関係の処理
+                // 同じ親を持つかをパスの集合積で判定する
+                // polyfills.tsにてSetのintersectionメソッドを定義している
+                const wildcardLen = calcWildcardLen(address.pathInfo, depPathInfo);
+                const expandable = (depPathInfo.wildcardCount - wildcardLen) >= 1;
+                if (expandable) {
+                    let listIndex;
+                    if (wildcardLen > 0) {
+                        // categories.*.name => categories.*.products.*.categoryName
+                        // ワイルドカードを含む同じ親（products.*）を持つのが、
+                        // さらに下位にワイルドカードがあるので展開する
                         if (address.listIndex === null) {
                             raiseError(`Cannot expand dynamic dependency with wildcard for non-list address: ${address.pathInfo.path}`);
                         }
-                        const listIndex = address.listIndex.at(wildcardLen - 1);
-                        listIndexes.push(listIndex);
+                        listIndex = address.listIndex.at(wildcardLen - 1);
                     }
+                    else {
+                        // selectedIndex => items.*.selected
+                        // 同じ親を持たない場合はnullから開始
+                        listIndex = null;
+                    }
+                    const expandContext = {
+                        stateName: context.stateName,
+                        stateElement: context.stateElement,
+                        targetListIndexes: [],
+                        wildcardPaths: depPathInfo.wildcardPaths,
+                        wildcardParentPaths: depPathInfo.wildcardParentPaths,
+                        stateProxy: context.stateProxy,
+                        searchType: context.searchType,
+                    };
+                    _walkExpandWildcard(expandContext, wildcardLen, listIndex);
+                    listIndexes.push(...expandContext.targetListIndexes);
                 }
                 else {
-                    // products.*.tax => currentTaxRate
-                    // 同じ親を持たないので、リストインデックスはnull
-                    listIndexes.push(null);
-                }
-                for (const listIndex of listIndexes) {
-                    const depAddress = createStateAddress(depPathInfo, listIndex);
-                    context.result.add(depAddress);
-                    nextEntries.push({ address: depAddress, depth: nextDepth });
+                    // products.*.price => products.*.tax
+                    // ワイルドカードを含む同じ親（products.*）を持つので、リストインデックスは引き継ぐ
+                    if (address.listIndex === null) {
+                        raiseError(`Cannot expand dynamic dependency with wildcard for non-list address: ${address.pathInfo.path}`);
+                    }
+                    const listIndex = address.listIndex.at(wildcardLen - 1);
+                    listIndexes.push(listIndex);
                 }
             }
-        }
-        // 逆順でpushして、元の再帰と同じ探索順序を保つ
-        for (let i = nextEntries.length - 1; i >= 0; i--) {
-            stack.push(nextEntries[i]);
+            else {
+                // products.*.tax => currentTaxRate
+                // 同じ親を持たないので、リストインデックスはnull
+                listIndexes.push(null);
+            }
+            for (const listIndex of listIndexes) {
+                const depAddress = createStateAddress(depPathInfo, listIndex);
+                context.result.add(depAddress);
+                nextEntries.push(depAddress);
+            }
         }
     }
 }
@@ -10119,7 +10363,12 @@ function walkDependency(stateName, stateElement, startAddress, staticDependency,
         callback(startAddress);
         return [];
     }
+    // パス単位のトポロジカル順位。値を一切読まずに求まり、依存グラフは追記のみで
+    // 成長するため epoch でメモ化される（topologicalRank.ts）。
+    const ranks = getTopologicalRanks(startPath, staticDependency, dynamicDependency, MAX_DEPENDENCY_DEPTH);
     const context = {
+        ranks: ranks,
+        stateName: stateName,
         stateElement: stateElement,
         staticMap: staticDependency,
         dynamicMap: dynamicDependency,
@@ -10258,6 +10507,10 @@ function _setByAddressWithSwap(target, address, absAddress, value, receiver, han
 function setByAddress(target, address, value, receiver, handler) {
     const stateElement = handler.stateElement;
     const path = address.pathInfo.path;
+    // occurrence（wc-bindable の `semantics: "event"`）由来の書き込みは、同値でも
+    // 「もう一度起きた」ことを落としてはならないため same-value guard を 1 回だけ飛ばす。
+    // トークンはここで消費されるので、この write の内側で走る他の書き込みには波及しない。
+    const skipSameValueGuard = consumeOccurrenceWrite();
     // --- fast path: 宣言済み getter/setter でも swap 対象でもない、親を持つ葉パス ---
     // 従来は same-value guard の値読み・hasByAddress・実書き込みがそれぞれ親チェーンを
     // 解決していた（キャッシュヒットでも getByAddress 呼び出しの固定費 ×3）。
@@ -10274,7 +10527,7 @@ function setByAddress(target, address, value, receiver, handler) {
                 : lastSegment;
             let devOldValue;
             let devHasOldValue = false;
-            if (config.sameValueGuard && (value === null || typeof value !== "object")) {
+            if (!skipSameValueGuard && config.sameValueGuard && (value === null || typeof value !== "object")) {
                 // hasByAddress と同じ「初期化済みスロットか」判定（undefined 格納と未初期化を区別）
                 const has = key !== undefined && key in parentValue;
                 const oldValue = key !== undefined ? parentValue[key] : undefined;
@@ -10334,7 +10587,7 @@ function setByAddress(target, address, value, receiver, handler) {
     // （参照型のために追加の get はしない — protocol §4.2）
     let devOldValue;
     let devHasOldValue = false;
-    if (config.sameValueGuard && (value === null || typeof value !== "object")) {
+    if (!skipSameValueGuard && config.sameValueGuard && (value === null || typeof value !== "object")) {
         const oldValue = getByAddress(target, address, receiver, handler);
         if (hasByAddress(target, address, receiver, handler) && Object.is(oldValue, value)) {
             return true;
@@ -10716,7 +10969,7 @@ function updatedCallback(target, refs, receiver, handler) {
  * setLoopContext.ts
  *
  * StateClassの内部APIとして、ループコンテキスト（ILoopContext）を一時的に設定し、
- * 指定した同期/非同期コールバックをそのスコープ内で実行するための関数です。
+ * 指定したコールバックをそのスコープ内で実行するための関数です。
  *
  * 主な役割:
  * - handler.loopContextにループコンテキストを一時的に設定
@@ -10727,9 +10980,26 @@ function updatedCallback(target, refs, receiver, handler) {
  * 設計ポイント:
  * - ループバインディングや多重ループ時のスコープ管理を安全に行う
  * - finallyで状態復元を保証し、例外発生時も安全
- * - 非同期処理にも対応
+ *
+ * **スコープは同期である（重要）**:
+ * push/pop は `callback()` の同期リターンで完結する。callback が Promise を返した
+ * 場合、finally はその Promise が settle する *前* に走るため、await を跨いだ先では
+ * ループコンテキストは既に外れている。したがって async なハンドラが await の後に
+ * `$1` や wildcard パス（`items.*.id`）を触ると raiseError になる。
+ *
+ * これは silent な取り違えではなく loud な失敗であり、意図した挙動である
+ * （特性化テスト: `__tests__/poc.asyncOnLoopContext.test.ts`）。await の後に行位置が
+ * 必要な場合は、ハンドラ引数で受け取った listIndexes を
+ * `$resolve(path, indexes, value?)` に渡すこと。listIndexes は素の数値配列なので
+ * await を跨いでも安全に持ち回せる。
+ *
+ * 補足: かつて `setLoopContextAsync` という変種が存在したが、実体は
+ * `await _setLoopContext(...)`（= finally が既に走った後の Promise を await するだけ）
+ * であり、名前が示唆する「コンテキストを await 跨ぎで保持する」挙動は持っていなかった。
+ * production の呼び出し元も無かったため削除した。同等の機能が必要になった場合は、
+ * 「名前どおりに動く」実装を新規に起こすこと。
  */
-function _setLoopContext(handler, loopContext, callback) {
+function setLoopContext(handler, loopContext, callback) {
     if (typeof handler.loopContext !== "undefined") {
         raiseError('already in loop context');
     }
@@ -10747,12 +11017,6 @@ function _setLoopContext(handler, loopContext, callback) {
         handler.clearLoopContext();
     }
 }
-function setLoopContext(handler, loopContext, callback) {
-    return _setLoopContext(handler, loopContext, callback);
-}
-async function setLoopContextAsync(handler, loopContext, callback) {
-    return await _setLoopContext(handler, loopContext, callback);
-}
 
 /**
  * get.ts
@@ -10870,12 +11134,6 @@ function get(target, prop, receiver, handler) {
         }
         let api;
         switch (prop) {
-            case setLoopContextAsyncSymbol: {
-                api = (loopContext, callback = async () => { }) => {
-                    return setLoopContextAsync(handler, loopContext, callback);
-                };
-                break;
-            }
             case setLoopContextSymbol: {
                 api = (loopContext, callback = () => { }) => {
                     return setLoopContext(handler, loopContext, callback);