@wcstack/state 1.21.7 → 1.22.0

package/README.ja.md

@@ -344,7 +344,7 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 
 ### バインディング authority (`#init=` / `#sync=`)
 
-`static wcBindable` を宣言したカスタム要素への prop バインディングは、**authority**（そのワイヤをどちら側が所有するか）を解決します。authority は初期値の出所だけでなく、**そのバインディングの生存期間全体で state→element 書き込みが有効かどうか**を決めます。既定はメンバの宣言位置から導出されます（`enableDirectionalInitialSync` で既定 ON）：
+`static wcBindable` を宣言したカスタム要素への prop バインディングは、**authority**（バインディング attach 時の**初期同期**をどちら側が勝つか）を解決します。定常時の方向は authority とは別に、メンバの宣言形状で決まります: output-only メンバは state からの書き込みを恒久的に受け付けず（契約）、双方向メンバは初期同期の勝者と無関係に以後は両方向に流れます。既定 authority はメンバの宣言位置から導出されます（`enableDirectionalInitialSync` で既定 ON）：
 
 | メンバの宣言位置 | 既定 authority | 効果 |
 |---|---|---|
@@ -357,12 +357,19 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 
 authority はバインディング単位で `#init=` により上書きできます：
 
-| 値 | authority | 使える宣言 |
+| 値 | 初期同期 | 使える宣言 |
 |---|---|---|
-| `init=state` | state 所有：state → element（双方向メンバは要素イベントも引き続き受信） | inputs のみ・双方向 |
-| `init=element` | element 所有：要素のスナップショットとイベント → state。state からの書き込みは抑止 | output-only・双方向 |
+| `init=state` | state の値を要素へ書く（双方向の既定） | inputs のみ・双方向 |
+| `init=element` | 要素のスナップショットを state へ入れる — 双方向メンバではその後は通常の双方向に戻る（次の変更から state→element も流れる） | output-only・双方向 |
 | `init=auto` | state スロットが未初期化なら `element`、それ以外は `state` | 双方向 |
-| `init=none` | 初期同期なし（event バインディングはこの値のみ許可） | すべて |
+| `init=none` | 初期同期なし — 次の変更から通常どおり流れる（event バインディングはこの値のみ許可） | すべて |
+
+`#init=` が決めるのは初期競合の勝者だけです。state→element 書き込みの**恒久**抑止は「メンバが output-only 宣言であること」から来るのであって、修飾子からは来ません。これにより `#init=element`（または `#init=auto`）が **load-before-bind** の宣言的な解になります: 要素が自身の `connectedCallback` で永続値をロード済み（バインディング確立より先）でも state 初期値に潰されず、以後の state 変更は要素へ届きます（例えば `<wcs-storage>` の保存は生き続けます）：
+
+```html
+<!-- 永続化済みリストが todos を初期化し、以後の todos 代入は保存もされる -->
+<wcs-storage key="todos" type="local" data-wcs="value#init=element: todos"></wcs-storage>
+```
 
 `#sync=` は element authority のバインディングで要素スナップショットを**いつ**読むかを制御します：
 
@@ -377,10 +384,13 @@ authority はバインディング単位で `#init=` により上書きできま
 <x-widget data-wcs="value#init=element,sync=connect: widget.snapshot"></x-widget>
 ```
 
+`sync=connect` では、接続時スナップショットが初期競合を解決するまで state→element 書き込みも保留されます。
+
 注意：
 
 - `enableDirectionalInitialSync: false`（opt-out）のとき `#init=`/`#sync=` を書くと throw します。
 - **1.20 以前からの移行：** output-only メンバに対して state 側に都合のよい初期値（`value: []`、`query: ""` 等）をシードしないでください — 要素側の実初期値（多くは `null`/`undefined`）がシードを置き換えます。シードは要素の実初期値に合わせ、表示用の値は派生 getter で null ガードしてください。
+- **1.21.x まで**、`init=element` / `init=auto` / `init=none` はバインディングの生存期間全体で state→element 書き込みを抑止しており、真に双方向なメンバには使えませんでした。現在は authority は初期同期のみを支配します（`docs/architecture-hardening/09-remediation-design.md` §3.6）。
 
 ### ラジオボタンバインディング
 
