@uzuhq/code-sdk 0.3.10 → 0.5.0

package/dist/dev-hooks.d.ts

@@ -20,6 +20,7 @@
  * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
  */
 import type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
+import type { PredictionWarning } from './dev-prediction-traps.js';
 import type { ServerEvent } from './types.js';
 export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
@@ -36,6 +37,13 @@ export interface UzuDevHooks<S = unknown> {
      * 貼り付けやすい uint32 を返す。
      */
     getSeed?(): number;
+    /**
+     * 素の action handler が先読み実行中に実時刻 / 乱数を読んだ記録。
+     *
+     * 先読みはサーバーと同じ結果を再現できることが前提なので、ここに何か入っていたら
+     * そのシナリオはオンラインでだけ予測がズレる。E2E で `[]` を assert すると回帰を防げる。
+     */
+    getPredictionWarnings(): readonly PredictionWarning[];
     /**
      * Server-side で action を直接 dispatch する。
      *

package/dist/dev-hooks.js

@@ -19,6 +19,7 @@
  * scenario 固有の helper (特定 field path の読み書き / phase 遷移時の field reset /
  * 特定 action 名のラッパー等) は scenario 側で window.__<scene>_dev を生やす。
  */
+import { getPredictionWarnings } from './dev-prediction-traps.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export function createDevHooks(ctx) {
     const getRawState = () => (ctx.getRawState ? ctx.getRawState() : null);
@@ -69,6 +70,7 @@ export function createDevHooks(ctx) {
         playerId: () => ctx.playerId(),
         subscribeSnapshot: (cb) => ctx.subscribeSnapshot(cb),
         waitForSnapshot,
+        getPredictionWarnings: () => getPredictionWarnings(),
     };
     if (ctx.sendAction) {
         const sendAction = ctx.sendAction;

package/dist/dev-prediction-traps.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
+ *
+ * 素の action handler のクライアント先読み実行中に、サーバーと結果が一致しない API
+ * (実時刻 / 乱数) が呼ばれたら警告する。
+ *
+ * 先読みは「サーバーと同じコードを同じ入力で走らせれば同じ結果になる」ことが前提で、
+ * 実時刻や乱数を読むとその前提が崩れる。ズレた state は一瞬表示されたあと ack で
+ * 上書きされ、画面が飛ぶ。
+ *
+ * 静的解析ではなく実行時に差し替えるのは、handler がヘルパー関数を何段挟んでいても
+ * 捕まえたいから。同じ理由で、演出用途 (描画ループの `Math.sin(Date.now() / 400)` など)
+ * は先読み経路を通らないので原理的に誤検知しない。
+ */
+export interface PredictionWarning {
+    /** 呼び出した action 名 */
+    action: string;
+    /** 呼ばれた API 名 (`'Date.now()'` など) */
+    api: string;
+}
+/**
+ * 素の action handler の先読み実行を計装して走らせる。
+ *
+ * Flutter native ホスト (本番) では計装せず素通しする。判定基準は dev hooks と同じ。
+ */
+export declare const runPredicted: (action: string, run: () => void) => void;
+/** 検出済みの警告一覧。`__uzu_dev.getPredictionWarnings()` から E2E で assert する用。 */
+export declare const getPredictionWarnings: () => readonly PredictionWarning[];
+/** 検出結果をリセットする (テスト用)。 */
+export declare const clearPredictionWarnings: () => void;

package/dist/dev-prediction-traps.test.d.ts

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

package/dist/dev-prediction-traps.test.js

@@ -0,0 +1,178 @@
+/**
+ * dev-prediction-traps.ts の unit test。
+ *
+ * 素の action handler をクライアント先読みで実行する間だけグローバルを差し替え、
+ * サーバーと結果が一致しない API (実時刻 / 乱数) の呼び出しを検出する仕組みを検証する。
+ *
+ * カバー対象:
+ * - 検出対象 API それぞれが記録されること
+ * - ヘルパー関数を経由した呼び出しも捕まえること (静的解析では追えない経路)
+ * - 同じ action / API の重複を 1 件に畳むこと
+ * - 実行後にグローバルが必ず元へ戻ること (例外時も含む)
+ * - 先読みの外では計装されていないこと
+ * - 本番 (Flutter native ホスト) では計装しないこと
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { clearPredictionWarnings, getPredictionWarnings, runPredicted, } from './dev-prediction-traps.js';
+beforeEach(() => {
+    clearPredictionWarnings();
+    // 警告本文は console に出るので、テスト出力を汚さないよう黙らせる。
+    vi.spyOn(console, 'groupCollapsed').mockImplementation(() => { });
+    vi.spyOn(console, 'log').mockImplementation(() => { });
+    vi.spyOn(console, 'groupEnd').mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete window.FlutterHost;
+});
+describe('runPredicted', () => {
+    /** 検出対象 API を先読み中に呼ぶと、action 名とセットで記録される。 */
+    describe('非決定的な API の検出', () => {
+        it('Date.now() を記録する', () => {
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'gm.timer.set', api: 'Date.now()' }]);
+        });
+        it('引数なしの new Date() を記録する', () => {
+            runPredicted('startPresentation', () => {
+                new Date();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'startPresentation', api: 'new Date()' }]);
+        });
+        /**
+         * 引数付きの new Date() は与えられた値から決まるので、サーバーと結果がズレない。
+         * 誤検知を避けるため記録しない。
+         */
+        it('引数付きの new Date(...) は記録しない', () => {
+            runPredicted('setDeadline', () => {
+                new Date(1700000000000);
+            });
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+        it('Math.random() を記録する', () => {
+            runPredicted('restart', () => {
+                Math.random();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'restart', api: 'Math.random()' }]);
+        });
+        it('performance.now() を記録する', () => {
+            runPredicted('tickLocal', () => {
+                performance.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'tickLocal', api: 'performance.now()' }]);
+        });
+        /**
+         * 静的解析が最も苦手とする経路。handler 本体に API が現れず、ヘルパー関数の中で
+         * 呼ばれていても捕まえられることを保証する (kikaidochu の setLine が実際にこの形)。
+         */
+        it('ヘルパー関数を経由した呼び出しも記録する', () => {
+            const setDeadlineViaHelper = () => Date.now() + 60000;
+            runPredicted('setLine', () => {
+                setDeadlineViaHelper();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'setLine', api: 'Date.now()' }]);
+        });
+        /** 元の API の戻り値はそのまま通す (計装で挙動を変えない)。 */
+        it('元の API の戻り値を変えない', () => {
+            let observed = 0;
+            runPredicted('noop', () => {
+                observed = Date.now();
+            });
+            expect(observed).toBeGreaterThan(0);
+        });
+    });
+    describe('重複の抑制', () => {
+        /** 同じ action で同じ API を何度呼んでも記録は 1 件。連打でログが溢れない。 */
+        it('同一 action / 同一 API は 1 件に畳む', () => {
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+                Date.now();
+            });
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([{ action: 'gm.timer.set', api: 'Date.now()' }]);
+        });
+        /** action が違えば別件として記録する。どの action を直すべきか分かる必要がある。 */
+        it('action が違えば別件として記録する', () => {
+            runPredicted('a', () => {
+                Date.now();
+            });
+            runPredicted('b', () => {
+                Date.now();
+            });
+            expect(getPredictionWarnings()).toEqual([
+                { action: 'a', api: 'Date.now()' },
+                { action: 'b', api: 'Date.now()' },
+            ]);
+        });
+        /** 同じ action でも API が違えば別件。両方直す必要があるため。 */
+        it('API が違えば別件として記録する', () => {
+            runPredicted('restart', () => {
+                Date.now();
+                Math.random();
+            });
+            expect(getPredictionWarnings()).toEqual([
+                { action: 'restart', api: 'Date.now()' },
+                { action: 'restart', api: 'Math.random()' },
+            ]);
+        });
+    });
+    describe('グローバルの復元', () => {
+        /** 先読みの外で呼ばれる API は計装されていない (描画ループが誤検知しない前提)。 */
+        it('実行後にグローバルが元へ戻る', () => {
+            const beforeNow = Date.now;
+            const beforeRandom = Math.random;
+            const beforeDate = Date;
+            runPredicted('a', () => {
+                Date.now();
+            });
+            expect(Date.now).toBe(beforeNow);
+            expect(Math.random).toBe(beforeRandom);
+            expect(Date).toBe(beforeDate);
+        });
+        /**
+         * handler が throw しても復元する。楽観実行は throw を握りつぶして
+         * サーバー送信だけ続ける経路があるので、ここで漏れるとグローバルが汚染されたまま残る。
+         */
+        it('handler が例外を投げてもグローバルが元へ戻る', () => {
+            const beforeNow = Date.now;
+            const beforeDate = Date;
+            expect(() => {
+                runPredicted('a', () => {
+                    Date.now();
+                    throw new Error('handler failed');
+                });
+            }).toThrow('handler failed');
+            expect(Date.now).toBe(beforeNow);
+            expect(Date).toBe(beforeDate);
+            // 例外で中断しても、そこまでに呼ばれた API は記録されている。
+            expect(getPredictionWarnings()).toEqual([{ action: 'a', api: 'Date.now()' }]);
+        });
+        /** 先読みの外の呼び出しは記録されない。描画コードの Date.now() を拾わない保証。 */
+        it('先読みの外で呼んだ API は記録しない', () => {
+            Date.now();
+            Math.random();
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+    });
+    describe('本番での無効化', () => {
+        /**
+         * Flutter native ホストでは計装しない。判定基準は dev hooks の attach と同じく
+         * `window.FlutterHost` の有無。
+         */
+        it('window.FlutterHost があるときは計装せず素通しする', () => {
+            window.FlutterHost = { postMessage: () => { } };
+            const beforeNow = Date.now;
+            let ran = false;
+            runPredicted('gm.timer.set', () => {
+                Date.now();
+                ran = true;
+            });
+            expect(ran).toBe(true);
+            expect(Date.now).toBe(beforeNow);
+            expect(getPredictionWarnings()).toEqual([]);
+        });
+    });
+});

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  * scenario ディレクトリで `uzu dev` を実行するだけで良い。 子 iframe は既存 online mode
  * (`?server=ws://localhost:<port>` 経路) で dev-server に接続する。
  */
