def-game 5.0.0 → 5.1.0-timeout.0

package/README.md

@@ -37,7 +37,50 @@ V5 は破壊的変更です。GameRule、GameEngine、TaskQueue に関する型
 - 参加・開始などもゲームの Command として扱います。
 - 旧 GameEngine の代わりに GameSimulator でコマンド列を実行します。
 
-Worker generator はこのリリースには含みません。Selfish の Worker 実装で共通部分を確認した後に追加する予定です。
+## Worker generator（5.0.1）
+
+Hono Worker、SQLite-backed Durable Object、waki.work JWT 認証、Hibernation WebSocket、保存・配信処理を生成します。GameDefinition の契約変更はありません。標準構成は timeout / Effect 実行なしです。開発版では下記の timeout オプションを追加しています。
+
+server package に `def-game.worker.json` を作ります。全パスはこの設定ファイルのディレクトリ基準です。
+
+```json
+{
+  "outputDir": "src/worker",
+  "adapter": "src/worker/game-adapter.ts",
+  "entry": "src/index.ts",
+  "wranglerConfig": "wrangler.jsonc",
+  "name": "my-game",
+  "assets": "../client/public",
+  "compatibilityDate": "2026-09-12"
+}
+```
+
+```sh
+npm install --save-dev def-game@5.0.1 wrangler @cloudflare/workers-types
+npm install hono jose
+npx def-game generate-worker --config def-game.worker.json
+npx def-game generate-worker --config def-game.worker.json --check
+```
+
+生成対象は `outputDir` 内の `index.ts`、`session.ts`、`auth.ts`、`env.ts`、`runtime/parse.ts`、`runtime/game-adapter.ts` と、`entry`、`wranglerConfig` の計8ファイルです。Hono / jose は利用側の runtime dependency で、generator 自体に実行時依存はありません。
+
+生成コードは Node.js 24.20.0、TypeScript 5.6.3、Hono 4.13.7、jose 6.2.12、Wrangler 4.131.1、`@cloudflare/workers-types` 5.20260911.1 の環境で、ビルド・型チェック・HTTP / WebSocket / Durable Object の通信テストを確認しています。
+
+ゲーム側は既存ファイルとして `adapter` を用意し、次を export します。このファイル、domain、shared は生成・上書きしません。
+
+- `gameAdapter`: 生成される `GameAdapter<State, Command, View, Error>` に適合するオブジェクト。
+- `gameAdapter.game`: ゲーム自身の GameDefinition（Effect は `never`）。
+- `parseCreate(input)` / `parseJoin(input)` / `parseCommand(input)`: 未検証入力から command を返す関数。形式不正なら null。WS の関数へ渡るのは envelope 内の command だけです。
+- `canConnect(state, actorId)`: 接続・配信を許可するかの判定。command の認可は GameDefinition が再検証します。
+- 型の export: `State`、`ActorId`（string）、`ServerMessage`、`ProtocolError`、`PublicError`、`CreateSessionResponse`、`JoinSessionResponse`。
+
+公開通信は `GameCommandRequest { requestId, command }`、`GameCommandResponse { requestId, ok, error? }`、`ViewStateEvent { viewState }`、`ProtocolErrorEvent { error }` の type で区別します。HTTP 応答は `CreateSessionResponse` / `JoinSessionResponse` の type と、成功時 `ok: true, sessionId`、失敗時 `ok: false, error` を持ちます。ProtocolError の code は `AuthenticationRequired` / `SessionNotFound` / `NotSessionMember` / `InvalidRequest` / `InternalError`。PublicError はそれとゲームエラーの union です。
+
+認証は Cookie `__token` を JWKS / ES256 / issuer / audience / exp で検証し、UUID の sub を ActorId として使います。Static Assets も認証必須。ログイン誘導・refresh は client の責務です。
+
+出力が同一なら変更しません。既存ファイルと差分がある場合は書き込み前に停止します。確認後に `--force` を付けると生成対象8ファイルだけを更新します。`--check` は欠落・差分を非ゼロ終了で報告し、ファイルを変更しません。生成ファイルは Git 管理し、修正は generator / 設定側へ戻してください。Wrangler 設定も全体が生成対象なので、独自 bindings や migrations の追加には generator の対応が必要です。
+
+CLI は dependencies、package scripts、tsconfig を書き換えません。利用側で Worker の型と Hono / jose を設定し、生成された entry を Wrangler から実行します。CLI には Node.js 20 以降が必要です。
 
 ## 開発と公開
 
@@ -50,6 +93,29 @@ npm pack
 
 開発時のテストには Node.js 20 以降を使用してください。npm test はビルドと Node 標準のシナリオテストを実行します。
 