@@ -1485,9 +1495,32 @@ stream の値は普通のプロパティで、コンパニオンの status / err
 
 error 時、プロパティは直前の fold 結果を保持し、エラーは `$streamError.<name>` に入ります。`done` / `error` の stream も依存の変化で restart します（再試行 = 依存の叩き直し）。
 
+**イベント API の橋渡し** —— 実際の source の多くはコールバック型（`EventSource`・`WebSocket`・DOM イベント）で、async iterable ではありません。標準の `ReadableStream` で包んでください: `start` で enqueue し、`cancel` でリソースを解放します。`AbortSignal` には一切触れません —— restart / 破棄時は runtime が reader を cancel し、parked read を強制解放して `cancel()` まで届けます：
+
+```js
+$streams: {
+  metrics: {
+    args: (state) => ({ host: state.host }),
+    source: ({ host }) => {
+      const es = new EventSource(`/api/metrics?host=${host}`);
+      return new ReadableStream({
+        start(controller) {
+          es.addEventListener("metric", (e) => controller.enqueue(JSON.parse(e.data)));
+        },
+        cancel() { es.close(); },   // restart / 破棄時に走る
+      });
+    },
+    fold: (acc, sample) => [...acc, sample].slice(-20),
+    initial: [],
+  },
+},
+```
+
+手書きの async generator も producer 側の制御が要るときは引き続き完全サポートですが、abort 救済は*部分的*です: `signal` を無視して `await` で park した generator は外から強制解放できません。イベント API の橋渡しには `ReadableStream` 形を推奨します。
+
 重要な規範：
 
-- **協調キャンセル（MUST）** —— `source` は渡された `AbortSignal` を必ず監視し、発火したら生産を停止すること。
+- **協調キャンセル（MUST）** —— `source` は渡された `AbortSignal` を必ず監視し、発火したら生産を停止すること。`ReadableStream` の source はこの契約を `cancel()` コールバック経由で自動的に満たします（abort 時に runtime が reader を cancel します）。自前の async iterable だけが `signal` を自分で監視する必要があります。
 - **有界 fold** —— 需要は producer に逆流しません（backpressure は明示的に放棄）。無限 / 長寿命ストリームでは latest・count・last-N（`(acc, chunk) => [...acc.slice(-99), chunk]`）・ウィンドウ集計など有界な fold を使うこと。生の全チャンク累積は有限ストリーム限定。
 - **`args` は同期** —— Promise を返すとエラー。`args` 内での wildcard 読みも拒否されます。
 - **自己依存・相互サイクルの禁止** —— `args` が自 stream の値や status を読むとエラーになります。2 つの stream の相互サイクル（A の `args` が B の値を読み、B の `args` が A の値を読む）は検出されず無限 restart になるため組まないこと。一方向のチェイン（A の値を B の `args` が読む）は正当です。

package/README.md

@@ -344,7 +344,7 @@ Automatically enabled for:
 
 ### Binding Authority (`#init=` / `#sync=`)
 
-For custom elements that declare `static wcBindable`, every prop binding resolves an **authority** — which side owns the wire. The authority decides both where the initial value comes from *and* whether state→element writes are enabled, for the binding's whole lifetime. It is derived from where the member is declared (on by default via `enableDirectionalInitialSync`):
+For custom elements that declare `static wcBindable`, every prop binding resolves an **authority** — which side wins the **initial sync** when the binding attaches. The steady-state direction is decided separately, by the member's declared shape: an output-only member never accepts state writes (a permanent contract), while a two-way member flows both ways after the initial sync regardless of which side won it. The default authority is derived from where the member is declared (on by default via `enableDirectionalInitialSync`):
 
 | Member declared in | Default authority | Effect |
 |---|---|---|
@@ -357,12 +357,19 @@ For custom elements that declare `static wcBindable`, every prop binding resolve
 
 Override the authority per binding with `#init=`:
 
-| Value | Authority | Allowed on |
+| Value | Initial sync | Allowed on |
 |---|---|---|
-| `init=state` | State-owned: state → element (two-way members still receive element events) | inputs-only, two-way |
-| `init=element` | Element-owned: element snapshot and events → state; state writes are suppressed | output-only, two-way |
+| `init=state` | The state value is written to the element (two-way default) | inputs-only, two-way |
+| `init=element` | The element's snapshot seeds the state instead — on a two-way member the binding then continues as normal two-way (state→element writes flow from the next change on) | output-only, two-way |
 | `init=auto` | `element` if the state slot is uninitialized, otherwise `state` | two-way |
-| `init=none` | No initial sync (event bindings accept only this value) | any |
+| `init=none` | No initial sync — changes flow normally from the next update (event bindings accept only this value) | any |
+
+`#init=` decides only who wins the initial race. The *permanent* suppression of state→element writes comes from the member being declared output-only, never from the modifier. This makes `#init=element` (or `#init=auto`) the declarative fix for **load-before-bind**: an element that loads a persisted value in its own `connectedCallback` — before the binding attaches — is no longer clobbered by the state seed, and later state changes still reach the element (so e.g. `<wcs-storage>` keeps saving):
+
+```html
+<!-- The persisted list seeds `todos`; assigning `todos` later still saves. -->
+<wcs-storage key="todos" type="local" data-wcs="value#init=element: todos"></wcs-storage>
+```
 
 `#sync=` controls **when** the element snapshot is read for element-authority bindings:
 
@@ -377,10 +384,13 @@ Override the authority per binding with `#init=`:
 <x-widget data-wcs="value#init=element,sync=connect: widget.snapshot"></x-widget>
 ```
 
+With `sync=connect`, state→element writes stay suppressed until the connect snapshot has resolved the initial race.
+
 Notes:
 
 - With `enableDirectionalInitialSync: false` (opt-out), writing `#init=`/`#sync=` throws.
 - **Migrating from ≤ 1.20:** do not seed state with placeholder values (`value: []`, `query: ""`) for output-only members — the element's real initial value (often `null`/`undefined`) replaces the seed. Match the seed to the element's actual initial value and null-guard display values with a derived getter.
+- **Until 1.21.x**, `init=element` / `init=auto` / `init=none` suppressed state→element writes for the binding's whole lifetime, which made them unusable on genuinely two-way members. Authority now governs only the initial sync (`docs/architecture-hardening/09-remediation-design.md` §3.6).
 
 ### Radio Binding
 
@@ -1486,9 +1496,32 @@ The stream's value is an ordinary property, and its companion status / error liv
 
 On error the property keeps its last folded value and the error lands in `$streamError.<name>`; a `done` or `error` stream restarts when its dependencies change (retrying = re-hitting the dependency).
 
+**Bridging an event API** — most real sources are callback-shaped (`EventSource`, `WebSocket`, DOM events), not async iterables. Wrap them in a standard `ReadableStream`: enqueue in `start`, release the resource in `cancel`. You never touch the `AbortSignal` — on restart/dispose the runtime cancels its reader, which force-unwinds a parked read and runs your `cancel()`:
+
+```js
+$streams: {
+  metrics: {
+    args: (state) => ({ host: state.host }),
+    source: ({ host }) => {
+      const es = new EventSource(`/api/metrics?host=${host}`);
+      return new ReadableStream({
+        start(controller) {
+          es.addEventListener("metric", (e) => controller.enqueue(JSON.parse(e.data)));
+        },
+        cancel() { es.close(); },   // runs on restart / dispose
+      });
+    },
+    fold: (acc, sample) => [...acc, sample].slice(-20),
+    initial: [],
+  },
+},
+```
+
+Hand-rolled async generators remain fully supported when you need producer-side control, but they are only *partially* rescued on abort: a generator parked in an `await` that ignores `signal` cannot be force-unwound from outside. Prefer the `ReadableStream` form for event-API bridging.
+
 Key rules:
 
-- **Cooperative cancellation (MUST)** — `source` must observe the passed `AbortSignal` and stop producing when it fires.
+- **Cooperative cancellation (MUST)** — `source` must observe the passed `AbortSignal` and stop producing when it fires. A `ReadableStream` source satisfies this automatically through its `cancel()` callback (the runtime cancels the reader on abort); only hand-rolled async iterables need to observe `signal` themselves.
 - **Bounded fold** — demand never flows back to the producer (backpressure is deliberately abandoned). For infinite / long-lived streams use a bounded fold — latest, count, last-N (`(acc, chunk) => [...acc.slice(-99), chunk]`), windowed aggregates. Raw accumulation of every chunk is for finite streams only.
 - **`args` is synchronous** — returning a Promise is an error, and wildcard reads inside `args` are rejected.
 - **No self-dependency, no mutual cycles** — `args` reading the stream's own value or status raises an error. Mutual cycles between two streams (A's `args` reads B's value and vice versa) are not detected and restart forever — do not build them. One-way chains (A's value feeding B's `args`) are legitimate.

package/dist/index.esm.js

@@ -3397,12 +3397,12 @@ function hasInitialSyncModifier(binding) {
 // 頻出ポリシー（修飾子なしの通常バインディング）の凍結シングルトン。リスト行では
 // binding ごとに resolveInitialSyncPolicy が走るため、毎回のオブジェクト割り当てを
 // 避ける（record.initialPolicy は読み取り専用でしか使われない）。
-const STATE_CALL_POLICY = Object.freeze({ authority: "state", syncOn: "call", observable: false });
-const NONE_CALL_POLICY = Object.freeze({ authority: "none", syncOn: "call", observable: false });
+const STATE_CALL_POLICY = Object.freeze({ authority: "state", syncOn: "call", observable: false, outputOnly: false });
+const NONE_CALL_POLICY = Object.freeze({ authority: "none", syncOn: "call", observable: false, outputOnly: false });
 function statePolicy(authority, syncOn) {
     if (authority === "state" && syncOn === "call")
         return STATE_CALL_POLICY;
-    return { authority, syncOn, observable: false };
+    return { authority, syncOn, observable: false, outputOnly: false };
 }
 function resolveInitialSyncPolicy(binding) {
     if (!config.enableDirectionalInitialSync) {
@@ -3417,7 +3417,7 @@ function resolveInitialSyncPolicy(binding) {
         if (explicitAuthority !== null && explicitAuthority !== "none") {
             raiseError("Event bindings only allow init=none.");
         }
-        return syncOn === "call" ? NONE_CALL_POLICY : { authority: "none", syncOn, observable: false };
+        return syncOn === "call" ? NONE_CALL_POLICY : { authority: "none", syncOn, observable: false, outputOnly: false };
     }
     // command.<name>: $command.<method> は命令的な command-token 配線。bindingType は
     // "prop" だが propName ("command.<name>") は wcBindable property ではないため、下の
@@ -3455,7 +3455,7 @@ function resolveInitialSyncPolicy(binding) {
     if (syncOn === "connect" && !hasOutput) {
         raiseError(`sync=connect requires observable property "${binding.propName}".`);
     }
-    return { authority, syncOn, observable: hasOutput };
+    return { authority, syncOn, observable: hasOutput, outputOnly: hasOutput && !hasInput };
 }
 function isBindingStateInitialized(binding) {
     const rootNode = binding.replaceNode.getRootNode();
@@ -3756,9 +3756,25 @@ class BindingSession {
             return true;
         if (!record.options.registerAddress || record.phase === "waiting-definition")
             return true;
+        if (record.phase === "failed")
+            return false;
         if (record.phase === "active")
             this.settleInitialRecord(record);
-        return record.resolvedAuthority === "state";
+        // authority は初期同期のみを支配する（09 §3.6: init=element は「snapshot を
+        // state へ入れる」、init=none は「次の変更から扱う」）。settle 後の最初の相談
+        // = 初期 state sweep / 初回 render / deferred initial apply の選別なので
+        // authority で答え、ここで初期適用を消費する。
+        if (!record.initialApplyDone) {
+            record.initialApplyDone = true;
+            return record.resolvedAuthority === "state";
+        }
+        if (record.resolvedAuthority === "state")
+            return true;
+        // 定常: two-way / input member は authority と無関係に state→element を流す。
+        // 恒久ブロックは (1) output-only member の契約（書き込み無意味・DCC/router の
+        // conformance が依存）と (2) sync=connect の接続 snapshot が未解決の間
+        //（初期競合が未決着のうちは state push が element 初期値を潰しうる）だけ。
+        return !record.outputOnlyMember && !record.observationPending;
     }
     getRecord(binding) {
         const record = recordByBinding.get(binding);
@@ -4026,6 +4042,8 @@ class BindingSession {
                 initialPolicy: slot.policy,
                 resolvedAuthority: slot.authority,
                 initialSettled: true,
+                initialApplyDone: false,
+                outputOnlyMember: slot.policy.outputOnly,
                 observationPending: false,
                 eventSequence: 0,
                 hasProducerValue: false,
@@ -4079,6 +4097,8 @@ class BindingSession {
                 record.initialPolicy = slot.policy;
                 record.resolvedAuthority = slot.authority;
                 record.initialSettled = true;
+                record.initialApplyDone = false;
+                record.outputOnlyMember = slot.policy.outputOnly;
                 this.records.add(record);
                 if (slot.isEvent) {
                     try {
@@ -4137,6 +4157,8 @@ class BindingSession {
             initialPolicy: null,
             resolvedAuthority: null,
             initialSettled: false,
+            initialApplyDone: false,
+            outputOnlyMember: false,
             observationPending: false,
             eventSequence: 0,
             hasProducerValue: false,
@@ -4265,6 +4287,7 @@ class BindingSession {
             record.initialPolicy = policy;
             record.resolvedAuthority = authority;
             record.initialSettled = true;
+            record.outputOnlyMember = policy.outputOnly;
             record.phase = "active";
             if (!policy.observable)
                 return;
@@ -6873,7 +6896,7 @@ async function buildBindings(root) {
     }
 }
 
-var version = "1.21.7";
+var version = "1.22.0";
 var pkg = {
 	version: version};
 
@@ -8858,7 +8881,11 @@ function traceArgs(stateElement, entry) {
  * Rescue levels on abort:
  *   - ReadableStream: FULLY rescued. A parked read() is force-unwound via
  *     reader.cancel(), which both releases the underlying source and settles the
- *     pending read() so the loop unwinds.
+ *     pending read() so the loop unwinds. Anything getReader-bearing is routed
+ *     through this path even when it is ALSO natively async-iterable (Node 18+ /
+ *     Chrome 124+ / Firefox): the spec serializes asyncIterator.return() behind
+ *     the pending next() ([[ongoingPromise]]), so the AsyncIterable rescue below
+ *     cannot force-unwind a parked read on a native ReadableStream.
  *   - AsyncIterable / async generator: PARTIALLY rescued. On abort we call
  *     iterator.return() to trigger the generator's finally/cleanup. But a parked
  *     `await` (the producer stalling before its next yield while IGNORING `signal`)
@@ -8939,19 +8966,24 @@ async function consumeSource(source, args, signal, sink) {
     }
 }
 function iterate(produced, signal) {
-    // Optional chaining: a null/undefined source return value must fall through to the
-    // explicit TypeError below (symmetric with the `?.` on the getReader probe), not
-    // throw an opaque "Cannot read properties of null" from this property access.
+    // Anything ReadableStream-shaped (has getReader) takes the reader path FIRST —
+    // even when it is also async-iterable. On runtimes where ReadableStream
+    // implements native async iteration (Node 18+ / Chrome 124+ / Firefox), the
+    // spec serializes `iterator.return()` behind the pending `next()`
+    // ([[ongoingPromise]]), so the AsyncIterable rescue cannot force-unwind a
+    // parked read: abort would hang the consume task until the producer's next
+    // chunk (or forever on a silent stream), leaking the underlying source.
+    // `reader.cancel()` has no such ordering — routing every getReader-bearing
+    // source through it keeps the FULL rescue promised for ReadableStream.
+    // Optional chaining: a null/undefined source return value must fall through to
+    // the explicit TypeError below, not throw an opaque property access error.
+    if (typeof produced?.getReader === "function") {
+        return readableToAsyncIterable(produced, signal);
+    }
     if (typeof produced?.[Symbol.asyncIterator] === "function") {
         return produced;
     }
-    // Not async-iterable: must be a ReadableStream (read via getReader). Validate so
-    // a wrong source value yields a clear error instead of an opaque "getReader is
-    // not a function" from inside the generator.
-    if (typeof produced?.getReader !== "function") {
-        throw new TypeError("[@wcstack/state] $streams: source must return an AsyncIterable or a ReadableStream (got neither).");
-    }
-    return readableToAsyncIterable(produced, signal);
+    throw new TypeError("[@wcstack/state] $streams: source must return an AsyncIterable or a ReadableStream (got neither).");
 }
 async function* readableToAsyncIterable(stream, signal) {
     const reader = stream.getReader();