-export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionHandler, ServerOnlyAction, ServerOnlyActionHandlerFn, } from './types.js';
+export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionContext, ActionHandler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
 export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { Room } from './room.js';
@@ -27,6 +27,8 @@ export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export type { JsonMergePatch, JsonPatchOp } from './dev-state-patch.js';
 export { attachDevHooks, createDevHooks } from './dev-hooks.js';
 export type { UzuDevHooks, DevHooksCtx, RunHandle, SyncHandle } from './dev-hooks.js';
+export { getPredictionWarnings } from './dev-prediction-traps.js';
+export type { PredictionWarning } from './dev-prediction-traps.js';
 import type { BridgeMessage, GameConfig, SyncConfig, PlayerVoiceState } from './types.js';
 import type { RoomLike } from './room.js';
 type GameMessageHandler = (payload: Record<string, unknown>) => void;

package/dist/index.js

@@ -5,6 +5,7 @@ export { ReconnectableWebSocket } from './reconnectable-ws.js';
 export { SeededRandomImpl } from './random.js';
 export { applyJsonMergePatch, applyJsonPatch } from './dev-state-patch.js';
 export { attachDevHooks, createDevHooks } from './dev-hooks.js';
+export { getPredictionWarnings } from './dev-prediction-traps.js';
 import { Room } from './room.js';
 import { ReconnectableWebSocket } from './reconnectable-ws.js';
 import { runOnlineServerAction } from './run/server-action.js';

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