-npm pack / npm publish の前に prepack で型チェック・ビルド・テストが実行されます。build は dist を作り直すため、削除した旧 API の生成物が混入しません。公開対象は dist、package.json、README、LICENSE です。
+npm pack / npm publish の前に prepack で型チェック・ビルド・テストが実行されます。build は dist を作り直すため、削除した旧 API の生成物が混入しません。公開対象は dist、bin、templates、package.json、README、LICENSE です。
 
 main にレビュー済みの変更を反映した後、公開する version と認証アカウントを確認し、検証済みのパッケージを npm publish で公開します。
+
+
+## Decision timeout（5.1.0-timeout.0 開発版）
+
+生成設定に `"timeout": true` を追加すると、DO Alarm と system command 配送を生成します。未指定または false なら従来の構成です。開発版は npm 未公開です。
+
+`GameAdapter<State, Command, View, Error, Effect>` に次の任意の接続点を設定します。
+
+```ts
+timeout: {
+  effect: (effect) => /* { type: "schedule", decisionId: string, deadline: number }
+                        または { type: "cancel", decisionId: string } */,
+  command: (decisionId) => /* ゲーム固有の system command */,
+}
+```
+
+ゲームは新しい decision で再利用しない ID と期限を発行します。同じ decision 内の部分完了では Effect を出しません。default action・pending actors・bot policy はゲーム側に残します。runtime は State を解釈せず、1つの現在予約を保存します。独立した複数の同時 decision のスケジューラーではありません。
+
+状態・予約・Alarm は同じ storage transaction で確定します。Alarm は保存済み予約から system command を生成し、古い発火が新しい予約を期限前に処理しないよう再予約します。domain も ID・期限を検証してください。期限を迎えた予約は成功した遷移と同じ transaction で消費し、次の予約があれば置き換えます。失敗は例外として伝播し Cloudflare の有限回の再試行に委ねます。無制限の再試行・外部 Effect の配送は含みません。
+
+このオプションで扱う Effect は timeout の予約・解除のみです。外部通知と異なり、Alarm は状態と原子的に保存するローカルな永続化処理です。外部サービス呼び出しは transaction 内に追加しないでください。
+
+実行環境の検証: Node.js 24、TypeScript 5.6、Hono 4.13、jose 6.2、Wrangler 4.131、Cloudflare Vitest plugin 1.1。標準構成・任意構成の生成一致を generator テストで確認しています。

