@uzuhq/code-sdk 0.7.6 → 0.7.7

package/dist/run/optimistic-action-client.js

@@ -1,209 +0,0 @@
-import { applyPatch } from '../json-patch.js';
-import { isServerOnlyAction } from '../server-only.js';
-import { runPredicted } from '../dev-prediction-traps.js';
-import { observeServerTime, serverNow } from '../server-clock.js';
-export function createOptimisticActionClient(config) {
-    const { logic, playerId, onState, events, sendAction } = config;
-    /** サーバー確定 state (楽観的更新のベース) */
-    let confirmedState = null;
-    /** 表示用 state (pending actions 適用済み) */
-    let displayState = null;
-    /** クライアント側の action 通番 */
-    let actionSeq = 0;
-    /**
-     * 送信済みだがサーバー未確認の action キュー。
-     * `now` は送信時に推定した値。再適用でも同じ値を使う (取り直すと表示がガタつく)。
-     */
-    const pendingActions = [];
-    /**
-     * 先読みで実行済みの events。
-     *
-     * IMPORTANT: pending action ごとではなくクライアント単位で持つ。二重実行は「自分の
-     * action の ack」だけでなく「他プレイヤーの action のブロードキャスト」でも起きるため
-     * (A と B が同時に同じ行送りを撃つと、B は自分の先読みで実行済みなのに A 由来の
-     * 配信でもう一度実行してしまう)。どの配信が来ても、まずここと突き合わせる。
-     *
-     * 記録には「どの action の先読みで実行したか」(seq) を持たせる。その action が ack
-     * された時点で引き当てられていない記録は「予測したが実際には起きなかった出来事」なので
-     * 捨てる。seq を持たせずに「pending が空になったら捨てる」だけにすると、別の action が
-     * 未確定な間ずっと外れた記録が生き残り、その後に本当に起きた同名イベントを 1 回
-     * 握り潰してしまう。
-     *
-     * サーバーは 1 本の接続へ処理順どおりに送るので、他プレイヤーの配信は自分の ack より
-     * 必ず先に届く = 引き当てのチャンスは記録が生きている間に必ず来る。
-     */
-    let firedPredictions = [];
-    /** 再適用時はイベントを発火しない (送信時に既に発火済み) */
-    const noopEmit = () => { };
-    const dispatchEvents = (evts) => {
-        for (const e of evts)
-            events?.[e.name]?.handler(e.data);
-    };
-    /** events の同一性キー。name と data が一致すれば「同じ出来事」とみなす。 */
-    const eventKey = (e) => `${e.name}\u0000${JSON.stringify(e.data ?? {})}`;
-    /**
-     * サーバーの events から、先読みで実行済みのものを差し引く (多重集合の差)。
-     *
-     * - 予測が当たった  → 差が空。二重に実行しない
-     * - 予測が外れた    → サーバー側の正しい event が残り、確定として実行される
-     * - 先読みで実行していない (predict: false / serverActions 由来 / 他プレイヤー由来)
-     *   → そのまま残って実行される
-     */
-    const subtractFired = (serverEvts) => {
-        if (firedPredictions.length === 0)
-            return serverEvts;
-        const out = [];
-        for (const e of serverEvts) {
-            const k = eventKey(e);
-            const idx = firedPredictions.findIndex((f) => eventKey(f) === k);
-            // 一致したら「先読みで実行済み」なので配信せず、記録も 1 件消費する。
-            if (idx >= 0)
-                firedPredictions.splice(idx, 1);
-            else
-                out.push(e);
-        }
-        return out;
-    };
-    /**
-     * confirmedState をベースに pending actions を再適用して displayState を更新する。
-     * 再適用失敗した action はキューから除去する。
-     */
-    const reapplyPendingActions = () => {
-        if (confirmedState === null)
-            return;
-        displayState = structuredClone(confirmedState);
-        let i = 0;
-        while (i < pendingActions.length) {
-            const { action, payload, now } = pendingActions[i];
-            const handler = logic.actions[action];
-            // 移行期の互換: 旧 serverOnly() を actions に入れたままの logic では、その handler は
-            // サーバー専用なので先読みの再適用対象から外す (send 時にも pending へ積んでいない)。
-            if (!handler || isServerOnlyAction(handler)) {
-                pendingActions.splice(i, 1);
-                continue;
-            }
-            // handler が途中まで state を変更してから throw すると、その部分変更が残ったまま
-            // publish されてしまう。1 件ごとに直前の確定形から作り直し、成功したものだけ採用する。
-            const base = structuredClone(displayState);
-            try {
-                runPredicted(action, () => handler({
-                    state: displayState,
-                    payload,
-                    playerId,
-                    ctx: { now, emit: noopEmit },
-                }));
-                i++;
-            }
-            catch {
-                displayState = base;
-                pendingActions.splice(i, 1);
-            }
-        }
-        onState(displayState, playerId);
-    };
-    /**
-     * サーバーからの配信を処理する。
-     *
-     * 送信元が誰であれ、まず先読みの実行記録と突き合わせる。自分の ack だけを見ていると、
-     * 他プレイヤーの action が同じ出来事を起こしたときに二重実行になる。
-     */
-    const handleAck = (ack, from, evts) => {
-        dispatchEvents(subtractFired(evts));
-        if (from === playerId && ack !== undefined) {
-            while (pendingActions.length > 0 && pendingActions[0].seq <= ack) {
-                pendingActions.shift();
-            }
-            // 確定した action の記録で引き当てられなかったものは「予測したが実際には
-            // 起きなかった出来事」。残すと次に本当に起きたときに握り潰してしまう。
-            firedPredictions = firedPredictions.filter((f) => f.seq > ack);
-        }
-    };
-    return {
-        send(type, payload) {
-            actionSeq++;
-            const seq = actionSeq;
-            // 先読みするのは logic.actions だけ。serverActions は transport にだけ送り、
-            // 結果は ack (state + serverEvents) で受け取る。
-            const handler = logic.actions[type];
-            // どちらにも無い action は届く先が無い。 黙って捨てると UI 上は無反応なのに
-            // 原因が分からないので、 ここで気付けるようにする。 serverActions にだけある
-            // action は actions[type] が undefined でも正常なので、 両方を見る。
-            if (!handler && !logic.serverActions?.[type]) {
-                console.error(`[uzu] unknown action: "${type}". logic.actions / logic.serverActions のどちらにも登録されていません。`);
-            }
-            // callback 内では displayState の narrowing が効かないので const に退避する。
-            const target = displayState;
-            // サーバーがこのアクションを処理する時刻の推定。再適用でも同じ値を使うので、
-            // ここで 1 回だけ確定させて pending に載せる。
-            const now = serverNow();
-            // predict: true の event だけ先読み時点で実行し、実行したものを記録する。
-            const predictEmit = (eventName, data) => {
-                const subscription = events?.[eventName];
-                if (!subscription?.predict)
-                    return;
-                const payloadData = data ?? {};
-                subscription.handler(payloadData);
-                firedPredictions.push({ seq, name: eventName, data: payloadData });
-            };
-            // 旧 serverOnly() が actions に残っている logic では、その handler を先読みすると
-            // サーバー専用のはずの副作用がクライアントでも走る。brand を見て弾く。
-            if (handler && !isServerOnlyAction(handler) && target !== null) {
-                try {
-                    runPredicted(type, () => handler({
-                        state: target,
-                        payload: payload ?? {},
-                        playerId,
-                        ctx: { now, emit: predictEmit },
-                    }));
-                    pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
-                    onState(target, playerId);
-                }
-                catch {
-                    // ローカル実行失敗 → 楽観的更新せずサーバーに送るだけ
-                }
-            }
-            sendAction({ action: type, payload: payload ?? {}, seq });
-        },
-        observeServerTime(serverTime) {
-            // 実体は server-clock.ts (UI 側の serverNow() と同じオフセットを共有する)。
-            observeServerTime(serverTime);
-        },
-        applyState(state, options = {}) {
-            handleAck(options.ack, options.from, options.events ?? []);
-            confirmedState = state;
-            reapplyPendingActions();
-        },
-        applyDelta(patches, options = {}) {
-            if (confirmedState === null)
-                return false;
-            // patch の適用可否を確定してから events 発火と pending 掃除を行う。適用失敗時は
-            // events を発火せず false を返し、transport 側でフル state を再要求する。これにより
-            // 「delta を適用できない (seq gap / patch 失敗) なら events を発火せずフル state を
-            // 要求する」という挙動が両経路で揃う (seq gap は transport 側で早期 return)。
-            const cloned = structuredClone(confirmedState);
-            const ok = applyPatch(cloned, patches);
-            if (!ok)
-                return false;
-            confirmedState = cloned;
-            handleAck(options.ack, options.from, options.events ?? []);
-            reapplyPendingActions();
-            return true;
-        },
-        rollback(seq) {
-            const idx = pendingActions.findIndex((p) => p.seq === seq);
-            if (idx !== -1) {
-                pendingActions.splice(idx, 1);
-                // rollback した action の先読み記録も捨てる (その出来事は起きなかった)。
-                firedPredictions = firedPredictions.filter((f) => f.seq !== seq);
-                reapplyPendingActions();
-            }
-        },
-        reset(state) {
-            pendingActions.length = 0;
-            firedPredictions = [];
-            confirmedState = state;
-            displayState = structuredClone(state);
-            onState(displayState, playerId);
-        },
-    };
-}

package/dist/run/optimistic-action-client.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/run/optimistic-action-client.test.js

@@ -1,430 +0,0 @@
-/**
- * optimistic-action-client.ts の unit test。
- *
- * `logic.actions` (クライアント先読み + サーバーの 2 回実行) と `logic.serverActions`
- * (サーバーのみ 1 回実行) を分離した設計が、events の配信と pending キューの巻き戻しの
- * 両方で正しく閉じることを検証する。
- *
- * events はサーバーから 1 本のリストで届き、クライアントが「先読みで自分が配信した分」を
- * 差し引いて残りを確定として発火する。予測が当たれば二重に鳴らず、外れればサーバー側の
- * 正しい event が追って届く。
- */
-import { describe, expect, it, vi } from 'vitest';
-import { createOptimisticActionClient } from './optimistic-action-client.js';
-import { serverOnly } from '../server-only.js';
-import { resetServerTimeOffset } from '../server-clock.js';
-/**
- * `serverOnly()` の brand が付いた handler。`actions` に入っていても先読みされないこと
- * (brand 判定が効くこと) を確かめる。旧シグネチャの互換は検証対象ではない。
- */
-const legacyServerOnly = serverOnly(({ state }) => {
-    state.charged += 1000;
-});
-const makeLogic = () => ({
-    setup: () => ({ moves: 0, charged: 0, stampedAt: 0 }),
-    actions: {
-        move: ({ state, ctx }) => {
-            state.moves += 1;
-            state.stampedAt = ctx.now;
-            ctx.emit('moved', {});
-        },
-        // 予測の結果によって別の event を出す (予測ミスの再現用)
-        guess: ({ state, payload, ctx }) => {
-            state.moves += 1;
-            ctx.emit(payload?.willEmit ?? 'accepted', payload?.data ?? {});
-        },
-        boom: () => {
-            throw new Error('always fails');
-        },
-        // 途中まで state を書き換えてから throw する (部分ミューテーションの検証用)
-        partial: ({ state }) => {
-            state.moves += 1;
-            throw new Error('fails after mutating');
-        },
-        // 旧 serverOnly() が actions に残っている logic の再現
-        // @ts-expect-error 移行期の互換挙動を検証するため意図的に型違反させる
-        legacy: legacyServerOnly,
-    },
-    serverActions: {
-        // move と同名 = 同じ action の「サーバーだけで走る続き」
-        move: ({ state, ctx }) => {
-            state.charged += ctx.tick;
-            ctx.emit('charged', {});
-        },
-        // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
-        notifyExternal: ({ state }) => {
-            state.charged += 100;
-        },
-    },
-    update: () => { },
-});
-/** 直近の onState 通知。tsconfig の lib が Array#at 未対応なので添字で取る。 */
-const latest = (states) => states[states.length - 1];
-const setup = () => {
-    // サーバー時刻オフセットは module 単位で共有されるので、テスト間で持ち越さない。
-    resetServerTimeOffset();
-    const sent = [];
-    const fired = [];
-    const states = [];
-    const client = createOptimisticActionClient({
-        logic: makeLogic(),
-        playerId: 'me',
-        onState: (s) => states.push(structuredClone(s)),
-        events: {
-            // predict: true = 先読み時点で実行する
-            moved: {
-                predict: true,
-                handler: (d) => {
-                    fired.push(`moved${d.n ?? ''}`);
-                },
-            },
-            accepted: {
-                predict: true,
-                handler: () => {
-                    fired.push('accepted');
-                },
-            },
-            tooLate: {
-                predict: true,
-                handler: () => {
-                    fired.push('tooLate');
-                },
-            },
-            // predict: false = サーバー確定後だけ実行する
-            charged: {
-                predict: false,
-                handler: () => {
-                    fired.push('charged');
-                },
-            },
-            fanfare: {
-                predict: false,
-                handler: () => {
-                    fired.push('fanfare');
-                },
-            },
-        },
-        sendAction: ({ action, seq }) => sent.push({ action, seq }),
-    });
-    client.reset({ moves: 0, charged: 0, stampedAt: 0 });
-    return { client, sent, fired, states };
-};
-describe('createOptimisticActionClient', () => {
-    describe('先読みの対象', () => {
-        /** actions にある handler だけがクライアントで先行実行される。 */
-        it('actions の handler は送信時に先行実行される', () => {
-            const { client, sent, states } = setup();
-            client.send('move');
-            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
-            expect(sent).toEqual([{ action: 'move', seq: 1 }]);
-        });
-        /**
-         * serverActions にしか無い action は先読みされない。state を触らずサーバーへ送るだけ。
-         * 旧 serverOnly() と同じ挙動。
-         */
-        it('serverActions にしか無い action は先行実行されない', () => {
-            const { client, sent, states } = setup();
-            client.send('notifyExternal');
-            expect(latest(states)).toMatchObject({ moves: 0, charged: 0 });
-            expect(sent).toEqual([{ action: 'notifyExternal', seq: 1 }]);
-        });
-        /**
-         * 同名で両方定義されている場合、先読みされるのは actions 側だけ。
-         * serverActions 側の結果 (charged) はサーバーの ack が来るまで反映されない。
-         */
-        it('同名で両方ある場合、先読みは actions 側だけ', () => {
-            const { client, states } = setup();
-            client.send('move');
-            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
-        });
-    });
-    describe('events の配信', () => {
-        /**
-         * 予測が当たった場合、確定時に再発火しない。二重に鳴ると効果音が 2 回鳴る。
-         * 先読みで 1 回だけ (predicted: true) 発火していること。
-         */
-        it('予測が当たったら確定時に再発火しない', () => {
-            const { client, fired } = setup();
-            client.send('move'); // 先読みで moved が発火
-            expect(fired).toEqual(['moved']);
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'moved', data: {} }] });
-            expect(fired).toEqual(['moved']);
-        });
-        /**
-         * IMPORTANT: 予測が外れた場合、サーバー側の正しい event が確定として発火する。
-         *
-         * 旧実装は「自分の ack なら actions 由来の events を全部 skip」していたため、
-         * 別の分岐を通っていると正しい event が永久に届かなかった。
-         */
-        it('予測が外れたらサーバー側の event が確定として発火する', () => {
-            const { client, fired } = setup();
-            client.send('guess', { willEmit: 'accepted' }); // 先読みでは accepted
-            expect(fired).toEqual(['accepted']);
-            // サーバーは tooLate だった
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'tooLate', data: {} }] });
-            expect(fired).toEqual(['accepted', 'tooLate']);
-        });
-        /**
-         * serverActions 由来の events は先読みで走っていないので確定として発火する。
-         * サーバーは events を 1 本で送るが、クライアントが自分の発火記録を差し引くので
-         * 袋を分ける必要がない (旧 serverEvents は廃止)。
-         */
-        it('先読みしていない event は 1 本のリストからでも発火する', () => {
-            const { client, fired } = setup();
-            client.send('move'); // 先読みで moved のみ
-            client.applyState({ moves: 1, charged: 5, stampedAt: 0 }, {
-                ack: 1,
-                from: 'me',
-                // actions 由来 (moved) と serverActions 由来 (charged) が同じ配列で届く
-                events: [
-                    { name: 'moved', data: {} },
-                    { name: 'charged', data: {} },
-                ],
-            });
-            expect(fired).toEqual(['moved', 'charged']);
-        });
-        /** 他プレイヤーの action なら先読みしていないので全部確定として発火する。 */
-        it('他プレイヤーの ack では全部確定として発火する', () => {
-            const { client, fired } = setup();
-            client.applyState({ moves: 1, charged: 5, stampedAt: 0 }, {
-                ack: 1,
-                from: 'other',
-                events: [
-                    { name: 'moved', data: {} },
-                    { name: 'charged', data: {} },
-                ],
-            });
-            expect(fired).toEqual(['moved', 'charged']);
-        });
-        /** predict: false の event は先読みで実行されず、確定時に 1 回だけ実行される。 */
-        it('predict: false の event は確定時にだけ実行される', () => {
-            const { client, fired } = setup();
-            client.send('guess', { willEmit: 'fanfare' });
-            expect(fired).toEqual([]);
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [{ name: 'fanfare', data: {} }] });
-            expect(fired).toEqual(['fanfare']);
-        });
-        /**
-         * IMPORTANT: 他プレイヤーの action が同じ出来事を起こしても二重実行しない。
-         *
-         * A と B が同時に同じ行送りを撃つと、サーバーは先着の A だけを通し、B の分は
-         * 握り潰す。 B から見て届くのは「A の action の ack」なので、記録を自分の pending に
-         * 紐づけていると引き当てられず、先読みで実行済みなのにもう一度実行してしまう。
-         * (e2e/prediction-misfire.mjs で実測した回帰)
-         */
-        it('他プレイヤー由来の配信でも先読み済みなら二重実行しない', () => {
-            const { client, fired } = setup();
-            // 自分も撃った (先読みで moved1 を実行)
-            client.send('guess', { willEmit: 'moved', data: { n: 1 } });
-            expect(fired).toEqual(['moved1']);
-            // 先に着いた他プレイヤーの action が同じ出来事を起こして配信されてくる
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
-            expect(fired).toEqual(['moved1']);
-        });
-        /**
-         * IMPORTANT: 予測が外れた記録は「その action が ack された時点」で捨てる。
-         *
-         * 「未確定の action が全部無くなったら捨てる」だけだと、別の action が未確定な間
-         * ずっと外れた記録が生き残り、その後に本当に起きた同名イベントを 1 回握り潰す。
-         * (レビュー指摘の再現)
-         */
-        it('別の action が未確定でも、外れた記録はその ack で捨てる', () => {
-            const { client, fired } = setup();
-            client.send('guess', { willEmit: 'moved', data: { n: 1 } }); // seq 1: 先読みで実行
-            client.send('move'); // seq 2: まだ未確定のまま残す
-            expect(fired).toEqual(['moved1', 'moved']);
-            // seq 1 の ack。サーバーは moved1 を出さなかった = 予測が外れた
-            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [] });
-            // seq 2 が未確定でも、seq 1 の記録は捨てられている
-            // → 他プレイヤー由来の本物の moved1 は実行されるべき
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
-            expect(fired).toEqual(['moved1', 'moved', 'moved1']);
-        });
-        /**
-         * 予測が外れて実際には起きなかった出来事の記録は、その action の ack で破棄する。
-         * 残したままだと、次に本当にその出来事が起きたときに実行されなくなる。
-         */
-        it('外れた記録は ack で破棄する', () => {
-            const { client, fired } = setup();
-            client.send('guess', { willEmit: 'moved', data: { n: 1 } });
-            expect(fired).toEqual(['moved1']);
-            // 自分の ack。サーバーは何も起こさなかった (予測が外れた)
-            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 1, from: 'me', events: [] });
-            expect(fired).toEqual(['moved1']);
-            // 後から本当に起きた同じ出来事は、記録が消えているので実行される
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, { ack: 100, from: 'other', events: [{ name: 'moved', data: { n: 1 } }] });
-            expect(fired).toEqual(['moved1', 'moved1']);
-        });
-        /** 同じ event が 2 回来たら、先読み 1 回分だけを差し引く (多重集合の差)。 */
-        it('同じ event が複数回でも先読み分だけ差し引く', () => {
-            const { client, fired } = setup();
-            client.send('move'); // 先読みで moved 1 回
-            client.applyState({ moves: 1, charged: 0, stampedAt: 0 }, {
-                ack: 1,
-                from: 'me',
-                events: [
-                    { name: 'moved', data: {} },
-                    { name: 'moved', data: {} },
-                ],
-            });
-            expect(fired).toEqual(['moved', 'moved']);
-        });
-    });
-    describe('pending キューと巻き戻し', () => {
-        /**
-         * pending に積まれるのは actions 分だけ。サーバー確定 state を受けたら、
-         * 未 ack の actions だけが再適用される (serverActions 分は state に含まれて来る)。
-         */
-        it('確定 state の上に未 ack の actions だけを再適用する', () => {
-            const { client, states } = setup();
-            client.send('move'); // seq 1
-            client.send('move'); // seq 2
-            // seq 1 だけ確定。charged はサーバー側で加算済みの値が入っている
-            client.applyState({ moves: 1, charged: 7, stampedAt: 0 }, { ack: 1, from: 'me' });
-            // 確定 (moves:1) + 未 ack の seq 2 を再適用 = moves:2、charged はサーバー値のまま
-            expect(latest(states)).toMatchObject({ moves: 2, charged: 7 });
-        });
-        /** __action_error で該当 seq を除去し、残りを再適用する。 */
-        it('rollback は該当 action だけを取り消す', () => {
-            const { client, states } = setup();
-            client.send('move'); // seq 1
-            client.send('move'); // seq 2
-            expect(latest(states)).toMatchObject({ moves: 2, charged: 0 });
-            client.rollback(1);
-            // seq 1 が消えて seq 2 だけ再適用される
-            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
-        });
-        /** 先行実行で throw した action は pending に積まれず、送信だけ行われる。 */
-        it('先行実行が throw した action は pending に積まれない', () => {
-            const { client, sent, states } = setup();
-            client.send('boom');
-            expect(sent).toEqual([{ action: 'boom', seq: 1 }]);
-            // pending が空なので、確定 state がそのまま表示される
-            client.applyState({ moves: 9, charged: 9, stampedAt: 0 }, {});
-            expect(latest(states)).toMatchObject({ moves: 9, charged: 9 });
-        });
-    });
-    describe('applyDelta', () => {
-        /** delta 経路でも events の差し引きは applyState と揃っている。 */
-        it('先読み済みを差し引いた残りだけを発火する', () => {
-            const { client, fired } = setup();
-            client.send('move'); // 先読みで moved
-            const ok = client.applyDelta([{ op: 'replace', path: '/charged', value: 3 }], {
-                ack: 1,
-                from: 'me',
-                events: [
-                    { name: 'moved', data: {} },
-                    { name: 'charged', data: {} },
-                ],
-            });
-            expect(ok).toBe(true);
-            expect(fired).toEqual(['moved', 'charged']);
-        });
-        /** patch が当たらないときは events を発火せず false を返す (transport がフル state を再要求する)。 */
-        it('patch 適用に失敗したら events を発火せず false を返す', () => {
-            const { client, fired } = setup();
-            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
-            const ok = client.applyDelta([{ op: 'replace', path: '/missing/deep', value: 1 }], {
-                events: [{ name: 'moved', data: {} }],
-            });
-            expect(ok).toBe(false);
-            expect(fired).toEqual([]);
-            warn.mockRestore();
-        });
-    });
-    describe('レビュー指摘の回帰防止', () => {
-        /**
-         * 旧 serverOnly() が actions に残っている logic では、その handler をクライアントで
-         * 先読みしてはいけない。サーバー専用の副作用 (fetch 等) が client でも走ってしまう。
-         */
-        it('actions に残った serverOnly() は先読みしない', () => {
-            const { client, sent, states } = setup();
-            client.send('legacy');
-            // state は動かず、送信だけ行われる
-            expect(latest(states)).toMatchObject({ moves: 0, charged: 0 });
-            expect(sent).toEqual([{ action: 'legacy', seq: 1 }]);
-        });
-        /** 再適用でも同じ。pending に積まれていても brand 付きなら実行しない。 */
-        it('再適用でも serverOnly() を実行しない', () => {
-            const { client, states } = setup();
-            client.send('move'); // seq 1 (pending へ)
-            client.send('legacy'); // seq 2 (pending へは積まれない)
-            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, {});
-            // 確定 state に move だけが再適用され、legacy の +1000 は入らない
-            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
-        });
-        /**
-         * 再適用中に handler が途中まで state を変更してから throw した場合、その部分変更を
-         * 残したまま publish してはいけない。
-         */
-        it('再適用で throw した handler の部分変更を残さない', () => {
-            const { client, states } = setup();
-            client.send('move'); // seq 1: moves +1
-            client.send('partial'); // seq 2: moves +1 してから throw (pending には積まれない)
-            // 送信時点で partial は throw するので pending に入らず、moves は 1 のまま
-            expect(latest(states).moves).toBe(1);
-            // 確定 state を受けて再適用しても、partial の部分変更は混ざらない
-            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, {});
-            expect(latest(states)).toMatchObject({ moves: 1, charged: 0 });
-        });
-    });
-    /**
-     * ctx.now の配布。
-     *
-     * actions はクライアント先読みとサーバーで 2 回走るため、handler の中で Date.now() を
-     * 読むと端末の時計ズレがそのまま state に入る。ctx.now はサーバーとのクロック
-     * オフセットで補正した推定値を配ることでこれを防ぐ。
-     */
-    describe('ctx.now', () => {
-        /** オフセット未取得なら素のローカル時刻。オフラインでも壊れないこと。 */
-        it('サーバー時刻を観測する前はローカル時刻が入る', () => {
-            const { client, states } = setup();
-            const before = Date.now();
-            client.send('move');
-            expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
-            expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
-        });
-        /**
-         * 端末の時計が大きくズレていても、サーバー時刻の観測でオフセットが補正される。
-         * ここでは「サーバーが 1 時間先」を観測させ、ctx.now がそちらへ寄ることを見る。
-         */
-        it('サーバー時刻を観測するとオフセット分ずれた値が入る', () => {
-            const { client, states } = setup();
-            const ONE_HOUR = 3600 * 1000;
-            client.observeServerTime(Date.now() + ONE_HOUR);
-            client.send('move');
-            const stamped = latest(states).stampedAt;
-            // 1 時間先へ寄っている (テスト実行のブレを考慮して幅を持たせる)
-            expect(stamped).toBeGreaterThan(Date.now() + ONE_HOUR - 5000);
-            expect(stamped).toBeLessThan(Date.now() + ONE_HOUR + 5000);
-        });
-        /** 数値でない / 欠けている場合は無視する (serverTime を持たないメッセージ用)。 */
-        it('不正な観測値は無視される', () => {
-            const { client, states } = setup();
-            client.observeServerTime(undefined);
-            client.observeServerTime(Number.NaN);
-            const before = Date.now();
-            client.send('move');
-            expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
-            expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
-        });
-        /**
-         * IMPORTANT: 再適用 (reconciliation でのやり直し) では初回予測時の now を使い回す。
-         *
-         * 取り直すと、サーバーから ack が来るたびに handler が別の時刻で走り、
-         * timerEndsAt のような値が毎回ズレて秒読みがガタつく。
-         */
-        it('再適用でも初回予測時の now を使い回す', () => {
-            const { client, states } = setup();
-            client.send('move');
-            const firstStamp = latest(states).stampedAt;
-            // 再適用の直前にオフセットを大きく動かす。now を取り直す実装ならここで
-            // stampedAt が 1 時間ジャンプするので、使い回しているかを確実に判別できる。
-            client.observeServerTime(Date.now() + 3600 * 1000);
-            // 別プレイヤーの ack を受けて再適用させる (自分の pending は残る)
-            client.applyState({ moves: 0, charged: 0, stampedAt: 0 }, { ack: 99, from: 'other' });
-            expect(latest(states).moves).toBe(1);
-            expect(latest(states).stampedAt).toBe(firstStamp);
-        });
-    });
-});

package/dist/run/server-action.d.ts

@@ -1,16 +0,0 @@
-/**
- * @docs
- * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
- * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
- *
- * ServerAction モードのオンライン接続 (WebSocket トランスポート)。
- *
- * ホスト/ゲストの区別なし。全クライアントがサーバーに対して同じ立場で action を送信し、
- * サーバーが reducer を実行して state を遷移させる。
- *
- * 楽観的更新ロジック (pending actions / reapply / ack 重複排除) は
- * `optimistic-action-client.ts` に集約。本ファイルは WebSocket 固有の責務
- * (接続管理 / メッセージ振り分け / delta seq の連続性チェック / フル state 再要求) のみ持つ。
- */
-import type { GameConfig, Seat, SeatKind } from '../types.js';
-export declare function runOnlineServerAction<S>(config: GameConfig<S>, gameEndpoint: string, roomId: string, seatId: string, players: Seat[], seatKind: SeatKind): void;