@@ -6,9 +6,10 @@
  * ブラウザ内 LocalGameRoom — GameRoom DO の動作をサーバーレスで再現する。
  * server_url がない場合に vite dev だけで ServerAction シナリオをローカル実行する。
  *
- * online (`runOnlineServerAction`) と挙動を揃えるため、standard handler は同期で実行し
+ * online (`runOnlineServerAction`) と挙動を揃えるため、`logic.actions` は同期で実行し
  * `sendAction()` 直後に `onState()` を同期発火する (楽観的更新だけで完結する仕様)。
- * serverOnly handler のみ `await` で非同期実行し、完了後に `onState()` を呼ぶ。
+ * `logic.serverActions` は `Promise<void>` を返しうるので `await` で実行し、完了後に
+ * `onState()` を呼ぶ。同名なら actions → serverActions の順で走る (サーバーと同じ)。
  */
 import type { GameConfig } from '../types.js';
 import type { RunHandle } from '../dev-hooks.js';

package/dist/run/local-server-action.js

@@ -24,39 +24,49 @@ export function runLocalServerAction(config) {
     let state = logic.setup(players, random);
     let tick = 0;
     const playerInputs = {};
-    // Action 処理。standard handler は同期実行で `sendAction()` 直後の同期 onState を
-    // 保証する (online の楽観的更新と同じ挙動)。serverOnly handler は `Promise<void>`
-    // を返しうるので `await` で実行し、完了後に events と onState を発火する。
+    // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する
+    // (online の楽観的更新と同じ挙動)。`serverActions` は `Promise<void>` を返しうるので
+    // `await` で実行し、完了後に events と onState を発火する。
     // どちらも 1 回しか実行しない (online の「楽観 → サーバー確定」の 2 段階は再現しない)。
     const dispatchAction = (type, payload) => {
-        const handler = logic.actions[type];
-        if (!handler)
+        const plain = logic.actions[type];
+        // 移行期: 旧 serverOnly() を actions に入れたままの logic も動かす。
+        const legacyServerOnly = isServerOnlyAction(plain) ? plain : null;
+        const server = logic.serverActions?.[type] ?? legacyServerOnly;
+        if (!plain && !server)
             return;
-        const actionEvents = [];
-        const actionEmit = (name, data) => actionEvents.push({ name, data: data ?? {} });
-        if (isServerOnlyAction(handler)) {
-            void (async () => {
-                try {
-                    await handler(state, payload ?? {}, myId, actionEmit, { tick });
-                }
-                catch (err) {
-                    console.warn('[SDK LocalServerAction] Action error:', err);
-                    return;
-                }
-                dispatchEvents(actionEvents);
-                onState(state, myId);
-            })();
-            return;
-        }
-        try {
-            handler(state, payload ?? {}, myId, actionEmit, { tick });
+        // events は emit 元ごとに分ける。online では actions 由来がクライアント先読みの
+        // 時点で発火するので、ここでも plain の実行直後に流す。共有すると serverActions が
+        // `await fetch()` を持つ場合に actions 側の events までその分遅れてしまい、
+        // 「ローカルモードだけ音が遅れる」というモード差になる。
+        const plainEvents = [];
+        const serverEvents = [];
+        const plainEmit = (name, data) => plainEvents.push({ name, data: data ?? {} });
+        const serverEmit = (name, data) => serverEvents.push({ name, data: data ?? {} });
+        if (plain && !legacyServerOnly) {
+            try {
+                plain(state, payload ?? {}, myId, plainEmit, {});
+            }
+            catch (err) {
+                console.warn('[SDK LocalServerAction] Action error:', err);
+                return;
+            }
+            dispatchEvents(plainEvents);
+            onState(state, myId);
         }
-        catch (err) {
-            console.warn('[SDK LocalServerAction] Action error:', err);
+        if (!server)
             return;
-        }
-        dispatchEvents(actionEvents);
-        onState(state, myId);
+        void (async () => {
+            try {
+                await server(state, payload ?? {}, myId, serverEmit, { tick, random });
+            }
+            catch (err) {
+                console.warn('[SDK LocalServerAction] Action error:', err);
+                return;
+            }
+            dispatchEvents(serverEvents);
+            onState(state, myId);
+        })();
     };
     inputs(dispatchAction);
     onState(state, myId);

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

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

package/dist/run/local-server-action.test.js

@@ -0,0 +1,208 @@
+/**
+ * local-server-action.ts (ソロモード) の unit test。
+ *
+ * ソロモードは「クライアント = サーバー」なので `actions` と `serverActions` の
+ * 両方を 1 回ずつ実行する。online の「楽観 → サーバー確定」の 2 段階は再現しないが、
+ * **events の発火タイミングは online に揃える** 必要がある。
+ *
+ * online では actions 由来の events はクライアント先読みの時点で即座に発火する。
+ * ソロでも同じく plain の実行直後に流さないと、`serverActions` が `await fetch()` を
+ * 持つシナリオで「ソロモードだけ音が遅れる」というモード差になる。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { runLocalServerAction } from './local-server-action.js';
+import { serverOnly } from '../server-only.js';
+/** 遅延させた serverActions を持たせるための待ち。 */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const run = (logic) => {
+    const fired = [];
+    const states = [];
+    let send = () => { };
+    const config = {
+        logic,
+        playerCount: 1,
+        onState: (s) => states.push(structuredClone(s)),
+        inputs: (sendAction) => {
+            send = sendAction;
+        },
+        events: {
+            moved: () => fired.push('moved'),
+            charged: () => fired.push('charged'),
+        },
+    };
+    runLocalServerAction(config);
+    return { send: (t, p) => send(t, p), fired, states };
+};
+const baseLogic = (overrides = {}) => ({
+    setup: () => ({ moves: 0, charged: 0, rolled: -1 }),
+    actions: {},
+    update: () => { },
+    ...overrides,
+});
+describe('runLocalServerAction', () => {
+    describe('actions と serverActions の実行', () => {
+        /** actions だけの action は同期実行され、その場で state と events が確定する。 */
+        it('actions だけなら同期で state と events が確定する', () => {
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+            }));
+            h.send('move');
+            expect(h.states[h.states.length - 1].moves).toBe(1);
+            expect(h.fired).toEqual(['moved']);
+        });
+        /** serverActions だけの action は、await 完了後に state と events が反映される。 */
+        it('serverActions だけなら await 後に反映される', async () => {
+            const h = run(baseLogic({
+                serverActions: {
+                    notifyExternal: async (state, _payload, _playerId, emit) => {
+                        await tick();
+                        state.charged += 1;
+                        emit('charged');
+                    },
+                },
+            }));
+            h.send('notifyExternal');
+            expect(h.fired).toEqual([]); // まだ await 中
+            await tick();
+            await tick();
+            expect(h.states[h.states.length - 1].charged).toBe(1);
+            expect(h.fired).toEqual(['charged']);
+        });
+        /**
+         * 同名で両方定義されている場合、サーバーと同じく actions → serverActions の順で走る。
+         * serverActions は actions が書いた結果を見られる。
+         */
+        it('同名なら actions → serverActions の順に走る', async () => {
+            const order = [];
+            const h = run(baseLogic({
+                actions: {
+                    move: (state) => {
+                        order.push('actions');
+                        state.moves += 1;
+                    },
+                },
+                serverActions: {
+                    move: (state, _payload, _playerId, _emit, ctx) => {
+                        order.push('serverActions');
+                        // actions の結果が見えている
+                        expect(state.moves).toBe(1);
+                        state.charged += ctx.tick + 1;
+                        state.rolled = ctx.random.int(100);
+                    },
+                },
+            }));
+            h.send('move');
+            await tick();
+            expect(order).toEqual(['actions', 'serverActions']);
+            const last = h.states[h.states.length - 1];
+            expect(last.moves).toBe(1);
+            expect(last.charged).toBe(1); // tick 0 + 1
+            // ctx.random が渡っている (setup 前の -1 から変わっている)
+            expect(last.rolled).toBeGreaterThanOrEqual(0);
+        });
+    });
+    describe('events の発火タイミング', () => {
+        /**
+         * online では actions 由来の events は先読み時に即発火する。ソロでも同じタイミングで
+         * 流し、serverActions の await を待たせない。ここが揃っていないとモード差になる。
+         */
+        it('actions の events は serverActions の await を待たない', async () => {
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+                serverActions: {
+                    move: async (state, _payload, _playerId, emit) => {
+                        await tick();
+                        state.charged += 1;
+                        emit('charged');
+                    },
+                },
+            }));
+            h.send('move');
+            // serverActions がまだ await 中でも actions 側の events は出ている
+            expect(h.fired).toEqual(['moved']);
+            await tick();
+            await tick();
+            expect(h.fired).toEqual(['moved', 'charged']);
+        });
+    });
+    describe('エラー処理', () => {
+        /** actions が throw したら serverActions へ進まず、state 更新も通知しない。 */
+        it('actions が throw したら serverActions を実行しない', () => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            let serverRan = false;
+            const h = run(baseLogic({
+                actions: {
+                    move: () => {
+                        throw new Error('boom');
+                    },
+                },
+                serverActions: {
+                    move: () => {
+                        serverRan = true;
+                    },
+                },
+            }));
+            h.send('move');
+            expect(serverRan).toBe(false);
+            warn.mockRestore();
+        });
+        /** serverActions が throw しても、既に流れた actions 側の events は取り消さない。 */
+        it('serverActions が throw しても actions の events は残る', async () => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const h = run(baseLogic({
+                actions: {
+                    move: (state, _payload, _playerId, emit) => {
+                        state.moves += 1;
+                        emit('moved');
+                    },
+                },
+                serverActions: {
+                    move: () => {
+                        throw new Error('boom');
+                    },
+                },
+            }));
+            h.send('move');
+            await tick();
+            expect(h.fired).toEqual(['moved']);
+            warn.mockRestore();
+        });
+    });
+    describe('旧 serverOnly() の互換', () => {
+        /**
+         * R2 の古い logic.js は serverOnly() の brand を付けたまま actions に入っている。
+         * ソロモードでも brand を見て「先読みしない handler」として扱う。
+         */
+        it('actions に入った serverOnly() は server 側として実行される', async () => {
+            const logic = baseLogic({
+                actions: {
+                    // 新しい型では actions に serverOnly() を入れられない (それが本 PR の狙い)。
+                    // ここは「R2 に残っている古い logic.js」を再現するための意図的な型違反。
+                    // @ts-expect-error 移行期の互換挙動を検証するため
+                    legacy: serverOnly(async (state, _payload, _playerId, emit, ctx) => {
+                        await tick();
+                        state.charged += ctx.tick + 1;
+                        emit('charged');
+                    }),
+                },
+            });
+            const h = run(logic);
+            h.send('legacy');
+            expect(h.fired).toEqual([]); // 先読みされていない
+            await tick();
+            await tick();
+            expect(h.states[h.states.length - 1].charged).toBe(1);
+            expect(h.fired).toEqual(['charged']);
+        });
+    });
+});

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

