@uzuhq/code-cli 0.3.19 → 0.4.0

package/dist/dev-server/game-room.js

@@ -14,12 +14,17 @@
 import { randomUUID } from 'crypto';
 import { compare, applyJsonMergePatch, applyJsonPatch } from './json-patch.js';
 import { SeededRandomImpl } from './random.js';
+import { SCHEDULED_ACTOR } from './game-types.js';
+import { ScheduleDraft, loadQueue, popDue, saveQueue, } from './scheduler.js';
 /**
  * serverOnly() で wrap された handler かを判定する (SDK の isServerOnlyAction と同じ brand)。
  * dev-server は SDK を import できないため実装を持つ。
  */
 function isServerOnlyAction(handler) {
-    return '__serverOnly' in handler && handler.__serverOnly === true;
+    // handler は logic.actions[name] の結果なので undefined になりうる。型上は
+    // undefined を含まない (noUncheckedIndexedAccess 無効) ため tsc では気付けない。
+    // typeof ガードが無いと `'__serverOnly' in undefined` で TypeError になる。
+    return (typeof handler === 'function' && '__serverOnly' in handler && handler.__serverOnly === true);
 }
 export class GameRoom {
     logic;
@@ -80,6 +85,8 @@ export class GameRoom {
     }
     broadcastStateDelta(events, extra) {
         this.seq++;
+        // クライアントはこの値でクロックオフセットを合わせる (ctx.now の推定に使う)。
+        const serverTime = Date.now();
         const fullType = extra.ack !== undefined ? '__action_result' : '__tick';
         const deltaType = extra.ack !== undefined ? '__action_result_delta' : '__tick_delta';
         const needFull = this.prevBroadcastState === null || this.seq % GameRoom.SNAPSHOT_INTERVAL === 0;
@@ -89,6 +96,7 @@ export class GameRoom {
                 state: this.gameState,
                 events,
                 seq: this.seq,
+                serverTime,
                 ...extra,
             });
         }
@@ -99,6 +107,7 @@ export class GameRoom {
                 patches,
                 events,
                 seq: this.seq,
+                serverTime,
                 ...extra,
             });
             const fullPayload = JSON.stringify({
@@ -106,6 +115,7 @@ export class GameRoom {
                 state: this.gameState,
                 events,
                 seq: this.seq,
+                serverTime,
                 ...extra,
             });
             const data = deltaPayload.length < fullPayload.length ? deltaPayload : fullPayload;
@@ -194,10 +204,17 @@ export class GameRoom {
             return;
         const events = [];
         const emit = (name, data) => events.push({ name, data: data ?? {} });
+        // ctx.now と予約の基準時刻は同じ値にする。別々に Date.now() を呼ぶと
+        // 「schedule の戻り値 = ctx.now + after * 1000」という約束が数 ms 崩れる。
+        const tickNow = Date.now();
+        const tickDraft = new ScheduleDraft(tickNow, (a) => this.hasAction(a));
         try {
             this.logic.update(this.gameState, {
                 random: this.random,
                 tick: this.tickCount,
+                now: tickNow,
+                schedule: (o) => tickDraft.schedule(o),
+                unschedule: (k) => tickDraft.unschedule(k),
                 emit,
                 playerInputs: this.playerInputs,
             });
@@ -208,6 +225,8 @@ export class GameRoom {
             return;
         }
         this.tickCount++;
+        if (tickDraft.dirty)
+            void this.flushSchedule(tickDraft);
         this.broadcastStateDelta(events, { tick: this.tickCount });
     }
     // ─── Connection ────────────────────────────────────────
@@ -263,6 +282,7 @@ export class GameRoom {
                 state: this.gameState,
                 tick: this.tickCount,
                 seq: this.seq,
+                serverTime: Date.now(),
             });
         }
         this.maybeStartGame();
@@ -319,6 +339,7 @@ export class GameRoom {
                     state: this.gameState,
                     tick: this.tickCount,
                     seq: this.seq,
+                    serverTime: Date.now(),
                 });
             }
             return;