package/bin/def-game.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { version } = require('../package.json');
+
+const help = `def-game ${version}
+Usage: def-game generate-worker --config <file.json> [--force | --check]
+
+Generate a Hono Worker, SQLite Durable Object, waki.work authentication and Wrangler config.
+--force  Replace differing output files (never edits the game adapter).
+--check  Verify generated files match without writing anything.
+Node.js 20+ is required. Set timeout: true in the config to generate decision timeout scheduling.`;
+
+function relativeImport(from, target) {
+  let value = path.relative(path.dirname(from), target).split(path.sep).join('/').replace(/\.ts$/, '.js');
+  if (!value.startsWith('.')) value = './' + value;
+  return JSON.stringify(value);
+}
+
+function main(args) {
+  if (args.length === 0 || args[0] === '--help') return console.log(help);
+  if (args[0] === '--version') return console.log(version);
+  if (Number(process.versions.node.split('.')[0]) < 20) throw new Error('Node.js 20+ is required');
+  if (args.shift() !== 'generate-worker') throw new Error('Unknown command. Use --help.');
+  let configPath;
+  let force = false;
+  let check = false;
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--config' && !configPath && args[0] && !args[0].startsWith('--')) configPath = args.shift();
+    else if (arg === '--force' && !force) force = true;
+    else if (arg === '--check' && !check) check = true;
+    else throw new Error(`Unknown or repeated option: ${arg}`);
+  }
+  if (!configPath || (force && check)) throw new Error('Provide --config and at most one of --force / --check');
+  configPath = path.resolve(configPath);
+  const root = path.dirname(configPath);
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Config must be an object');
+  const allowed = new Set(['outputDir', 'adapter', 'entry', 'wranglerConfig', 'name', 'assets', 'compatibilityDate', 'timeout']);
+  if (config.timeout !== undefined && typeof config.timeout !== 'boolean') throw new Error('timeout must be boolean');
+  for (const key of Object.keys(config)) if (!allowed.has(key)) throw new Error(`Unknown config key: ${key}`);
+  const required = (key) => {
+    if (typeof config[key] !== 'string' || !config[key].trim() || config[key].includes('\0')) throw new Error(`Invalid config: ${key}`);
+    return config[key];
+  };
+  const inside = (value) => {
+    if (path.isAbsolute(value)) throw new Error(`Path must be relative: ${value}`);
+    const resolved = path.resolve(root, value);
+    const relative = path.relative(root, resolved);
+    if (!relative || relative === '..' || relative.startsWith('..' + path.sep)) throw new Error(`Path must stay inside config directory: ${value}`);
+    // Do not follow existing symlinks when overwriting output or locating the adapter.
+    let current = root;
+    for (const part of relative.split(path.sep)) {
+      current = path.join(current, part);
+      if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) throw new Error(`Symlink is not supported: ${current}`);
+    }
+    return resolved;
+  };
+  const outputDir = inside(required('outputDir'));
+  const adapter = inside(required('adapter'));
+  if (!/\.(ts|js)$/.test(adapter) || !fs.statSync(adapter).isFile()) throw new Error('adapter must be an existing .ts or .js file');
+  const entry = inside(required('entry'));
+  if (!entry.endsWith('.ts')) throw new Error('entry must end with .ts');
+  const wrangler = inside(required('wranglerConfig'));
+  if (!wrangler.endsWith('.jsonc')) throw new Error('wranglerConfig must end with .jsonc');
+  const name = required('name');
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(name)) throw new Error('Invalid Worker name');
+  const assets = required('assets');
+  if (path.isAbsolute(assets)) throw new Error('assets must be relative to the config directory');
+  const date = required('compatibilityDate');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(Date.parse(date)) || new Date(date).toISOString().slice(0, 10) !== date) {
+    throw new Error('Invalid compatibilityDate');
+  }
+
+  const banner = `// Generated by def-game ${version}. Do not edit; change the generator or its config.\n`;
+  const files = new Map();
+  const add = (file, text) => {
+    if (files.has(file) || file === adapter || file === configPath) throw new Error(`Output path collision: ${file}`);
+    inside(path.relative(root, file));
+    files.set(file, banner + text);
+  };
+  for (const file of ['index.ts', 'session.ts', 'auth.ts', 'env.ts', 'runtime/parse.ts', 'runtime/game-adapter.ts']) {
+    const target = path.join(outputDir, file);
+    const template = config.timeout && ['session.ts', 'runtime/game-adapter.ts'].includes(file) ? path.join('timeout', file) : file;
+    const source = fs.readFileSync(path.join(__dirname, '../templates/worker', template), 'utf8');
+    add(target, source.replaceAll('__ADAPTER_IMPORT__', relativeImport(target, adapter)));
+  }
+  add(entry, `export { default, SessionDurableObject } from ${relativeImport(entry, path.join(outputDir, 'index.ts'))};\n`);
+  const fromWrangler = (target) => path.relative(path.dirname(wrangler), target).split(path.sep).join('/');
+  add(wrangler, JSON.stringify({
+    name,
+    main: fromWrangler(entry),
+    compatibility_date: date,
+    assets: { directory: fromWrangler(path.resolve(root, assets)), binding: 'ASSETS', run_worker_first: true },
+    durable_objects: { bindings: [{ name: 'SESSIONS', class_name: 'SessionDurableObject' }] },
+    migrations: [{ tag: 'v1', new_sqlite_classes: ['SessionDurableObject'] }],
+    vars: {
+      AUTH_ISSUER: 'https://auth.waki.work', AUTH_AUDIENCE: 'waki.work',
+      AUTH_JWKS_URL: 'https://auth.waki.work/.well-known/jwks.json',
+    },
+  }, null, 2) + '\n');
+
+  // Preflight every output before the first write, so conflicts cannot leave half-generated code.
+  const changed = [];
+  for (const [file, contents] of files) {
+    const exists = fs.existsSync(file);
+    if (exists && !fs.statSync(file).isFile()) throw new Error(`Output is not a file: ${file}`);
+    if (exists && fs.readFileSync(file, 'utf8') === contents) continue;
+    if (exists && !force && !check) throw new Error(`Refusing to overwrite ${file}; review the changes and use --force`);
+    changed.push([file, contents]);
+  }
+  if (check) {
+    if (changed.length) throw new Error(`Generated files differ or are missing:\n${changed.map(([file]) => path.relative(root, file)).join('\n')}`);
+    return console.log(`Verified ${files.size} generated files (def-game ${version})`);
+  }
+  for (const [file, contents] of changed) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = file + `.def-game-${process.pid}.tmp`;
+    try {
+      fs.writeFileSync(temp, contents, { flag: 'wx' });
+      fs.renameSync(temp, file);
+    } finally {
+      if (fs.existsSync(temp)) fs.unlinkSync(temp);
+    }
+  }
+  console.log(`Generated ${files.size} files; changed ${changed.length} (def-game ${version})`);
+}
+
+try { main(process.argv.slice(2)); }
+catch (error) { console.error(`def-game: ${error.message}`); process.exitCode = 1; }

package/dist/game-definition.d.ts

@@ -11,7 +11,8 @@ export type CommandContext<ActorId> = {
 };
 /**
  * 成功時は次の安定状態と副作用の宣言、失敗時はゲーム上の拒否理由を返す。
- * 実行側は成功した状態を保存してから Effect を処理する。
+ * 実行側は成功した状態を保存してから外部 Effect を処理する。
+ * 同じストレージ内の Alarm 予約などは、状態と原子的に保存できる。
  */
 export type TransitionResult<State, Effect, Error> = {
     readonly ok: true;

package/dist/game-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-definition.d.ts","sourceRoot":"","sources":["../src/game-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,IAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAC3C;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK;IACxE,0CAA0C;IAC1C,kBAAkB,IAAI,KAAK,CAAC;IAE5B;;;;OAIG;IACH,aAAa,CACT,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACjD"}
+{"version":3,"file":"game-definition.d.ts","sourceRoot":"","sources":["../src/game-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,IAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAC3C;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK;IACxE,0CAA0C;IAC1C,kBAAkB,IAAI,KAAK,CAAC;IAE5B;;;;OAIG;IACH,aAAa,CACT,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "def-game",
-  "version": "5.0.0",
+  "version": "5.1.0-timeout.0",
   "description": "Game definition contracts and an in-memory simulator for turn-based games",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,10 +17,15 @@
     "typescript": "^5.8.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MFQWKMR4/def-game.git"
+  },
+  "bin": {
+    "def-game": "bin/def-game.cjs"
   }
 }

package/templates/worker/auth.ts

@@ -0,0 +1,23 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import type { Env } from "./env.js";
+
+let cachedKeys: { url: string; keys: ReturnType<typeof createRemoteJWKSet> } | undefined;
+
+/** JWT は Worker 境界だけで扱う。署名・必須 claims を検証した sub だけを DO へ渡す。 */
+export async function authenticate(token: string | undefined, env: Env): Promise<string | null> {
+  if (!token) return null;
+  try {
+    if (cachedKeys?.url !== env.AUTH_JWKS_URL) {
+      // jose がキャッシュと未知 kid に対する再取得（cooldown 付き）を扱う。
+      cachedKeys = { url: env.AUTH_JWKS_URL, keys: createRemoteJWKSet(new URL(env.AUTH_JWKS_URL)) };
+    }
+    const { payload } = await jwtVerify(token, cachedKeys.keys, {
+      issuer: env.AUTH_ISSUER, audience: env.AUTH_AUDIENCE,
+      algorithms: ["ES256"], requiredClaims: ["sub", "exp", "iat"],
+    });
+    return typeof payload.sub === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(payload.sub)
+      ? payload.sub : null;
+  } catch {
+    return null;
+  }
+}

package/templates/worker/env.ts

@@ -0,0 +1,9 @@
+import type { SessionDurableObject } from "./session.js";
+
+export interface Env {
+  SESSIONS: DurableObjectNamespace<SessionDurableObject>;
+  ASSETS: Fetcher;
+  AUTH_ISSUER: string;
+  AUTH_AUDIENCE: string;
+  AUTH_JWKS_URL: string;
+}

package/templates/worker/index.ts

@@ -0,0 +1,84 @@
+import { Hono, type Context } from "hono";
+import { getCookie } from "hono/cookie";
+import type { ActorId, CreateSessionResponse, JoinSessionResponse, ProtocolError, PublicError } from __ADAPTER_IMPORT__;
+import type { Env } from "./env.js";
+import { authenticate } from "./auth.js";
+export { SessionDurableObject } from "./session.js";
+
+type AppEnv = { Bindings: Env; Variables: { actorId: ActorId } };
+const app = new Hono<AppEnv>();
+
+// Static Assets を含む全ルートで認証し、以後は検証済み ActorId を context から取得する。
+app.use("*", async (c, next) => {
+  const actorId = await authenticate(getCookie(c, "__token"), c.env);
+  if (!actorId) return errorResponse(c, "AuthenticationRequired", 401);
+  c.set("actorId", actorId);
+  await next();
+});
+
+app.use("*", async (c, next) => {
+  const origin = c.req.header("origin");
+  const isWebSocket = c.req.path.startsWith("/ws/");
+  if (origin && origin !== new URL(c.req.url).origin && (c.req.method !== "GET" || isWebSocket)) {
+    return errorResponse(c, "InvalidRequest", 403);
+  }
+  await next();
+});
+
+app.post("/api/sessions", (c) => joinSession(c, c.env.SESSIONS.newUniqueId(), "create"));
+
+app.post("/api/sessions/:sessionId/join", (c) => {
+  const sessionId = c.req.param("sessionId");
+  if (!/^[0-9a-f]{64}$/.test(sessionId)) return errorResponse(c, "InvalidRequest", 404);
+  return joinSession(c, c.env.SESSIONS.idFromString(sessionId), "join");
+});
+
+app.get("/ws/:sessionId", (c) => {
+  const sessionId = c.req.param("sessionId");
+  if (!/^[0-9a-f]{64}$/.test(sessionId)) return errorResponse(c, "InvalidRequest", 404);
+  if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return errorResponse(c, "InvalidRequest", 426);
+  const id = c.env.SESSIONS.idFromString(sessionId);
+  // DO の Hibernation 接続をそのまま返す。token や外部のヘッダーは転送しない。
+  return c.env.SESSIONS.get(id).fetch(new Request("https://session/connect", {
+    headers: { upgrade: "websocket", "x-actor-id": c.get("actorId") },
+  }));
+});
+
+app.all("/api/*", (c) => errorResponse(c, "InvalidRequest", 404));
+app.all("/ws/*", (c) => errorResponse(c, "InvalidRequest", 404));
+app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));
+
+app.onError((_error, c) => {
+  console.error("Worker request failed");
+  return errorResponse(c, "InternalError", 500);
+});
+
+export default app;
+
+/** create と join に共通する本文検証と DO 呼び出し。本文のゲーム固有形式と参加可否は DO 内の adapter / domain が判断する。 */
+async function joinSession(c: Context<AppEnv>, id: DurableObjectId, operation: "create" | "join"): Promise<Response> {
+  if (!c.req.header("content-type")?.startsWith("application/json")) return errorResponse(c, "InvalidRequest", 400);
+  const raw = await c.req.text();
+  if (raw.length > 64 * 1024) return errorResponse(c, "InvalidRequest", 400);
+  let body: unknown;
+  try { body = JSON.parse(raw); } catch { return errorResponse(c, "InvalidRequest", 400); }
+
+  const result = await c.env.SESSIONS.get(id).fetch(new Request(`https://session/${operation}`, {
+    method: "POST", headers: { "x-actor-id": c.get("actorId"), "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }));
+  const data = await result.json<{ ok: true } | { ok: false; error: PublicError }>();
+  const type = operation === "create" ? "CreateSessionResponse" : "JoinSessionResponse";
+  const response: CreateSessionResponse | JoinSessionResponse = data.ok
+    ? { type, ok: true, sessionId: id.toString() }
+    : { type, ok: false, error: data.error };
+  return Response.json(response, { status: result.status });
+}
+
+/** middleware で拒否する場合も、既存の公開レスポンス形式を維持する。 */
+function errorResponse(c: Context<AppEnv>, code: ProtocolError["code"], status: 400 | 401 | 403 | 404 | 426 | 500): Response {
+  const type = c.req.method === "POST" && c.req.path === "/api/sessions"
+    ? "CreateSessionResponse"
+    : /^\/api\/sessions\/[0-9a-f]{64}\/join$/.test(c.req.path) ? "JoinSessionResponse" : undefined;
+  return c.json({ ...(type ? { type } : {}), ok: false, error: { code } }, status);
+}

package/templates/worker/runtime/game-adapter.ts

@@ -0,0 +1,15 @@
+import type { GameDefinition } from "def-game";
+
+/**
+ * 生成対象の runtime とゲーム固有コードの接続契約。GameDefinition 自体は変更しない。
+ * decoder は未検証の本文からゲーム command を作り、形式不正なら null を返す。
+ * 参加・復帰の意味や認可は game.handleCommand が判断する。
+ * 現段階は Effect なし。timeout / Effect の生成オプションは実装時に別途追加する。
+ */
+export interface GameAdapter<State, Command, View, Error> {
+  readonly game: GameDefinition<State, Command, string, View, never, Error>;
+  readonly parseCreate: (input: unknown) => Command | null;
+  readonly parseJoin: (input: unknown) => Command | null;
+  readonly parseCommand: (input: unknown) => Command | null;
+  readonly canConnect: (state: State, actorId: string) => boolean;
+}

package/templates/worker/runtime/parse.ts

@@ -0,0 +1,14 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 通信 envelope だけを検証する。command の名前・payload の意味は adapter が判断する。 */
+export function parseCommandRequest(raw: string | ArrayBuffer): { requestId: string; command: unknown } | null {
+  if (typeof raw !== "string" || raw.length > 64 * 1024) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (!isRecord(value) || value.type !== "GameCommandRequest" || typeof value.requestId !== "string"
+      || value.requestId.length === 0 || value.requestId.length > 128 || !Object.hasOwn(value, "command")) return null;
+    return { requestId: value.requestId, command: value.command };
+  } catch { return null; }
+}

package/templates/worker/session.ts

@@ -0,0 +1,100 @@
+import { DurableObject } from "cloudflare:workers";
+import { gameAdapter, type State, type ServerMessage, type ProtocolError } from __ADAPTER_IMPORT__;
+import type { Env } from "./env.js";
+import { isRecord, parseCommandRequest } from "./runtime/parse.js";
+
+const STATE_KEY = "game-state";
+
+/** 生成対象の Session runtime。ゲーム固有の判断は gameAdapter だけを通して呼ぶ。 */
+export class SessionDurableObject extends DurableObject<Env> {
+  // State の独自キャッシュを持たない。再起動時にも Storage と attachment だけで復元する。
+  async fetch(request: Request): Promise<Response> {
+    return this.ctx.blockConcurrencyWhile(async () => {
+      const actorId = request.headers.get("x-actor-id");
+      const fail = (code: ProtocolError["code"], status: number) => Response.json({ ok: false, error: { code } }, { status });
+      if (!actorId) return fail("AuthenticationRequired", 401);
+      const path = new URL(request.url).pathname;
+      const stored = await this.ctx.storage.get<State>(STATE_KEY);
+      if (path === "/connect" && request.method === "GET") {
+        if (stored === undefined) return fail("SessionNotFound", 404);
+        if (!gameAdapter.canConnect(stored, actorId)) return fail("NotSessionMember", 403);
+        const viewState = gameAdapter.game.project(stored, actorId);
+        const pair = new WebSocketPair();
+        pair[1].serializeAttachment({ actorId });
+        this.ctx.acceptWebSocket(pair[1]);
+        this.send(pair[1], { type: "ViewStateEvent", viewState });
+        return new Response(null, { status: 101, webSocket: pair[0] });
+      }
+      if (request.method !== "POST" || (path !== "/create" && path !== "/join")) return fail("InvalidRequest", 400);
+      if (path === "/create" && stored !== undefined) return fail("InvalidRequest", 409);
+      if (path === "/join" && stored === undefined) return fail("SessionNotFound", 404);
+      let body: unknown;
+      try { body = await request.json(); } catch { return fail("InvalidRequest", 400); }
+      const command = path === "/create" ? gameAdapter.parseCreate(body) : gameAdapter.parseJoin(body);
+      if (command === null) return fail("InvalidRequest", 400);
+      const result = gameAdapter.game.handleCommand(stored === undefined ? gameAdapter.game.createInitialState() : stored, command, { origin: "actor", actorId });
+      if (!result.ok) return Response.json(result, { status: 409 });
+      // 作成と作成者の参加は、この1回の保存で確定する。
+      if (result.state !== stored) {
+        await this.ctx.storage.put(STATE_KEY, result.state);
+        this.broadcast(result.state);
+      }
+      return Response.json({ ok: true });
+    });
+  }
+
+  async webSocketMessage(socket: WebSocket, raw: string | ArrayBuffer): Promise<void> {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      const parsed = parseCommandRequest(raw);
+      const command = parsed ? gameAdapter.parseCommand(parsed.command) : null;
+      if (!parsed || command === null) {
+        this.send(socket, { type: "ProtocolErrorEvent", error: { code: "InvalidRequest" } });
+        return;
+      }
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        const state = await this.ctx.storage.get<State>(STATE_KEY);
+        if (state === undefined || !isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "NotSessionMember" } });
+          return;
+        }
+        const result = gameAdapter.game.handleCommand(state, command, { origin: "actor", actorId: attachment.actorId });
+        if (!result.ok) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: result.error });
+          return;
+        }
+        await this.ctx.storage.put(STATE_KEY, result.state);
+        // Effect は現在 never。実装時もこの保存の後に実行し、配送失敗で rollback しない。
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: true });
+        this.broadcast(result.state);
+      } catch {
+        console.error("Session command failed");
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "InternalError" } });
+      }
+    });
+  }
+
+  private broadcast(state: State): void {
+    for (const socket of this.ctx.getWebSockets()) {
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        if (!isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) continue;
+        this.send(socket, { type: "ViewStateEvent", viewState: gameAdapter.game.project(state, attachment.actorId) });
+      } catch {
+        console.error("Session view delivery failed");
+        this.close(socket);
+      }
+    }
+  }
+
+  private send(socket: WebSocket, message: ServerMessage): void {
+    try { socket.send(JSON.stringify(message)); } catch { this.close(socket); }
+  }
+
+  private close(socket: WebSocket): void {
+    try { socket.close(1011, "Delivery failed"); } catch { /* 切断済み。確定済みの保存結果へ影響させない。 */ }
+  }
+
+  webSocketClose(socket: WebSocket, code: number, reason: string): void { socket.close(code, reason); }
+  webSocketError(socket: WebSocket): void { socket.close(1011, "Connection error"); }
+}

package/templates/worker/timeout/runtime/game-adapter.ts

@@ -0,0 +1,18 @@
+import type { GameDefinition } from "def-game";
+
+export type TimeoutEffect =
+  | { readonly type: "schedule"; readonly decisionId: string; readonly deadline: number }
+  | { readonly type: "cancel"; readonly decisionId: string };
+
+/** Runtime never interprets State. The adapter translates game effects and timeout commands. */
+export interface GameAdapter<State, Command, View, Error, Effect = never> {
+  readonly game: GameDefinition<State, Command, string, View, Effect, Error>;
+  readonly parseCreate: (input: unknown) => Command | null;
+  readonly parseJoin: (input: unknown) => Command | null;
+  readonly parseCommand: (input: unknown) => Command | null;
+  readonly canConnect: (state: State, actorId: string) => boolean;
+  readonly timeout?: {
+    readonly effect: (effect: Effect) => TimeoutEffect;
+    readonly command: (decisionId: string) => Command;
+  };
+}

package/templates/worker/timeout/session.ts

@@ -0,0 +1,152 @@
+import { DurableObject } from "cloudflare:workers";
+import { gameAdapter, type State, type ServerMessage, type ProtocolError } from __ADAPTER_IMPORT__;
+import type { Env } from "./env.js";
+import { isRecord, parseCommandRequest } from "./runtime/parse.js";
+
+const STATE_KEY = "game-state";
+const TIMEOUT_KEY = "decision-timeout";
+type Reservation = { decisionId: string; deadline: number };
+type Success = Extract<ReturnType<typeof gameAdapter.game.handleCommand>, { ok: true }>;
+
+/** 生成対象の Session runtime。ゲーム固有の判断は gameAdapter だけを通して呼ぶ。 */
+export class SessionDurableObject extends DurableObject<Env> {
+  // State の独自キャッシュを持たない。再起動時にも Storage と attachment だけで復元する。
+  async fetch(request: Request): Promise<Response> {
+    return this.ctx.blockConcurrencyWhile(async () => {
+      const actorId = request.headers.get("x-actor-id");
+      const fail = (code: ProtocolError["code"], status: number) => Response.json({ ok: false, error: { code } }, { status });
+      if (!actorId) return fail("AuthenticationRequired", 401);
+      const path = new URL(request.url).pathname;
+      const stored = await this.ctx.storage.get<State>(STATE_KEY);
+      if (path === "/connect" && request.method === "GET") {
+        if (stored === undefined) return fail("SessionNotFound", 404);
+        if (!gameAdapter.canConnect(stored, actorId)) return fail("NotSessionMember", 403);
+        const viewState = gameAdapter.game.project(stored, actorId);
+        const pair = new WebSocketPair();
+        pair[1].serializeAttachment({ actorId });
+        this.ctx.acceptWebSocket(pair[1]);
+        this.send(pair[1], { type: "ViewStateEvent", viewState });
+        return new Response(null, { status: 101, webSocket: pair[0] });
+      }
+      if (request.method !== "POST" || (path !== "/create" && path !== "/join")) return fail("InvalidRequest", 400);
+      if (path === "/create" && stored !== undefined) return fail("InvalidRequest", 409);
+      if (path === "/join" && stored === undefined) return fail("SessionNotFound", 404);
+      let body: unknown;
+      try { body = await request.json(); } catch { return fail("InvalidRequest", 400); }
+      const command = path === "/create" ? gameAdapter.parseCreate(body) : gameAdapter.parseJoin(body);
+      if (command === null) return fail("InvalidRequest", 400);
+      const result = gameAdapter.game.handleCommand(stored === undefined ? gameAdapter.game.createInitialState() : stored, command, { origin: "actor", actorId });
+      if (!result.ok) return Response.json(result, { status: 409 });
+      // 作成と作成者の参加は、この1回の保存で確定する。
+      if (result.state !== stored || result.effects.length > 0) {
+        try { await this.commit(result); } catch { return fail("InternalError", 500); }
+        this.broadcast(result.state);
+      }
+      return Response.json({ ok: true });
+    });
+  }
+
+  async webSocketMessage(socket: WebSocket, raw: string | ArrayBuffer): Promise<void> {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      const parsed = parseCommandRequest(raw);
+      const command = parsed ? gameAdapter.parseCommand(parsed.command) : null;
+      if (!parsed || command === null) {
+        this.send(socket, { type: "ProtocolErrorEvent", error: { code: "InvalidRequest" } });
+        return;
+      }
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        const state = await this.ctx.storage.get<State>(STATE_KEY);
+        if (state === undefined || !isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "NotSessionMember" } });
+          return;
+        }
+        const result = gameAdapter.game.handleCommand(state, command, { origin: "actor", actorId: attachment.actorId });
+        if (!result.ok) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: result.error });
+          return;
+        }
+        await this.commit(result);
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: true });
+        this.broadcast(result.state);
+      } catch {
+        console.error("Session command failed");
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "InternalError" } });
+      }
+    });
+  }
+
+  /** Commit state, reservation and alarm together. No external effects inside the transaction. */
+  private async commit(result: Success, consumedDecisionId?: string): Promise<void> {
+    const effects = result.effects.map(effect => {
+      if (!gameAdapter.timeout) throw new Error("Timeout adapter required for effects");
+      return gameAdapter.timeout.effect(effect);
+    });
+    await this.ctx.storage.transaction(async txn => {
+      await txn.put(STATE_KEY, result.state);
+      if (consumedDecisionId !== undefined) {
+        const current = await txn.get<Reservation>(TIMEOUT_KEY);
+        if (current?.decisionId === consumedDecisionId) {
+          await txn.delete(TIMEOUT_KEY);
+          await txn.deleteAlarm();
+        }
+      }
+      for (const effect of effects) {
+        if (effect.type === "schedule") {
+          if (!effect.decisionId || !Number.isFinite(effect.deadline)) throw new Error("Invalid timeout reservation");
+          await txn.put(TIMEOUT_KEY, { decisionId: effect.decisionId, deadline: effect.deadline });
+          await txn.setAlarm(effect.deadline);
+        } else {
+          const current = await txn.get<Reservation>(TIMEOUT_KEY);
+          if (current?.decisionId === effect.decisionId) {
+            await txn.delete(TIMEOUT_KEY);
+            await txn.deleteAlarm();
+          }
+        }
+      }
+    });
+  }
+
+  async alarm(): Promise<void> {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      const reservation = await this.ctx.storage.get<Reservation>(TIMEOUT_KEY);
+      if (!reservation) return;
+      // An old alarm can wake after a new reservation replaced it. Never expire that decision early.
+      if (Date.now() < reservation.deadline) {
+        await this.ctx.storage.setAlarm(reservation.deadline);
+        return;
+      }
+      const state = await this.ctx.storage.get<State>(STATE_KEY);
+      if (state === undefined || !gameAdapter.timeout) throw new Error("Missing timeout state or adapter");
+      const result = gameAdapter.game.handleCommand(state, gameAdapter.timeout.command(reservation.decisionId), { origin: "system" });
+      if (!result.ok) throw new Error("Timeout command rejected");
+      // Failed commits throw so Cloudflare can retry. Delivery failure never rolls back committed state.
+      await this.commit(result, reservation.decisionId);
+      this.broadcast(result.state);
+    });
+  }
+
+  private broadcast(state: State): void {
+    for (const socket of this.ctx.getWebSockets()) {
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        if (!isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) continue;
+        this.send(socket, { type: "ViewStateEvent", viewState: gameAdapter.game.project(state, attachment.actorId) });
+      } catch {
+        console.error("Session view delivery failed");
+        this.close(socket);
+      }
+    }
+  }
+
+  private send(socket: WebSocket, message: ServerMessage): void {
+    try { socket.send(JSON.stringify(message)); } catch { this.close(socket); }
+  }
+
+  private close(socket: WebSocket): void {
+    try { socket.close(1011, "Delivery failed"); } catch { /* 切断済み。確定済みの保存結果へ影響させない。 */ }
+  }
+
+  webSocketClose(socket: WebSocket, code: number, reason: string): void { socket.close(code === 1005 || code === 1006 || code === 1015 ? 1000 : code, reason); }
+  webSocketError(socket: WebSocket): void { socket.close(1011, "Connection error"); }
+}