@@ -8,10 +8,10 @@
  * トランスポート (WebSocket / BroadcastChannel) と上位ロジック (楽観更新 / pending
  * キュー / ack ベースの確定 / rollback) を分離し、3 モードで挙動が揃うことを実装で保証する。
  *
- * - `send(type, payload)`: standard handler は同期で先行実行し pending キューへ。
- *   serverOnly handler は skip して transport にだけ送る。
- * - `applyState(state, { ack, from, events })`: フル state を受信した時に呼ぶ。
- * - `applyDelta(patches, { ack, from, events })`: JSON Patch を受信した時に呼ぶ
+ * - `send(type, payload)`: `logic.actions` の handler を同期で先行実行し pending キューへ。
+ *   `logic.serverActions` は先読みせず transport にだけ送る。
+ * - `applyState(state, { ack, from, events, serverEvents })`: フル state を受信した時に呼ぶ。
+ * - `applyDelta(patches, { ack, from, events, serverEvents })`: JSON Patch を受信した時に呼ぶ
  *   (適用失敗時は false を返すので transport 側でフル state を再要求する)。
  * - `rollback(seq)`: `__action_error` 受信時に該当 action を pending から除去して再適用。
  * - `reset(state)`: 再接続後の state 復元用 (pending を全クリア)。
