@xgamesfun/xcore 0.1.0 → 0.2.1

package/lib/server/contract.mjs

@@ -1,8 +1,8 @@
 // gf-server-v1: what a game's own server code is, as the kit reads it. This one module holds every name and number of
-// the contract between a game's `server/`, the kit (dev, publish) and games.fun's hosting (the play edge's /api/*, the
+// the contract between a game's `server/`, the kit (dev, publish) and xgames.fun's hosting (the play edge's /api/*, the
 // dispatch namespace, the platform binding env.GF). docs/SERVER.md is the person's page for it.
 //
-// Coded to games.fun's hosting contract, version gf-server-v1, and the play edge's own checks of a server's manifest.
+// Coded to xgames.fun's hosting contract, version gf-server-v1, and the play edge's own checks of a server's manifest.
 // Where that contract changes, change it here: nothing else in the kit names these values.
 //
 //   A game folder:
@@ -12,22 +12,27 @@
 //                          "routes": "/api/*", "compatibilityFlags": [] } } (§2). Without it, server/index.js is the
 //                          server when it exists, with no objects.
 //     server/ and gamesfun.json are never served; a game with a server has no files under api/ (§1).
+//     gamesfun.json        { "database": { "engine": "d1", "binding": "DB", "migrations": "server/migrations" } }: a D1
+//                          database of the game's own (xgames.fun's STORAGE.md §8.2, readDatabaseConfig below). A
+//                          database and no server of its own: xcore's stock server is the server.
 //   Requests:  <the game's origin>/api/*  → the server's fetch, the URL unchanged; every x-gf-* header removed (§4.1)
 //              (in the kit's dev server: the page's /game/api/*, sent on as /api/*)
-//   env:       env.GF          the platform (below); no other secret of games.fun's
+//   env:       env.GF          the platform (below); no other secret of xgames.fun's
 //              env.<binding>   a Durable Object namespace for each declared object, SQLite storage
 //              env.GF_GAME_ID, env.GF_SLUG, env.GF_CONTRACT   plain text
+//              env.<database.binding>   the game's D1 database, when gamesfun.json has a database (env.DB)
 //   Runtime:   Workers, compatibility date 2025-06-01; nodejs_compat only when gamesfun.json asks for it
-//   Outbound:  fetch() reaches only backend.json's origins and games.fun's (hosted; not enforced on this machine)
+//   Outbound:  fetch() reaches only backend.json's origins and xgames.fun's (hosted; not enforced on this machine)
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 export const SERVER_FORMAT = 'gf-server-v1';
 export const CONFIG_FILE = 'gamesfun.json';
 export const DEFAULT_ENTRY = 'server/index.js';
 export const SERVER_DIR = 'server';
-/** The runtime the hosted script runs on (games.fun's upload and its local parity use these). */
+/** The runtime the hosted script runs on (xgames.fun's upload and its local parity use these). */
 export const COMPATIBILITY_DATE = '2025-06-01';
 /** The only compatibility flag a game may ask for (gamesfun.json server.compatibilityFlags). */
 export const ALLOWED_FLAGS = Object.freeze(['nodejs_compat']);
@@ -36,7 +41,7 @@ export const ROUTES = '/api/*';
 export const SERVER_KEYS = Object.freeze(['main', 'objects', 'routes', 'compatibilityFlags']);
 /** One module goes up: the bundle. */
 export const BUNDLE_NAME = 'index.js';
-/** games.fun's caps for one game's server (§7: 16 modules and 5 MB in all, 8 Durable Object classes). */
+/** xgames.fun's caps for one game's server (§7: 16 modules and 5 MB in all, 8 Durable Object classes). */
 export const LIMITS = Object.freeze({
   bytes: 5 * 1024 * 1024,
   warnBytes: 1024 * 1024,
@@ -92,10 +97,20 @@ export const NODE_REFUSED = Object.freeze([
  *   scores.top(board, {limit?, offset?}) → {ok, order, writer, entries: [{rank, player, name, score, at}]}
  *   scores.best(board, player)           → {ok, entry: {rank, score, name, at} | null}
  *   scores.remove(board, player)         → {ok, removed}
- *   loot.report({round, endedAt, winners: [{wallet, place, grant?}]})    → {ok, result, vouchers} (games.fun signs it
+ *   loot.report({round, endedAt, winners: [{wallet, place, grant?}]})    → {ok, result, vouchers} (xgames.fun signs it
  *                                          with the game's host key; the keeper decides) — locally logged only
  *   loot.status()                        → {ok, host, certified, game}
  *   info()                               → {ok, contract, gameId, slug}
+ *   files.put(path, body, {type, public = false, length})  → {ok, path, bytes, url?}  (the game's project files,
+ *                                          STORAGE.md §8.6, §8.10: body a string, ArrayBuffer or byte ReadableStream, up
+ *                                          to 25 MB; a stream held to exactly its length, or up to 1 MB without; url,
+ *                                          https://<slug>.xgamesusercontent.com/<path>, when public; over the cap
+ *                                          {ok: false, code: 'full'})
+ *   files.get(path)                      → {ok, body, type, bytes, public}  (body: a ReadableStream of the bytes)
+ *   files.head(path)                     → {ok, type, bytes, public}
+ *   files.list({prefix, after, limit = 100})  → {ok, items: [{path, bytes, type, public, updatedAt}], after}
+ *   files.delete(path)                   → {ok, deleted}
+ *   files.usage()                        → {ok, bytes, files, cap}
  */
 export const GF_METHODS = Object.freeze([
   'verifyPlayer',
@@ -112,8 +127,79 @@ export const GF_METHODS = Object.freeze([
   'loot.report',
   'loot.status',
   'info',
+  'files.put',
+  'files.get',
+  'files.head',
+  'files.list',
+  'files.delete',
+  'files.usage',
 ]);
-/** The platform's per-game limits (games.fun platform/limits.mjs), the same here so a game fits both. */
+
+// ---- the game's project files: env.GF.files and the files domain (STORAGE.md §8.6–8.7) ---------------------------
+// Files the developer or the game's server writes, never players (replays, generated levels, content packs). Live:
+// the bucket xgames-files, key g/<gameId>/<path>; a public one served at https://<slug>.xgamesusercontent.com/<path>,
+// another site to the browser. On this machine: <game>/.gamesfun/dev/files/, served on a port of its own (another
+// origin, though the same site as the page's)
+// (../dev/files.mjs).
+
+/** The files' rules and caps (§8.6; the cap is Free's: Creator 10 GB, Scale 100 GB). */
+export const FILES = Object.freeze({
+  path: /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/,
+  pathChars: 512,
+  fileBytes: 25 * 1024 * 1024,
+  capBytes: 100 * 1024 * 1024,
+  listMax: 1000,
+  domain: 'xgamesusercontent.com',
+});
+
+/** A file's path, checked: letters, digits, . _ - and / between them, no . or .. part, at most 512. → null or why */
+export function filePathProblem(p) {
+  if (typeof p !== 'string' || !p) return 'A file needs a path, such as replays/2026-11-08.json.';
+  if (p.length > FILES.pathChars) return `A file's path is at most ${FILES.pathChars} characters.`;
+  if (!FILES.path.test(p)) return 'A path is letters, digits, ".", "_" and "-", with "/" between folders.';
+  if (p.split('/').some(part => part === '.' || part === '..')) return 'A path has no "." or ".." part.';
+  return null;
+}
+
+/** The types served as themselves (§8.7); anything else goes as application/octet-stream, to be downloaded. */
+const INLINE =
+  /^(image\/(png|jpeg|webp|gif|avif)|audio\/[a-z0-9.+-]+|video\/[a-z0-9.+-]+|font\/[a-z0-9.+-]+|application\/json|text\/plain)$/;
+/** How the files domain serves a file of this type. → {type, inline} */
+export function servedType(type) {
+  const t = String(type ?? '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
+  return INLINE.test(t)
+    ? { type: t === 'text/plain' ? 'text/plain; charset=utf-8' : t, inline: true }
+    : { type: 'application/octet-stream', inline: false };
+}
+const BY_EXTENSION = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  gif: 'image/gif',
+  avif: 'image/avif',
+  mp3: 'audio/mpeg',
+  ogg: 'audio/ogg',
+  wav: 'audio/wav',
+  m4a: 'audio/mp4',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  json: 'application/json',
+  txt: 'text/plain',
+};
+/** A file's type from its name, when the put names none. */
+export const fileType = p => BY_EXTENSION[/\.([a-z0-9]+)$/i.exec(p)?.[1]?.toLowerCase()] ?? 'application/octet-stream';
+
+/** Server code that calls env.GF.files (its sources, comments left out), which needs "files" in server.features. */
+export const usesFiles = code => /\bGF\s*\.\s*files\b|\bfiles\b[^;{}]*\}\s*=\s*[\w.]*\bGF\b/.test(code);
+/** The platform's per-game limits (xgames.fun platform/limits.mjs), the same here so a game fits both. */
 export const PLATFORM_LIMITS = Object.freeze({
   saves: Object.freeze({ playerChars: 128, valueBytes: 64 * 1024, keysPerPlayer: 16 }),
   scores: Object.freeze({ boards: 16, rules: 32, nameChars: 32, perPlayerEveryMs: 1000, topMax: 100 }),
@@ -123,7 +209,7 @@ export const PLATFORM_LIMITS = Object.freeze({
 export const SAVE_KEY = /^[A-Za-z0-9_.-]{1,32}$/;
 const ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 const ROUND = /^[0-9a-f]{32}$/;
-/** A loot result's shape, as games.fun checks it (platform/loot.mjs checkResult, less the owner's grant list). → null or a refusal */
+/** A loot result's shape, as xgames.fun checks it (platform/loot.mjs checkResult, less the owner's grant list). → null or a refusal */
 export function checkLootResult(r, now = Date.now()) {
   const no = (code, why) => ({ ok: false, code, why });
   if (!r || typeof r !== 'object') return no('shape', 'A result is {round, endedAt, winners}.');
@@ -143,7 +229,7 @@ export function checkLootResult(r, now = Date.now()) {
 }
 
 /**
- * Does this games.fun take server code? The contract (§6) does not say how a kit learns it, so the kit asks GET
+ * Does this xgames.fun take server code? The contract (§6) does not say how a kit learns it, so the kit asks GET
  * /api/kit/me for `server: { contracts: ['gf-server-v1'], maxBytes? }` (also read: `formats`, `contract`) and sends
  * server code only when it is there. → { ok, maxBytes } | { ok: false, why }
  */
@@ -155,17 +241,25 @@ export function studioAccepts(me) {
   if (!formats.includes(SERVER_FORMAT))
     return {
       ok: false,
-      why: `this games.fun does not take server code yet (GET /api/kit/me does not list ${SERVER_FORMAT})`,
+      why: `this xgames.fun does not take server code yet (GET /api/kit/me does not list ${SERVER_FORMAT})`,
     };
   const maxBytes = Number.isFinite(s.maxBytes) && s.maxBytes > 0 ? Math.min(s.maxBytes, LIMITS.bytes) : LIMITS.bytes;
   return { ok: true, maxBytes };
 }
 
+/**
+ * What else this xgames.fun runs for a game (STORAGE.md §8.1): GET /api/kit/me → server.features, a list that has
+ * "d1" once it makes each game a database, and "files" once env.GF.files and the files domain are live. → a Set
+ */
+export const studioFeatures = me =>
+  new Set(Array.isArray(me?.server?.features) ? me.server.features.filter(f => typeof f === 'string') : []);
+
 /**
  * The publish body's `server` field (POST /api/kit/publish), the manifest of §6.1. The module's bytes go up through
- * the same blob route as the files (POST /api/kit/publish/<id>/blobs/<sha256>), named in the answer's `missing`.
+ * the same blob route as the files (POST /api/kit/publish/<id>/blobs/<sha256>), named in the answer's `missing`; so
+ * do the database's migration files (STORAGE.md §8.3: `database: {binding, migrations: [{name, sha256, bytes}]}`).
  */
-export function publishField({ sha256, bytes, objects, compatibilityFlags, wasm = [] }) {
+export function publishField({ sha256, bytes, objects, compatibilityFlags, wasm = [], database = null }) {
   return {
     contract: SERVER_FORMAT,
     main: BUNDLE_NAME,
@@ -176,9 +270,317 @@ export function publishField({ sha256, bytes, objects, compatibilityFlags, wasm
     objects: objects.map(o => ({ class: o.class, binding: o.binding })),
     compatibilityDate: COMPATIBILITY_DATE,
     compatibilityFlags: [...compatibilityFlags],
+    ...(database?.has
+      ? {
+          database: {
+            binding: database.binding,
+            migrations: database.migrations.map(m => ({ name: m.name, sha256: m.sha256, bytes: m.bytes })),
+          },
+        }
+      : {}),
+  };
+}
+
+// ---- the game's database: gamesfun.json → database (STORAGE.md §8.2) ---------------------------------------------
+//   "database": { "engine": "d1", "binding": "DB", "migrations": "server/migrations",
+//                 "collections": { "*": {"read": "owner", "write": "owner"} } }
+// One D1 database a game, bound to its server as env.<binding>. Its tables come from the migration files, applied in
+// name order, each once; once applied a migration never changes (append only). `collections` are the rules of the
+// page's documents (gf.db, api/db/*): a game with a database and no server/ gets xcore's stock server
+// (../client/server/stock.js), which serves them from the database; a game with a server of its own serves them with
+// server/gf-docs.js (`xcore add` writes it), and publish refuses one whose server does not route api/db/.
+
+/** The keys gamesfun.json → database takes. */
+export const DATABASE_KEYS = Object.freeze(['engine', 'binding', 'migrations', 'collections']);
+export const DATABASE_DEFAULTS = Object.freeze({ engine: 'd1', binding: 'DB', migrations: 'server/migrations' });
+/** A migration's file name: four digits, then words (0001_init.sql). */
+export const MIGRATION_NAME = /^\d{4}_[a-z0-9_-]+\.sql$/;
+/**
+ * The most a request through xgames.fun's Studio may carry (§8.10): it runs on Vercel, which caps a request body at
+ * 4.5 MB. An owner's `db import --live` and `files put --live` are held to it; a bigger file goes up from the game's
+ * server (env.GF.files.put, up to 25 MB).
+ */
+export const STUDIO_BODY_BYTES = 4_500_000;
+/** xgames.fun's caps (§8.3, §8.5): 200 migrations of 1 MB each; an import of 5 MB. */
+export const DATABASE_LIMITS = Object.freeze({
+  migrations: 200,
+  migrationBytes: 1024 * 1024,
+  importBytes: 5 * 1024 * 1024,
+  // D1's longest SQL statement (developers.cloudflare.com/d1/platform/limits); each statement of a migration is held
+  // to it on its own (§8.10), so a migration may still be 1 MB of many statements
+  statementBytes: 100_000,
+});
+/** In server/database.js since 0.2.0 (its table's key): every player a space of their own; 0.1.0's had (collection, id). */
+export const OWNER_SPACES = 'PRIMARY KEY (collection, owner, id)';
+/** RULES as xcore 0.1.0 wrote it into server/database.js, untouched: anyone read every document. */
+export const OLD_DEFAULT_RULES = "export const RULES = {\n  '*': { read: 'anyone', write: 'owner' },\n};";
+/** The collections' rules when the stock server has none: each player reads and writes only their own. */
+export const DEFAULT_COLLECTIONS = Object.freeze({ '*': Object.freeze({ read: 'owner', write: 'owner' }) });
+/** What the stock server is called where a server's entry file would be named. */
+export const STOCK_ENTRY = "xcore's stock server";
+const COLLECTION = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * The database block, checked (§8.2). `objects`: the server's Durable Objects, whose bindings it must not take.
+ * → { has, engine, binding, migrationsDir, migrations: [{name, path, sha256, bytes, data, text}], collections, problems,
+ * warnings }. `has` is false without a block.
+ */
+export async function readDatabaseConfig(dir, config, { objects = [], own = false } = {}) {
+  const problems = [],
+    warnings = [];
+  const d = config?.database;
+  const none = { has: false, binding: null, migrations: [], collections: null, problems, warnings };
+  if (d === undefined) return none;
+  if (d === null || typeof d !== 'object' || Array.isArray(d)) {
+    problems.push(`${CONFIG_FILE} "database" is an object: {"engine": "d1", "binding": "DB"}`);
+    return none;
+  }
+  const extra = Object.keys(d).filter(k => !DATABASE_KEYS.includes(k));
+  if (extra.length)
+    problems.push(
+      `${CONFIG_FILE} database has ${extra.map(k => JSON.stringify(k)).join(', ')}, which it does not know (it takes ${DATABASE_KEYS.join(', ')})`,
+    );
+  const engine = d.engine ?? DATABASE_DEFAULTS.engine;
+  if (engine !== 'd1') problems.push(`${CONFIG_FILE} database.engine is "d1" (the only engine xgames.fun runs)`);
+  const binding = d.binding ?? DATABASE_DEFAULTS.binding;
+  if (typeof binding !== 'string' || !BINDING_NAME.test(binding) || reservedBinding(binding))
+    problems.push(
+      `${CONFIG_FILE} database.binding ${JSON.stringify(binding)} must be A–Z, 0–9 and _, starting with a letter, at most 32 characters, and not GF or GF_* (it is env.<binding> in the server; the default is "DB")`,
+    );
+  else if (objects.some(o => o.binding === binding))
+    problems.push(
+      `${CONFIG_FILE} database.binding ${binding} is also a Durable Object's binding (server.objects): give one of them another name`,
+    );
+  // the migrations stay inside server/, which is never a public file
+  const folder =
+    typeof d.migrations === 'string' ? d.migrations.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '') : null;
+  let migrationsDir = DATABASE_DEFAULTS.migrations;
+  if (
+    d.migrations !== undefined &&
+    (folder === null || !/^server\/[A-Za-z0-9_./-]+$/.test(folder) || folder.split('/').includes('..'))
+  )
+    problems.push(
+      `${CONFIG_FILE} database.migrations is a folder inside server/, such as "server/migrations" (server/ is never a public file)`,
+    );
+  else if (folder !== null) migrationsDir = folder;
+  const migrations = [];
+  const abs = path.join(dir, ...migrationsDir.split('/'));
+  if (existsSync(abs)) {
+    const names = (await readdir(abs, { withFileTypes: true }))
+      .filter(e => e.isFile() && !e.name.startsWith('.'))
+      .map(e => e.name)
+      .sort();
+    const seen = new Map();
+    for (const name of names) {
+      if (!MIGRATION_NAME.test(name)) {
+        if (/\.sql$/i.test(name))
+          problems.push(
+            `${migrationsDir}/${name}: a migration's name is four digits, _ and lowercase words, such as 0002_add_guilds.sql`,
+          );
+        else warnings.push(`${migrationsDir}/${name} is not a migration (NNNN_name.sql): it is left out`);
+        continue;
+      }
+      const n = name.slice(0, 4);
+      if (seen.has(n)) {
+        problems.push(`${migrationsDir}: ${seen.get(n)} and ${name} have the same number; give each its own`);
+        continue;
+      }
+      seen.set(n, name);
+      const bytes = await readFile(path.join(abs, name));
+      const empty = emptyMigration({ name, path: `${migrationsDir}/${name}`, bytes: bytes.length });
+      if (empty) problems.push(empty);
+      else if (bytes.length > DATABASE_LIMITS.migrationBytes)
+        problems.push(`${migrationsDir}/${name} is ${(bytes.length / 1048576).toFixed(1)} MB; a migration may be 1 MB`);
+      else {
+        // xgames.fun refuses it at publish (422 migration-failed), with nothing of the publish's migrations applied
+        const why = migrationStatementsProblem({ name, text: bytes.toString('utf8') });
+        if (why) problems.push(`${migrationsDir}/${name}: ${why}. xgames.fun would refuse it (migration-failed)`);
+      }
+      migrations.push({
+        name,
+        path: `${migrationsDir}/${name}`,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        bytes: bytes.length,
+        data: bytes,
+        text: bytes.toString('utf8'),
+      });
+    }
+    if (migrations.length > DATABASE_LIMITS.migrations)
+      problems.push(
+        `${migrationsDir} has ${migrations.length} migrations; a game may have ${DATABASE_LIMITS.migrations}`,
+      );
+  }
+  let collections = null;
+  if (d.collections !== undefined) {
+    if (!d.collections || typeof d.collections !== 'object' || Array.isArray(d.collections))
+      problems.push(
+        `${CONFIG_FILE} database.collections is an object: {"*": {"read": "owner", "write": "owner"}, "profiles": {"read": "anyone", "write": "owner"}}`,
+      );
+    else {
+      collections = {};
+      for (const [name, rule] of Object.entries(d.collections)) {
+        if (name !== '*' && !COLLECTION.test(name)) {
+          problems.push(
+            `${CONFIG_FILE} database.collections: ${JSON.stringify(name)} is not a collection's name (1 to 64 letters, digits, - or _; or "*")`,
+          );
+          continue;
+        }
+        const keys = rule && typeof rule === 'object' && !Array.isArray(rule) ? Object.keys(rule) : null;
+        if (
+          !keys ||
+          keys.some(k => k !== 'read' && k !== 'write') ||
+          (rule.read !== undefined && !['owner', 'anyone'].includes(rule.read)) ||
+          (rule.write !== undefined && !['owner', 'server'].includes(rule.write))
+        ) {
+          problems.push(
+            `${CONFIG_FILE} database.collections.${name} is {"read": "owner" | "anyone", "write": "owner" | "server"}`,
+          );
+          continue;
+        }
+        collections[name] = { ...(rule.read ? { read: rule.read } : {}), ...(rule.write ? { write: rule.write } : {}) };
+      }
+    }
+  }
+  return {
+    has: true,
+    engine,
+    binding: typeof binding === 'string' ? binding : DATABASE_DEFAULTS.binding,
+    migrationsDir,
+    migrations,
+    // the stock server's rules, or a server of its own's when it has them (server/gf-docs.js reads them)
+    collections: own ? collections : (collections ?? { ...DEFAULT_COLLECTIONS }),
+    problems,
+    warnings,
   };
 }
 
+/**
+ * The SQL's statements, split on semicolons outside strings, quoted names and comments, with the comments removed.
+ * → [statement text, trimmed] (empty statements dropped). An unterminated string or comment → null. With `triggers`, a
+ * trigger's BEGIN … END is one statement. Copied from xgames.fun's creator-studio/lib/game-database.mjs as it is: the
+ * query route's rule (../db.mjs queryProblem) and a migration's statements as Studio sends them to D1.
+ */
+export function sqlStatements(sql, { triggers = false } = {}) {
+  const out = [];
+  let cur = '',
+    i = 0,
+    head = [],
+    depth = 0;
+  const n = sql.length;
+  // A trigger's body (CREATE [TEMP] TRIGGER … BEGIN …; …; END) is one statement whose own statements end in `;`, read
+  // as SQLite reads it (and as ../dev/d1.mjs splitSql does): BEGIN, and a CASE inside the body, open what END closes.
+  const trigger = () =>
+    head[0] === 'CREATE' &&
+    (head[1] === 'TRIGGER' || ((head[1] === 'TEMP' || head[1] === 'TEMPORARY') && head[2] === 'TRIGGER'));
+  while (i < n) {
+    const c = sql[i],
+      d = sql[i + 1];
+    if (c === '-' && d === '-') {
+      const e = sql.indexOf('\n', i);
+      i = e < 0 ? n : e + 1;
+      cur += ' ';
+      continue;
+    }
+    if (c === '/' && d === '*') {
+      const e = sql.indexOf('*/', i + 2);
+      if (e < 0) return null;
+      i = e + 2;
+      cur += ' ';
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`' || c === '[') {
+      const close = c === '[' ? ']' : c;
+      let j = i + 1;
+      for (;;) {
+        if (j >= n) return null;
+        if (sql[j] === close) {
+          if (close !== ']' && sql[j + 1] === close) {
+            j += 2;
+            continue;
+          }
+          break;
+        }
+        j++;
+      }
+      cur += sql.slice(i, j + 1);
+      i = j + 1;
+      continue;
+    }
+    if (triggers && /[A-Za-z_]/.test(c) && !/[A-Za-z0-9_$]/.test(sql[i - 1] ?? '')) {
+      const w = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(sql.slice(i, i + 64))[0],
+        W = w.toUpperCase();
+      if (head.length < 3) head.push(W);
+      if (trigger()) {
+        if (W === 'BEGIN' || (W === 'CASE' && depth > 0)) depth++;
+        else if (W === 'END' && depth > 0) depth--;
+      }
+      cur += w;
+      i += w.length;
+      continue;
+    }
+    if (c === ';' && depth === 0) {
+      if (cur.trim()) out.push(cur.trim());
+      cur = '';
+      head = [];
+      i++;
+      continue;
+    }
+    cur += c;
+    i++;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+const clip = s => {
+  const t = s.replace(/\s+/g, ' ');
+  return t.length > 80 ? `${t.slice(0, 80)}…` : t;
+};
+/**
+ * A migration D1 cannot run as it is, in xgames.fun's words (§8.10): SQL that never ends, or a statement over D1's
+ * 100,000 bytes (UTF-8, as Studio sends it: comments left out). `m`: {name, text}. → null, or why (without an end mark)
+ */
+export function migrationStatementsProblem(m) {
+  const statements = sqlStatements(m.text, { triggers: true });
+  if (!statements) return `${m.name} has a string, a quoted name or a comment that never ends`;
+  for (const [i, st] of statements.entries()) {
+    const size = Buffer.byteLength(st);
+    if (size > DATABASE_LIMITS.statementBytes)
+      return `Statement ${i + 1} of ${m.name} (${clip(st)}) is ${size.toLocaleString('en-US')} bytes, and D1 runs at most ${DATABASE_LIMITS.statementBytes.toLocaleString('en-US')} bytes in one statement. Split it (an INSERT of many rows into several INSERTs, each under the limit)`;
+  }
+  return null;
+}
+
+/** A migration file with nothing in it (0 bytes) is refused, here as on xgames.fun. → null, or why */
+export const emptyMigration = m =>
+  m.bytes === 0
+    ? `${m.path ?? m.name} is empty (0 bytes): put the migration's statements in it, or delete the file`
+    : null;
+
+/**
+ * Do the migrations still begin with the ones already applied, each the same bytes (append only, §8.4.2)? `applied`:
+ * [{name, sha256}] in the order they were applied. → null, or {code, name, why} in plain words.
+ */
+export function migrationsChanged(migrations, applied = []) {
+  for (let i = 0; i < applied.length; i++) {
+    const was = applied[i],
+      now = migrations[i];
+    if (now?.name === was.name && now.sha256 === was.sha256) continue;
+    const there = migrations.find(m => m.name === was.name);
+    const why = !there
+      ? `${was.name} was applied to the database, and it is not there any more`
+      : there.sha256 !== was.sha256
+        ? `${was.name} changed after it was applied to the database`
+        : `${now?.name ?? 'a migration'} comes before ${was.name}, which was applied already`;
+    return {
+      code: 'migration-changed',
+      name: was.name,
+      why: `${why}. A migration is never changed once applied: put it back as it was, and make the change in a new migration after the last one`,
+    };
+  }
+  return null;
+}
+
 /**
  * The game's server settings (§2). → { has, entry (relative, posix), objects: [{class, binding}], compatibilityFlags,
  * problems, config (gamesfun.json or null) }. `has` is false for a game without server code (no gamesfun.json
@@ -205,8 +607,25 @@ export async function readServerConfig(dir) {
       `${CONFIG_FILE} "server" is an object: {"main": "server/index.js", "objects": [{"class": "Room", "binding": "ROOM"}]}`,
     );
   const srv = s && typeof s === 'object' && !Array.isArray(s) ? s : {};
-  const has = s !== undefined || existsSync(path.join(dir, DEFAULT_ENTRY));
-  if (!has) return { has: false, entry: null, objects: [], compatibilityFlags: [], problems, config };
+  const own = s !== undefined || existsSync(path.join(dir, DEFAULT_ENTRY));
+  if (!own) {
+    // a database and no server of its own: xcore's stock server serves the page's api/db/ from it
+    const database = await readDatabaseConfig(dir, config);
+    problems.push(...database.problems);
+    if (!database.has)
+      return { has: false, entry: null, objects: [], compatibilityFlags: [], problems, warnings: [], database, config };
+    return {
+      has: true,
+      stock: true,
+      entry: STOCK_ENTRY,
+      objects: [],
+      compatibilityFlags: [],
+      problems,
+      warnings: [...database.warnings],
+      database,
+      config,
+    };
+  }
   // a misspelled key (object for objects) was silently ignored, and the server went up without its Durable Objects
   const extra = srv && typeof srv === 'object' ? Object.keys(srv).filter(k => !SERVER_KEYS.includes(k)) : [];
   if (extra.length)
@@ -256,12 +675,17 @@ export async function readServerConfig(dir) {
     problems.push(
       `${CONFIG_FILE} server.compatibilityFlags may hold only ${ALLOWED_FLAGS.map(f => JSON.stringify(f)).join(', ')}`,
     );
+  const database = await readDatabaseConfig(dir, config, { objects, own: true });
+  problems.push(...database.problems);
   return {
     has: true,
+    stock: false,
     entry,
     objects,
     compatibilityFlags: Array.isArray(flags) ? [...new Set(flags.filter(f => ALLOWED_FLAGS.includes(f)))] : [],
     problems,
+    warnings: [...database.warnings],
+    database,
     config,
   };
 }