@wcstack/devtools 1.29.0 → 1.31.0

package/dist/index.d.ts

@@ -65,6 +65,14 @@ interface IStateElementSummaryLike {
      * 旧ランタイムにはフィールド自体が無いため optional。宣言なしは null。
      */
     readonly watchPaths?: ReadonlySet<string> | null;
+    /**
+     * `$listKeys` で宣言されたリストパス集合（protocol v1 追補）。ワイルドカード行
+     * watch に**リスト書き込み**が届く前提は「for バインド（paths.list）or
+     * $listKeys 宣言」なので、前提判定の正確化に paths.list と対で使う
+     *（明示 index 書き込みは前提に依らず発火し得る）。旧ランタイムにはフィールド自体が
+     * 無いため optional（undefined = $listKeys 側が観測不能）。宣言なしは null。
+     */
+    readonly keyedListPaths?: ReadonlySet<string> | null;
 }
 /**
  * 宣言レベルのバインディング 1 件（getDeclaredBindings の要素・protocol v1 追補）。
@@ -140,6 +148,18 @@ type DevtoolsEventLike = {
     readonly type: "state:watch-fired";
     readonly stateName: string;
     readonly path: string;
+} | {
+    readonly type: "state:path-unresolved";
+    readonly source: "binding" | "watch";
+    readonly stateName: string;
+    readonly path: string;
+    readonly missingSegment: string;
+} | {
+    readonly type: "state:binding-apply-error";
+    readonly stateName: string;
+    readonly path: string;
+    readonly bindingType: string;
+    readonly error: unknown;
 } | {
     readonly type: "propagation:suppressed";
     readonly reason: "confirmation" | "visited-edge";
@@ -219,7 +239,7 @@ interface IDevtoolsHookRegistryLike {
 
 /** 予約 state 名 prefix（protocol §5）。この prefix の要素・イベントは常に除外 */
 declare const RESERVED_STATE_NAME_PREFIX = "wcs-devtools";
-type TimelineKind = "write" | "batch" | "command" | "event" | "element-registered" | "element-unregistered" | "watch-error" | "watch-chain-limit" | "propagation-suppressed" | "propagation-coalesced" | "propagation-hop-limit" | "contract-drift";
+type TimelineKind = "write" | "batch" | "command" | "event" | "element-registered" | "element-unregistered" | "watch-error" | "watch-chain-limit" | "path-unresolved" | "binding-apply-error" | "propagation-suppressed" | "propagation-coalesced" | "propagation-hop-limit" | "contract-drift";
 interface ITimelineEntry {
     readonly seq: number;
     readonly time: number;
@@ -249,8 +269,8 @@ type CoreChangeListener = (kind: CoreChangeKind) => void;
 /**
  * 配線カバレッジ 1 行（static-wiring-dx-design.md §4 — 宣言 × 実測の突合）。
  * - watch: `fired`（count 回）/ `never` / `prerequisite-missing`
- *   （ワイルドカード行 watch はリストが `for` バインドされていないと発火前提が
- *   成立しない — 「未発火」と区別しないと誤警告になる）
+ *   （ワイルドカード行 watch は「for バインド or $listKeys 宣言」が無いと
+ *   リスト書き込みが行へ届かない — 「未発火」と区別しないと誤警告になる）
  * - command / eventToken: `emitted`（count 回）/ `never` /
  *   `emitted-unheard`（全 emit が subscriberCount 0 = 空撃ち。§4 の突合対象）
  * - binding: canonical declared がある場合のみ。`attached` / `never-attached`

package/dist/index.esm.js

@@ -452,14 +452,21 @@ class DevtoolsCore {
                     out.push({ stateName: entry.name, kind: "watch", name: path, status: "fired", count, note: null });
                     continue;
                 }
-                // ワイルドカード行 watch は各 `.*` 階層のリストが `for` バインドされている
-                // （= paths.list に載っている）ことが発火前提（watch 設計 §6-3）。未成立は
-                // 「未発火」と区別する。ただし paths.list は for 由来のみで `$listKeys`
-                // 宣言はここから見えないため、断定でなく「for が観測できない」と報告する。
+                // ワイルドカード行 watch に**リスト書き込み**が届く前提 = 各 `.*` 階層の
+                // リストが「for バインド（paths.list）or `$listKeys` 宣言（keyedListPaths）」
+                // されていること（watch 設計 §6-3）。未成立は「未発火」と区別する。
+                // 前提はリスト置換経路に限る主張 — 明示 index 書き込み（`$resolve` /
+                // `items.0.price` 代入。$getAll で listIndex 台帳が生えた後）は前提に
+                // 依らず発火し得るため、「一度も発火しない」とは断定できない（実測済み）。
+                // keyedListPaths は protocol v1 追補 — フィールドを持たない旧ランタイム
+                // では $listKeys 側が観測できないため、note はさらに観測形に落とす 2 段。
+                const keyedKnown = summary.keyedListPaths !== undefined;
                 let missingList = null;
                 for (let star = path.indexOf(".*"); star !== -1; star = path.indexOf(".*", star + 2)) {
                     const listPath = path.slice(0, star);
-                    if (!summary.paths.list.has(listPath)) {
+                    const satisfied = summary.paths.list.has(listPath)
+                        || (summary.keyedListPaths?.has(listPath) ?? false);
+                    if (!satisfied) {
                         missingList = listPath;
                         break;
                     }
@@ -467,7 +474,9 @@ class DevtoolsCore {
                 if (missingList !== null) {
                     out.push({
                         stateName: entry.name, kind: "watch", name: path, status: "prerequisite-missing", count: 0,
-                        note: `no for binding observed for list "${missingList}" (a $listKeys declaration would still let it fire)`,
+                        note: keyedKnown
+                            ? `list "${missingList}" has no for binding and no $listKeys declaration — list writes never reach its rows (only explicit-index writes can fire this watch)`
+                            : `no for binding observed for list "${missingList}" (a $listKeys declaration would still let list writes fire it)`,
                     });
                     continue;
                 }
@@ -799,6 +808,38 @@ class DevtoolsCore {
                 });
                 return;
             }
+            case "state:path-unresolved": {
+                if (this.isHiddenStateName(event.stateName)) {
+                    return;
+                }
+                // ランタイムは warn で続行する（既存ページを止めないため）。lint を
+                // 走らせていない相手には、ここが「配線が死んでいる」唯一の可視面になる。
+                this._appendTimeline({
+                    sourceId,
+                    kind: "path-unresolved",
+                    stateName: event.stateName,
+                    label: event.path,
+                    detail: `${event.source}: "${event.missingSegment}" is not declared`,
+                    subscriberCount: null,
+                });
+                return;
+            }
+            case "state:binding-apply-error": {
+                if (this.isHiddenStateName(event.stateName)) {
+                    return;
+                }
+                // 隔離された適用失敗。bindingType を detail 先頭に置くのは、構造
+                // （for / if）の失敗と値の失敗で影響範囲が違うため。
+                this._appendTimeline({
+                    sourceId,
+                    kind: "binding-apply-error",
+                    stateName: event.stateName,
+                    label: event.path,
+                    detail: `${event.bindingType}: ${formatError(event.error)}`,
+                    subscriberCount: null,
+                });
+                return;
+            }
             case "propagation:suppressed": {
                 // two-way エコーの辺単位抑止。state 名を持たない（node+member が主語）
                 // ため hidden 判定はここでは行わない。
@@ -1811,6 +1852,14 @@ class WcsDevtools extends HTMLElement {
                 ? "a $watch threw; the runtime isolated it (console.error only)"
                 : "a $watch write chain hit the depth limit and was cut off";
         }
+        // 配線の死（解決しないパス）と隔離された適用失敗も、ランタイムが console に
+        // 出すだけで続行する ＝ 見ていなければ気づけない種類なので warn に乗せる。
+        if (entry.kind === "path-unresolved" || entry.kind === "binding-apply-error") {
+            kind.classList.add("warn");
+            kind.title = entry.kind === "path-unresolved"
+                ? "a wired path does not resolve on the state; its updates are dropped"
+                : "a binding threw while applying; the runtime isolated it (console.error only)";
+        }
         // 伝播の打ち切りと契約 drift も「黙って起きる異常」なので warn に乗せる。
         // suppressed / coalesced は定常動作（エコー抑止・合流）のため通常表示。
         if (entry.kind === "propagation-hop-limit" || entry.kind === "contract-drift") {