@@ -331,25 +352,127 @@ export class GameRoom {
         }
     }
     async dispatchAction(actionName, payload, senderId, ackSeq) {
-        const handler = this.logic.actions[actionName];
-        if (!handler) {
+        const plain = this.logic.actions[actionName];
+        // 移行期の互換: 旧 serverOnly() を actions に入れたままの logic も動かす。
+        const legacyServerOnly = isServerOnlyAction(plain) ? plain : null;
+        const serverHandler = this.logic.serverActions?.[actionName] ?? legacyServerOnly;
+        if (!plain && !serverHandler) {
             throw new Error(`Unknown action: ${actionName}`);
         }
         if (!this.gameState) {
             throw new Error('Game not started');
         }
+        // actions 由来か serverActions 由来かは区別せず 1 本のリストで送る。
+        // 先読みで発火済みかどうかの判定はクライアントが自分の記録と突き合わせて行う。
         const events = [];
         const emit = (name, data) => events.push({ name, data: data ?? {} });
-        // serverOnly handler はサーバーでしか走らないので tick を渡せる。素の handler は
-        // クライアント先読みでも同じコードが走るため、そこで再現できない値は渡さない。
-        if (isServerOnlyAction(handler)) {
-            await handler(this.gameState, payload ?? {}, senderId, emit, { tick: this.tickCount });
+        const serverEmit = emit;
+        // action は「全部成功か全部失敗か」にする。plain が state を変更したあと
+        // serverActions が throw すると、caller の catch が __action_error を返して
+        // broadcast されないまま変更が gameState に残り、次の無関係な broadcast の diff に
+        // 紛れて漏れる。クライアントは __action_error で予測を rollback するので、
+        // 巻き戻さないとサーバー真実と表示が食い違ったままになる。
+        const snapshot = structuredClone(this.gameState);
+        // actions と serverActions には同じ時刻を渡す。同一 dispatch の前半と後半で
+        // 値が変わると、片方だけを見た state が一瞬矛盾する。
+        const now = Date.now();
+        // handler 内では配列を触るだけにして、反映は dispatch 後にまとめて行う。
+        const draft = new ScheduleDraft(now, (a) => this.hasAction(a));
+        const scheduleCtx = {
+            schedule: (o) => draft.schedule(o),
+            unschedule: (k) => draft.unschedule(k),
+        };
+        try {
+            // 決定的な部分を先に走らせ、serverActions がその結果を見られるようにする。
+            if (plain && !legacyServerOnly) {
+                plain(this.gameState, payload ?? {}, senderId, emit, { now, ...scheduleCtx });
+            }
+            if (serverHandler) {
+                await serverHandler(this.gameState, payload ?? {}, senderId, serverEmit, {
+                    tick: this.tickCount,
+                    random: this.random ?? new SeededRandomImpl(this.seed),
+                    now,
+                    ...scheduleCtx,
+                });
+            }
         }
-        else {
-            handler(this.gameState, payload ?? {}, senderId, emit, {});
+        catch (err) {
+            this.gameState = snapshot;
+            throw err;
         }
+        if (draft.dirty)
+            await this.flushSchedule(draft);
         this.broadcastStateDelta(events, { ack: ackSeq, from: senderId });
     }
+    // ─── Scheduler (本番の Durable Object alarm 相当) ──────────
+    /** dev はメモリ + setTimeout。本番は storage + alarm。 */
+    scheduled = [];
+    wakeupTimer = null;
+    get schedulerStore() {
+        return {
+            get: async () => this.scheduled,
+            put: async (entries) => {
+                this.scheduled = entries;
+            },
+            setWakeup: async (at) => {
+                if (this.wakeupTimer)
+                    clearTimeout(this.wakeupTimer);
+                this.wakeupTimer = null;
+                if (at == null)
+                    return;
+                this.wakeupTimer = setTimeout(() => void this.fireDue(), Math.max(0, at - Date.now()));
+            },
+        };
+    }
+    hasAction(name) {
+        return Boolean(this.logic.actions[name] || this.logic.serverActions?.[name]);
+    }
+    /**
+     * 予約の書き込みを直列化する。
+     *
+     * tick / action / 発火処理が同時に走ると、後着が先着を上書きして予約が消える。
+     * 呼び出し順に 1 本の鎖へ並べる (play-server 版と同じ)。
+     */
+    scheduleChain = Promise.resolve();
+    queueScheduleWrite(mutate) {
+        this.scheduleChain = this.scheduleChain
+            .then(async () => {
+            const current = await loadQueue(this.schedulerStore);
+            await saveQueue(this.schedulerStore, mutate(current));
+        })
+            .catch((err) => {
+            console.error('[Scheduler] ❌ 予約の書き込みに失敗', err);
+        });
+        return this.scheduleChain;
+    }
+    flushSchedule(draft) {
+        return this.queueScheduleWrite((current) => draft.apply(current));
+    }
+    /**
+     * 期限の来た予約を実行する。本番の alarm() と同じ意味論。
+     *
+     * 失敗は握って捨てる (決定的バグでクラッシュを繰り返さない)。ログには必ず残す。
+     */
+    async fireDue() {
+        let due = [];
+        // 先に残りを確定させる。実行中に新しい予約が積まれても失われない。
+        await this.queueScheduleWrite((current) => {
+            const split = popDue(current, Date.now());
+            due = split.due;
+            return split.rest;
+        });
+        if (due.length > 0) {
+            console.log(`[Scheduler] ⏰ ${due.length} 件発火: ${due.map((e) => e.key).join(', ')}`);
+        }
+        for (const entry of due) {
+            try {
+                await this.dispatchAction(entry.action, entry.payload, SCHEDULED_ACTOR);
+            }
+            catch (err) {
+                console.error(`[Scheduler] ❌ key=${entry.key} action=${entry.action}:`, err);
+            }
+        }
+    }
     handleClose(ws) {
         const attachment = this.attachments.get(ws);
         if (!attachment)

package/dist/dev-server/game-types.js

@@ -8,4 +8,10 @@
  * SDK を直接 import できず、game-worker-template と同じく copy を持つ。
  * 3 か所いずれかを変更したら他 2 か所も同期させること。
  */
-export {};
+/**
+ * 予約から発火した action に渡る playerId。
+ *
+ * 送信者がいないので、人間の操作と区別するための定数。
+ * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
+ */
+export const SCHEDULED_ACTOR = '__scheduled';

package/dist/dev-server/scheduler.js

@@ -0,0 +1,135 @@
+/**
+ * @docs
+ * - ServerAction仕様: docs/docs/uzu_code/connection-method/arch3-authority.md
+ *
+ * サーバー権威のタイマー。
+ *
+ * これは dev-server (Node) 用のコピー。本番の Durable Object 版
+ * (play-server/src/game-worker-template/scheduler.ts) と**同一内容に保つこと**。
+ * 意味論がずれると「dev では動くが本番で止まる」という一番タチの悪い差になる。
+ *
+ * dev では alarm の代わりに setTimeout、storage の代わりにメモリを使う (SchedulerStore
+ * の実装差だけで吸収する)。
+ */
+const STORAGE_KEY = '__scheduled';
+/**
+ * 同時に持てる予約の上限。
+ *
+ * key で置き換わるので通常は増えないが、キーを動的に生成する (`narration:${i++}` 等)
+ * バグを踏むと際限なく積み上がる。その歯止め。
+ *
+ * NOTE: 値そのものに根拠は無い。マダミスの実データ (フェーズ数 + ナレーション行列で
+ * 数十件) から見て十分に余裕がある数字を置いているだけ。
+ */
+export const MAX_SCHEDULED = 256;
+/**
+ * 予約できる先の上限 (ms)。
+ *
+ * 狙いは単位の取り違え。`after: 1200 * 1000` (ms のつもり) を書くと 13.9 日後になるが、
+ * 型では防げない。ゲームは長くても数時間なので、これを超える予約は事実上バグ。
+ *
+ * NOTE: 値そのものに根拠は無い。
+ */
+export const MAX_HORIZON_MS = 24 * 60 * 60 * 1000;
+/**
+ * 1 dispatch ぶんの予約変更を溜めるバッファ。
+ *
+ * action handler の中では同期的に呼ばれるので、ここでは配列を触るだけにして、
+ * dispatch が終わってからまとめてストレージへ書き戻す (I/O を handler の外へ出す)。
+ */
+export class ScheduleDraft {
+    now;
+    knownActions;
+    added = [];
+    removed = new Set();
+    /** 予約 / 取り消しが 1 件でもあったか。無ければストレージに触らない。 */
+    dirty = false;
+    constructor(now, knownActions) {
+        this.now = now;
+        this.knownActions = knownActions;
+    }
+    schedule(options) {
+        const { key, action } = options;
+        if (options.at != null && options.after != null) {
+            throw new Error(`schedule: key=${key} — at と after は排他です`);
+        }
+        const at = options.at != null ? Number(options.at) : this.now + Number(options.after ?? 0) * 1000;
+        // IMPORTANT: 検査に引っかかったら握り潰さず throw する。
+        //
+        // 黙って捨てると、呼び出し側は予約できたつもりで戻り値を endsAt として state に入れ、
+        // タイマーが表示されたまま永久に発火しない = ゲームが静かに止まる。予約方式は
+        // 「何も起きないこと」に気づけないので、その場で失敗させるしかない。
+        // ここに来るのはバグのときだけなので、action 全体がロールバックされて構わない。
+        if (!key)
+            throw new Error('schedule: key は必須です');
+        if (!Number.isFinite(at))
+            throw new Error(`schedule: key=${key} の時刻が不正です`);
+        if (!this.knownActions(action)) {
+            throw new Error(`schedule: key=${key} の action "${action}" が logic に存在しません`);
+        }
+        if (at - this.now > MAX_HORIZON_MS) {
+            const days = ((at - this.now) / 86_400_000).toFixed(1);
+            throw new Error(`schedule: key=${key} の予約が上限 (24h) を超えています (${days} 日後)。` +
+                ' after は「秒」です。ms を渡していませんか');
+        }
+        this.removed.add(key);
+        const idx = this.added.findIndex((e) => e.key === key);
+        const entry = { key, at, action, payload: options.payload ?? {} };
+        if (idx >= 0)
+            this.added[idx] = entry;
+        else
+            this.added.push(entry);
+        this.dirty = true;
+        return at;
+    }
+    unschedule(key) {
+        this.removed.add(key);
+        const idx = this.added.findIndex((e) => e.key === key);
+        if (idx >= 0)
+            this.added.splice(idx, 1);
+        this.dirty = true;
+    }
+    /**
+     * 既存キューへ変更を適用する。key 単位で必ず 1 件に畳まれる。
+     *
+     * 上限超過は throw する。どれを捨てるかを SDK が決めると、フェーズタイマー (遠い) を
+     * 捨ててナレーション (近い) を残す、といった優先順位の判断を勝手にすることになる。
+     */
+    apply(current) {
+        const next = current.filter((e) => !this.removed.has(e.key));
+        next.push(...this.added);
+        if (next.length > MAX_SCHEDULED) {
+            throw new Error(`schedule: 予約が上限 ${MAX_SCHEDULED} 件を超えました (${next.length} 件)。` +
+                ' key を動的に生成していませんか');
+        }
+        next.sort((a, b) => a.at - b.at);
+        return next;
+    }
+}
+/** ストレージのキューを読む。 */
+export async function loadQueue(store) {
+    return (await store.get()) ?? [];
+}
+/** キューを書き戻し、最も早い 1 件へ起床時刻を張り替える。 */
+export async function saveQueue(store, entries) {
+    await store.put(entries);
+    const next = entries.length > 0 ? entries[0] : null;
+    await store.setWakeup(next ? next.at : null);
+    // 予約方式は「静かに何も起きない」ので、状態がログに出ないと調査手段が無くなる。
+    if (next) {
+        const inSec = Math.round((next.at - Date.now()) / 1000);
+        console.log(`[Scheduler] 📅 ${entries.length} 件 / 次は ${next.key} (${next.action}) ${inSec}s 後`);
+    }
+    else {
+        console.log('[Scheduler] 📭 予約なし');
+    }
+}
+/** 期限が来た予約を取り出し、残りを返す。 */
+export function popDue(entries, now) {
+    const due = [];
+    const rest = [];
+    for (const e of entries)
+        (e.at <= now ? due : rest).push(e);
+    return { due, rest };
+}
+export const SCHEDULER_STORAGE_KEY = STORAGE_KEY;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzuhq/code-cli",
-  "version": "0.3.19",
+  "version": "0.4.0",
   "description": "UZU ゲーム開発 CLI - ビルド・パブリッシュ・プロジェクト作成ツール",
   "type": "module",
   "bin": {