@@ -27,8 +27,13 @@ export interface ConfirmOptions {
     ack?: number;
     /** ack の送信元 player id。自分の pending と一致した時だけ events を skip する */
     from?: string;
-    /** サーバー (or 仮想サーバー) が dispatch した events */
+    /** `logic.actions` 由来の events。自分の ack なら先読み時に発火済みなので skip する */
     events?: EventEntry[];
+    /**
+     * `logic.serverActions` 由来の events。先読みでは走らないので、自分の ack でも必ず配信する。
+     * これを `events` と混ぜると、同名 action の server 側 events が重複排除で消える。
+     */
+    serverEvents?: EventEntry[];
 }
 export interface OptimisticActionClientConfig<S> {
     logic: GameLogic<S>;

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

@@ -1,5 +1,6 @@
 import { applyPatch } from '../json-patch.js';
 import { isServerOnlyAction } from '../server-only.js';
+import { runPredicted } from '../dev-prediction-traps.js';
 export function createOptimisticActionClient(config) {
     const { logic, playerId, onState, events, sendAction } = config;
     /** サーバー確定 state (楽観的更新のベース) */
@@ -32,16 +33,21 @@ export function createOptimisticActionClient(config) {
         while (i < pendingActions.length) {
             const { action, payload } = pendingActions[i];
             const handler = logic.actions[action];
-            if (!handler) {
+            // 移行期の互換: 旧 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 {
-                // tick はサーバー側でのみ正確に管理される。再適用ではサーバー tick が不明のため 0 を使う。
-                handler(displayState, payload, playerId, noopEmit, { tick: 0 });
+                runPredicted(action, () => handler(displayState, payload, playerId, noopEmit, {}));
                 i++;
             }
             catch {
+                displayState = base;
                 pendingActions.splice(i, 1);
             }
         }
@@ -51,11 +57,13 @@ export function createOptimisticActionClient(config) {
      * 自分が出した pending action が ack されたかを判定し、events 重複排除と
      * pending キューの掃除を行う。
      */
-    const handleAck = (ack, from, evts) => {
+    const handleAck = (ack, from, evts, serverEvts) => {
         const isMyAck = from === playerId && ack !== undefined && pendingActions.some((p) => p.seq === ack);
         if (!isMyAck) {
             dispatchEvents(evts);
         }
+        // serverActions 由来は先読みで走っていないので、自分の ack でも必ず配信する。
+        dispatchEvents(serverEvts);
         if (from === playerId && ack !== undefined) {
             while (pendingActions.length > 0 && pendingActions[0].seq <= ack) {
                 pendingActions.shift();
@@ -66,14 +74,18 @@ export function createOptimisticActionClient(config) {
         send(type, payload) {
             actionSeq++;
             const seq = actionSeq;
-            // serverOnly handler は先行実行を skip。pending にも積まないので、ack 受信時の
-            // isMyAck 判定で false となり、サーバー発の events が普通に emit される。
+            // 先読みするのは logic.actions だけ。serverActions は transport にだけ送り、
+            // 結果は ack (state + serverEvents) で受け取る。
             const handler = logic.actions[type];
-            if (handler && !isServerOnlyAction(handler) && displayState !== null) {
+            // callback 内では displayState の narrowing が効かないので const に退避する。
+            const target = displayState;
+            // 旧 serverOnly() が actions に残っている logic では、その handler を先読みすると
+            // サーバー専用のはずの副作用がクライアントでも走る。brand を見て弾く。
+            if (handler && !isServerOnlyAction(handler) && target !== null) {
                 try {
-                    handler(displayState, payload ?? {}, playerId, emit, { tick: 0 });
+                    runPredicted(type, () => handler(target, payload ?? {}, playerId, emit, {}));
                     pendingActions.push({ seq, action: type, payload: payload ?? {} });
-                    onState(displayState, playerId);
+                    onState(target, playerId);
                 }
                 catch {
                     // ローカル実行失敗 → 楽観的更新せずサーバーに送るだけ
@@ -82,7 +94,7 @@ export function createOptimisticActionClient(config) {
             sendAction({ action: type, payload: payload ?? {}, seq });
         },
         applyState(state, options = {}) {
-            handleAck(options.ack, options.from, options.events ?? []);
+            handleAck(options.ack, options.from, options.events ?? [], options.serverEvents ?? []);
             confirmedState = state;
             reapplyPendingActions();
         },
@@ -98,7 +110,7 @@ export function createOptimisticActionClient(config) {
             if (!ok)
                 return false;
             confirmedState = cloned;
-            handleAck(options.ack, options.from, options.events ?? []);
+            handleAck(options.ack, options.from, options.events ?? [], options.serverEvents ?? []);
             reapplyPendingActions();
             return true;
         },

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

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

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

@@ -0,0 +1,232 @@
+/**
+ * optimistic-action-client.ts の unit test。
+ *
+ * `logic.actions` (クライアント先読み + サーバーの 2 回実行) と `logic.serverActions`
+ * (サーバーのみ 1 回実行) を分離した設計が、events の重複排除と pending キューの
+ * 巻き戻しの両方で正しく閉じることを検証する。
+ *
+ * 特に重要なのは、同名 action で両方が定義されたケース。先読みで走るのは actions 側
+ * だけなので、serverActions が emit した events まで「自分の ack だから発火済み」として
+ * 捨ててしまうと、サーバー側のイベントが永久に届かなくなる。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createOptimisticActionClient } from './optimistic-action-client.js';
+import { serverOnly } from '../server-only.js';
+/** 旧 serverOnly() ブランド付き handler。actions に残っている古い logic を再現する。 */
+const legacyServerOnly = serverOnly((state) => {
+    state.charged += 1000;
+});
+const makeLogic = () => ({
+    setup: () => ({ moves: 0, charged: 0 }),
+    actions: {
+        move: (state) => {
+            state.moves += 1;
+        },
+        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, _payload, _playerId, _emit, ctx) => {
+            state.charged += ctx.tick;
+        },
+        // actions に無い名前 = 先読みされない action (旧 serverOnly 相当)
+        notifyExternal: (state) => {
+            state.charged += 100;
+        },
+    },
+    update: () => { },
+});
+/** 直近の onState 通知。tsconfig の lib が Array#at 未対応なので添字で取る。 */
+const latest = (states) => states[states.length - 1];
+const setup = () => {
+    const sent = [];
+    const fired = [];
+    const states = [];
+    const client = createOptimisticActionClient({
+        logic: makeLogic(),
+        playerId: 'me',
+        onState: (s) => states.push(structuredClone(s)),
+        events: {
+            moved: () => fired.push('moved'),
+            charged: () => fired.push('charged'),
+        },
+        sendAction: ({ action, seq }) => sent.push({ action, seq }),
+    });
+    client.reset({ moves: 0, charged: 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)).toEqual({ 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)).toEqual({ 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)).toEqual({ moves: 1, charged: 0 });
+        });
+    });
+    describe('events の重複排除', () => {
+        /**
+         * 自分が出した action の ack では、actions 由来の events は先読み時に発火済みなので
+         * skip する。二重発火すると効果音が 2 回鳴るなどの不具合になる。
+         */
+        it('自分の ack では actions 由来の events を発火しない', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            client.applyState({ moves: 1, charged: 0 }, { ack: 1, from: 'me', events: [{ name: 'moved', data: {} }] });
+            expect(fired).toEqual([]);
+        });
+        /**
+         * serverActions 由来の events は先読みで走っていないので、自分の ack でも必ず発火する。
+         * ここを events と同じ配列で送ると重複排除に巻き込まれて永久に届かなくなる。
+         */
+        it('自分の ack でも serverEvents は発火する', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            client.applyState({ moves: 1, charged: 5 }, {
+                ack: 1,
+                from: 'me',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(fired).toEqual(['charged']);
+        });
+        /** 他プレイヤーの action なら先読みしていないので、両方とも発火する。 */
+        it('他プレイヤーの ack では両方発火する', () => {
+            const { client, fired } = setup();
+            client.applyState({ moves: 1, charged: 5 }, {
+                ack: 1,
+                from: 'other',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(fired).toEqual(['moved', 'charged']);
+        });
+    });
+    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 }, { ack: 1, from: 'me' });
+            // 確定 (moves:1) + 未 ack の seq 2 を再適用 = moves:2、charged はサーバー値のまま
+            expect(latest(states)).toEqual({ 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)).toEqual({ moves: 2, charged: 0 });
+            client.rollback(1);
+            // seq 1 が消えて seq 2 だけ再適用される
+            expect(latest(states)).toEqual({ 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 }, {});
+            expect(latest(states)).toEqual({ moves: 9, charged: 9 });
+        });
+    });
+    describe('applyDelta', () => {
+        /** delta 経路でも serverEvents の扱いは applyState と揃っている。 */
+        it('自分の ack でも serverEvents を発火する', () => {
+            const { client, fired } = setup();
+            client.send('move');
+            const ok = client.applyDelta([{ op: 'replace', path: '/charged', value: 3 }], {
+                ack: 1,
+                from: 'me',
+                events: [{ name: 'moved', data: {} }],
+                serverEvents: [{ name: 'charged', data: {} }],
+            });
+            expect(ok).toBe(true);
+            expect(fired).toEqual(['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: {} }],
+                serverEvents: [{ name: 'charged', 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)).toEqual({ 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 }, {});
+            // 確定 state に move だけが再適用され、legacy の +1000 は入らない
+            expect(latest(states)).toEqual({ 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 }, {});
+            expect(latest(states)).toEqual({ moves: 1, charged: 0 });
+        });
+    });
+});

package/dist/run/server-action.js

@@ -123,9 +123,10 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
             const ack = parsed.ack;
             const from = parsed.from;
             const evts = parsed.events ?? [];
+            const serverEvts = parsed.serverEvents ?? [];
             serverSeq = parsed.seq ?? serverSeq + 1;
             requestStatePending = false;
-            client.applyState(parsed.state, { ack, from, events: evts });
+            client.applyState(parsed.state, { ack, from, events: evts, serverEvents: serverEvts });
             return;
         }
         // ─── Action 結果 (差分パッチ) ────────────────────────
@@ -133,6 +134,7 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
             const ack = parsed.ack;
             const from = parsed.from;
             const evts = parsed.events ?? [];
+            const serverEvts = parsed.serverEvents ?? [];
             const newSeq = parsed.seq ?? serverSeq + 1;
             if (newSeq !== serverSeq + 1) {
                 requestFullState();
@@ -142,6 +144,7 @@ export function runOnlineServerAction(config, gameEndpoint, roomId, seatId, seat
                 ack,
                 from,
                 events: evts,
+                serverEvents: serverEvts,
             });
             if (!ok) {
                 requestFullState();

package/dist/server-only.d.ts

@@ -3,24 +3,31 @@
  * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
  * - 開発パターン: docs/docs/uzu_code/sdk-guide/patterns.md
  *
- * serverOnly() で wrap した handler はクライアント側の楽観的更新（先行実行）を
- * スキップし、サーバー側でだけ実行される。fetch などの副作用付き処理を安全に
- * 書ける。
+ * `serverOnly()` は `logic.serverActions` に置き換わった互換 API。
+ *
+ * 新しく書くコードでは `serverActions` フィールドへ直接置く。`actions` の型からは
+ * ユニオンが外れたため、`serverOnly()` で wrap した handler を `actions` に入れることは
+ * できない (型エラーになる)。
+ *
+ * `isServerOnlyAction()` はサーバー側テンプレが残す必要がある。R2 に保存済みの古い
+ * logic.js は `serverOnly()` の brand を持ったまま `actions` に入っており、新しい
+ * テンプレと組み合わさるため、brand を見ないと先読み対象として扱ってしまう。
  */
-import type { ActionHandler, ServerOnlyAction, ServerOnlyActionHandlerFn } from './types.js';
+import type { ActionHandler, ServerActionHandler, ServerOnlyAction } from './types.js';
 /**
- * server-only action handler を作る。
+ * @deprecated `logic.serverActions` に直接書く。
  *
- * 例:
  * ```ts
- * actions: {
- *   notifyExternal: serverOnly(async (state, payload, playerId) => {
- *     await fetch('https://example.com/notify', { ... });
- *     state.notifiedAt = Date.now();
- *   }),
- * }
+ * // before
+ * actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+ * // after
+ * serverActions: { notifyExternal: async (state) => { ... } }
  * ```
  */
-export declare function serverOnly<S>(handler: ServerOnlyActionHandlerFn<S>): ServerOnlyAction<S>;
-/** handler が serverOnly() で wrap されているか判定する。 */
-export declare function isServerOnlyAction<S>(handler: ActionHandler<S> | ServerOnlyAction<S> | undefined): handler is ServerOnlyAction<S>;
+export declare function serverOnly<S>(handler: ServerActionHandler<S>): ServerOnlyAction<S>;
+/**
+ * handler が `serverOnly()` で wrap されているか判定する。
+ *
+ * 移行期の互換用。`serverActions` へ移行済みの logic では常に false になる。
+ */
+export declare function isServerOnlyAction<S>(handler: ActionHandler<S> | ServerActionHandler<S> | ServerOnlyAction<S> | undefined): handler is ServerOnlyAction<S>;

package/dist/server-only.js

@@ -1,20 +1,21 @@
 /**
- * server-only action handler を作る。
+ * @deprecated `logic.serverActions` に直接書く。
  *
- * 例:
  * ```ts
- * actions: {
- *   notifyExternal: serverOnly(async (state, payload, playerId) => {
- *     await fetch('https://example.com/notify', { ... });
- *     state.notifiedAt = Date.now();
- *   }),
- * }
+ * // before
+ * actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+ * // after
+ * serverActions: { notifyExternal: async (state) => { ... } }
  * ```
  */
 export function serverOnly(handler) {
     return Object.assign(handler, { __serverOnly: true });
 }
-/** handler が serverOnly() で wrap されているか判定する。 */
+/**
+ * handler が `serverOnly()` で wrap されているか判定する。
+ *
+ * 移行期の互換用。`serverActions` へ移行済みの logic では常に false になる。
+ */
 export function isServerOnlyAction(handler) {
     return (typeof handler === 'function' && '__serverOnly' in handler && handler.__serverOnly === true);
 }

package/dist/types.d.ts

@@ -67,14 +67,31 @@ export interface SeededRandom {
     pick<T>(array: T[]): T;
     shuffle<T>(array: T[]): T[];
 }
-export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: {
-    tick: number;
-}) => void;
-export type ServerOnlyActionHandlerFn<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: {
+/**
+ * 素の action handler の実行文脈。空なのは意図的。
+ *
+ * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
+ * 再現できない値 (tick / 実時刻 / 乱数) をここで配ると、サーバー・ソロ・dev では
+ * 本物が入るのにオンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
+ * そういう値が要る処理は `serverActions` 側に書く。
+ */
+export type ActionContext = Record<never, never>;
+/** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
+export interface ServerActionContext {
     tick: number;
-}) => Promise<void> | void;
-/** serverOnly() で wrap された handler。`__serverOnly` brand で識別する。 */
-export type ServerOnlyAction<S> = ServerOnlyActionHandlerFn<S> & {
+    random: SeededRandom;
+}
+/** @deprecated `ServerActionContext` を使う。 */
+export type ServerOnlyActionContext = ServerActionContext;
+export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ActionContext) => void;
+export type ServerActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerActionContext) => Promise<void> | void;
+/** @deprecated `ServerActionHandler` を使う。 */
+export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
+/**
+ * @deprecated `serverActions` フィールドに直接書く。
+ * `serverOnly()` で wrap された handler。`__serverOnly` brand で識別する。
+ */
+export type ServerOnlyAction<S> = ServerActionHandler<S> & {
     readonly __serverOnly: true;
 };
 export interface GameLogic<S> {
@@ -83,7 +100,22 @@ export interface GameLogic<S> {
      * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
      */
     setup(seats: Seat[], random: SeededRandom): S;
-    actions: Record<string, ActionHandler<S> | ServerOnlyAction<S>>;
+    /**
+     * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
+     *
+     * `serverActions` に同名のキーを置くと、同じ action の「サーバーだけで走る続き」に
+     * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
+     * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
+     */
+    actions: Record<string, ActionHandler<S>>;
+    /**
+     * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
+     * 再現できない処理をここに書く。async 可。
+     *
+     * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
+     * (旧 `serverOnly()` 相当) になる。
+     */
+    serverActions?: Record<string, ServerActionHandler<S>>;
     update(state: S, ctx: {
         random: SeededRandom;
         tick: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzuhq/code-sdk",
-  "version": "0.3.10",
+  "version": "0.5.0",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {