fd9c87c
@@ -30,6 +30,45 @@
bun run scripts/mutate-result.ts                        # break each rule in src
FORGE_APP_DATA=./data bun run src/tty.ts                # the terminal interface
```
## The bots' round: planning with TypeSafe AI
The bots have had two layers for a while — A* solves the objective, a trained
policy runs the fight — and nothing in between: every bot flipped its own coin
for a site, so five attackers arrived at two sites in ones and twos. There is
now a third layer, the round itself.
A **round plan** is one site, one shape (`stack`, `split` or `fake`), a tempo
and a save, per side. `src/plan/plan.ts` cuts it into one **job** per bot — the
site it walks to, whether it goes in first or gives the entry its beat, how far
off the site it is willing to stand, and whether it buys at all — and
`src/client/bots.ts` plays it. The fight is untouched: the policy and its
weights are exactly what they were.
Where the plan comes from depends on one environment variable:
- **No `TYPESAFE_API_KEY`** (every preview, and production until somebody sets
  one): the page plans every round itself with `localPlan`, which is
  arithmetic over the situation. Nothing is sent anywhere, and the bots are
  still a team.
- **With a key**: the page posts the round's situation — the map, the round
  number, the score, what each side can afford, and nothing about you — to
  `POST /api/plan` on this server, which puts it to
  [TypeSafe AI](https://typesafe.ai) as *typed questions*: a choice between the
  two sites, a rubric for the tempo, a yes/no for the save. The answer is
  validated back into a plan or dropped for the local one. The key is read from
  this process's environment at start-up and never reaches a page.
What is real and what is not: the plan is real — a model really answers it when
a key is set, and you can watch the call in the round's line on the HUD, which
says which side is doing what. Everything else about the game is still local:
the match, the fight, the physics and the weights all run in your browser.
`TYPESAFE_MODEL` overrides the model (the SDK's default is `jev-latest`).
Planning is rate-limited per caller and under a spend ceiling for the whole
process; over either, or on any failure, the round gets the local plan, which is
a plan and not an error.
## What is real and what is not
- **Real.** The game: WebGL2 written by hand, a fixed 64 Hz simulation, Source-style
@@ -4,6 +4,9 @@
  "workspaces": {
    "": {
      "name": "cs-engine",
      "dependencies": {
        "@typesafe-ai/sdk": "^0.6.0",
      },
      "devDependencies": {
        "@types/bun": "^1.4.2",
        "typescript": "^7.0.2",
@@ -15,6 +18,8 @@
    "@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g=="],
    "@typesafe-ai/sdk": ["@typesafe-ai/[email protected]", "", {}, "sha512-IddX+Q0XM+VagOUZFeP7wZjaO4SHMdvnh2zEBdrZZnXedWI3BNK1lKhMx3ayrkFWvVLbVcUHJy6AVZlY+e6Jaw=="],
    "@typescript/typescript-aix-ppc64": ["@typescript/[email protected]", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
    "@typescript/typescript-darwin-arm64": ["@typescript/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
@@ -11,5 +11,8 @@
  "devDependencies": {
    "@types/bun": "^1.4.2",
    "typescript": "^7.0.2"
  },
  "dependencies": {
    "@typesafe-ai/sdk": "^0.6.0"
  }
}
@@ -2,9 +2,10 @@
import { expect, test } from "bun:test";
import { PACKED, useShipped } from "./shipped.ts";
import { unpack, type Policy } from "../engine/index.ts";
import {
  applyIntent, blindness, botThink, dry, flashed, makeBrain, nextWeapon, NO_POLICY, pathTo, policy, usePolicy,
  ride, think,
  applyIntent, blindness, botBuy, botThink, dry, flashed, makeBrain, nextWeapon, NO_POLICY, pathTo, policy,
  ride, roundPlan, think, usePlan, usePolicy,
} from "./bots.ts";
import type { RoundPlan, TeamPlan } from "../plan/plan.ts";
import { grip } from "./spray.ts";
import { colOf, findPath, rowOf, walkable, worldOf } from "./level.ts";
import { dist, type Vec3 } from "../engine/index.ts";
@@ -327,3 +328,102 @@
test("a bot with bullets left plays exactly as it did: no swap, no knife", () =>
  expect(d.bot.weapon).toBe("ak47");
  expect(shots).toBeGreaterThan(0);
});
// --- the round's plan -------------------------------------------------------
const planned = (over: Partial<TeamPlan> = {}): RoundPlan => ({
  round: 1,
  source: "typesafe",
  model: "jev-1",
  t: { site: "A", shape: "stack", tempo: 2, save: false, ...over },
  ct: { site: "A", shape: "stack", tempo: 2, save: false, ...over },
});
/** A full ten-bot round, frozen on the first tick, with every brain made. */
const round = (seed = 77): ReturnType<typeof createWorld> => {
  const world = createWorld(DE_FORGE, COMPETITIVE, "you", "ct", 5, seed);
  world.match.phase = "freeze";
  return world;
};
const bots = (world: ReturnType<typeof createWorld>, team: "t" | "ct"): Player[] =>
  world.players.filter((p) => p.team === team && p !== world.me);
test("with no plan a bot is what it always was: its own coin flip, no wait", () => {
  const world = round();
  const bot = bots(world, "t")[0] as Player;
  botThink(world, bot, 1 / 64);
  expect(roundPlan(world)).toBeNull();
  expect(bot.brain?.job.role).toBe("support");
  expect(bot.brain?.job.delay).toBe(0);
  expect(["A", "B"]).toContain(bot.brain?.job.site ?? "");
});
test("a plan makes a team a team: one site between them, and one of them first", () => {
  const world = round();
  usePlan(world, planned({ site: "B" }));
  for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
  const attackers = bots(world, "t");
  expect(attackers.every((bot) => bot.brain?.job.site === "B")).toBe(true);
  expect(attackers.filter((bot) => bot.brain?.job.role === "entry")).toHaveLength(1);
  // The entry goes now and the rest give it its beat: that is the coordination.
  const entry = attackers.find((bot) => bot.brain?.job.role === "entry") as Player;
  expect(entry.brain?.job.delay).toBe(0);
  expect(attackers.some((bot) => (bot.brain?.job.delay ?? 0) > 0)).toBe(true);
});
test("a split sends the attackers to both sites at once", () => {
  const world = round();
  usePlan(world, planned({ site: "A", shape: "split" }));
  for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
  const sites = bots(world, "t").map((bot) => bot.brain?.job.site);
  expect(sites.filter((site) => site === "A").length).toBeGreaterThan(0);
  expect(sites.filter((site) => site === "B").length).toBeGreaterThan(0);
});
test("a bot waiting for its beat stands still, and goes when the beat comes", () => {
  const world = round();
  usePlan(world, planned());
  world.match.phase = "freeze";
  for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
  const waiting = bots(world, "t").find((bot) => (bot.brain?.job.delay ?? 0) > 0) as Player;
  waiting.hasBomb = false;
  world.match.phase = "live";
  world.time += 0.5;
  const held = botThink(world, waiting, 1 / 64);
  expect(held.forward).toBe(0);
  expect(held.side).toBe(0);
  // Past the wait it moves off towards the site like any other bot.
  world.time = (waiting.brain?.pushAt ?? 0) + 0.1;
  const moving = botThink(world, waiting, 1 / 64);
  expect(Math.abs(moving.forward) + Math.abs(moving.side)).toBeGreaterThan(0);
});
test("a plan that says save is a round nothing is spent on a rifle", () => {
  const world = round();
  const bot = bots(world, "t")[0] as Player;
  bot.money = 2400;
  usePlan(world, planned({ save: true }));
  botBuy(world, bot);
  expect(bot.primary).toBeNull();
  expect(bot.money).toBe(2400);
  // The same money with the same plan, on a side that is not saving: it buys.
  const spending = round(78);
  const other = bots(spending, "t")[0] as Player;
  other.money = 2400;
  usePlan(spending, planned({ save: false }));
  botBuy(spending, other);
  expect(other.money).toBeLessThan(2400);
});
test("a plan that lands mid-round re-tasks the team it was cut for", () => {
  const world = round();
  usePlan(world, planned({ site: "A" }));
  for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
  expect(bots(world, "t").every((bot) => bot.brain?.job.site === "A")).toBe(true);
  usePlan(world, planned({ site: "B" }));
  for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
  expect(bots(world, "t").every((bot) => bot.brain?.job.site === "B")).toBe(true);
  expect(roundPlan(world)?.t.site).toBe("B");
});
@@ -9,6 +9,16 @@
 * reflex is what reinforcement learning is good at: src/rl trains this policy
 * on millions of duels in the same simulation you are playing.
 *
 * Between the two there is now a third thing, and it is the round: `usePlan`
 * hands the bots a `RoundPlan` — a site, a shape, a tempo and a save for each
 * side — and `src/plan/plan.ts` cuts it into one job per bot, so five attackers
 * arrive at one site together, or at two sites in two groups, instead of each
 * flipping its own coin. Where that plan came from is not this file's business:
 * the page asks its own server, and the server asks TypeSafe AI when it has a
 * key and answers with the local plan when it has not. Bots nobody planned for
 * — the arena's, the trainer's — behave exactly as they did before, down to the
 * coin flip, because `usePlan` was never called on them.
 *
 * The weights are not in here and are not imported: they arrive as data. In a
 * browser `src/client/main.ts` downloads `weights.json` as this game's own
 * asset and calls `usePolicy` before Play is pressable; in Bun
@@ -22,6 +32,7 @@
import {
  angleDelta, clamp, dist, forward, newActivations, rng, sample,
  type Activations, type Policy, type Vec3,
} from "../engine/index.ts";
import { assign, DEFAULT_JOB, type Job, type RoundPlan } from "../plan/plan.ts";
import { colOf, findPath, rowOf, siteAt, walkable, worldOf, type Level } from "./level.ts";
import { CS_HULL } from "./movement.ts";
import { observe, OBS_SIZE, type Memory } from "./observe.ts";
@@ -58,6 +69,24 @@
export function policy(): Policy {
  return learned;
}
/**
 * Hand one world's bots the round they are playing. `main.ts` does this every
 * round: the local plan the moment the round starts, and the planned one if a
 * better one arrives while it is still that round.
 *
 * It is the world's and not this module's, unlike the policy above, because a
 * plan is one match's round and a policy is the whole game's: a plan in a
 * module would be one match's orders reaching the next match's bots, and the
 * arena's duels and the trainer's rounds — worlds nobody plans for — would be
 * playing whatever the last page happened to ask for.
 */
export function usePlan(world: World, plan: RoundPlan | null): void {
  world.plan = plan;
}
/** The round this world's bots are playing, or null when nobody planned one. */
export const roundPlan = (world: World): RoundPlan | null => world.plan;
/** The policy decides at 16 Hz and holds it, exactly as it was trained. */
const SKIP = 4;
@@ -82,7 +111,13 @@
export type BotBrain = {
  strafeUntil: number;
  suspect: Vec3 | null;
  plannedFor: string;
  site: "A" | "B";
  /** This bot's share of the round: a site, a role, a beat to wait, a spread. */
  job: Job;
  /** The plan the job was cut from, and the round it was cut for. */
  jobPlan: RoundPlan | null;
  jobRound: number;
  /** The clock the job's wait is up at. Set while the round is still frozen. */
  pushAt: number;
  reset: boolean;
  random: () => number;
  // What the policy needs to run, one set per bot so nothing is shared.
@@ -111,7 +146,8 @@
export function makeBrain(skill: number, seed: number, useLearned = true): BotBr
    goal: null, path: [], step: 0, repathAt: 0,
    targetId: null, seenAt: 0, burstUntil: 0, restUntil: 0,
    strafe: 0, strafeUntil: 0, suspect: null, plannedFor: "",
    site: "A", reset: true,
    job: DEFAULT_JOB, jobPlan: null, jobRound: -1, pushAt: 0,
    reset: true,
    random: rng(seed),
    obs: new Float32Array(OBS_SIZE),
    // Sized from the shape the game asks for rather than from a policy: a
@@ -194,9 +230,23 @@
export function ride(bot: Player, brain: BotBrain, grip: number, dt: number): vo
/** How far a bot notices an enemy at all, in units, with its eyes working. */
const SIGHT = 4000;
/**
 * A bot rich enough that a save costs it nothing buys anyway, which is what a
 * person does with a round's worth of money already in the bank.
 */
const FORCE = 5000;
/** What a bot spends its money on, roughly in the order a person would. */
export function botBuy(world: World, bot: Player): void {
  const brain = brainOf(world, bot);
  const job = jobOf(world, bot, brain);
  // The economy half of a plan: a round the side is saving is a round nothing
  // leaves the bank, so the next one is a full buy for five rather than a rifle
  // for two. Armour is still worth it to whoever can spare the change.
  if (job.save && bot.money < FORCE) {
    if (bot.armor < 100 && bot.money >= 2000) buy(world, bot, "armor");
    return;
  }
  const rich = bot.money >= 4000;
  const wants: WeaponId[] = [];
  if (rich && brain.random() < 0.15 && bot.money >= WEAPONS.awp.price + 1000) wants.push("awp");
@@ -258,11 +308,48 @@
function brainOf(world: World, bot: Player): BotBrain {
  return bot.brain;
}
/**
 * This bot's job, cut from the round's plan the first time anyone asks for it
 * after that plan arrived. A job belongs to a team and not to a bot — an entry
 * only means anything if somebody else is the support — so asking for one bot's
 * re-tasks its whole side at once, in one `assign`, and the other four find
 * theirs already waiting.
 *
 * With no plan handed in this is whatever `botThink` put there at the start of
 * the round, which is the coin flip these bots have always made. Nothing about
 * the arena or the trainer changes until somebody calls `usePlan`.
 */
function jobOf(world: World, bot: Player, brain: BotBrain): Job {
  const plan = world.plan;
  if (plan === null) return brain.job;
  // The plan itself is the stamp: a new one is a new object, and a bot holding
  // a job cut from another one is a bot with yesterday's orders.
  if (brain.jobPlan === plan && brain.jobRound === world.match.round) return brain.job;
  const mates = world.players.filter((p) => p.team === bot.team);
  const brains = mates.map((mate) => brainOf(world, mate));
  const jobs = assign(plan[bot.team], bot.team, mates.map((mate, at) => ({
    id: mate.id,
    skill: brains[at]?.skill ?? 0,
  })));
  brains.forEach((mate, at) => {
    mate.job = jobs[at] ?? DEFAULT_JOB;
    mate.jobPlan = plan;
    mate.jobRound = world.match.round;
    // The wait runs from the moment the round goes live, and the freeze time is
    // still running: `botThink` pushes this forward on every frozen tick.
    mate.pushAt = world.time + mate.job.delay;
    // A goal cut for the site this bot is no longer going to is not a goal.
    mate.plannedFor = "";
  });
  return brain.job;
}
/** Where this bot is trying to be, given what the round is doing. */
function chooseGoal(world: World, bot: Player, brain: BotBrain): Vec3 {
  const bomb = world.bomb;
  const level = world.level;
  const site = level.sites[brain.site];
  const job = brain.job;
  const site = level.sites[job.site];
  if (bot.team === "t") {
    if (bomb.state === "planted") {
      // Hold near the bomb rather than walk onto it.
@@ -270,10 +357,12 @@
function chooseGoal(world: World, bot: Player, brain: BotBrain): Vec3 {
    }
    if (bot.hasBomb) return site;
    if (bomb.state === "dropped") return bomb.pos;
    return nearby(level, brain, site, 200);
    // An entry walks onto the site; a lurker is happy five hundred units off
    // it, watching the way somebody would come. That is what a role is worth.
    return nearby(level, brain, site, job.spread * 0.8);
  }
  if (bomb.state === "planted") return bomb.pos;
  return nearby(level, brain, site, 250);
  return nearby(level, brain, site, job.spread);
}
const nearby = (level: Level, brain: BotBrain, at: Vec3, spread: number): Vec3 => {
@@ -466,7 +555,12 @@
export function botThink(world: World, bot: Player, dt: number): Input {
  const input: Input = { ...NO_INPUT };
  if (brain.reset) {
    brain.reset = false;
    brain.site = brain.random() < 0.5 ? "A" : "B";
    // The job a bot has when no round was planned for it: its own coin flip for
    // a site, no wait and the spread these bots have always used. A plan, if one
    // arrived, replaces this on the next line and for the rest of the round.
    brain.job = { ...DEFAULT_JOB, site: brain.random() < 0.5 ? "A" : "B" };
    brain.jobPlan = null;
    brain.pushAt = 0;
    brain.goal = null;
    brain.path = [];
    brain.targetId = null;
@@ -479,7 +573,12 @@
export function botThink(world: World, bot: Player, dt: number): Input {
    brain.pull = [0, 0];
    input.switchTo = bot.primary ?? bot.secondary;
  }
  const job = jobOf(world, bot, brain);
  if (world.match.phase === "freeze") {
    // Nobody moves in the freeze time, so a job's wait cannot start running
    // inside it: it is pushed along in front of the clock and starts the moment
    // the round goes live, which is the beat an entry is ahead by.
    brain.pushAt = world.time + job.delay;
    return input;
  }
@@ -532,9 +631,21 @@
export function botThink(world: World, bot: Player, dt: number): Input {
    return withBomb(world, bot, input);
  }
  // --- waiting. A support does not walk out with the entry; it gives it its
  // beat and follows. The bomb never waits — a round where the bomb stands at
  // spawn for two seconds is two seconds off the clock — and neither does a bot
  // with something in front of it, because the fight above returned already.
  if (world.time < brain.pushAt && !bot.hasBomb && world.bomb.state === "carried") {
    if (brain.suspect !== null) {
      const look = aimAt(bot, brain.suspect);
      turnTowards(bot, { yaw: look.yaw, pitch: clamp(look.pitch, -20, 20) }, brain.aimSpeed * 0.5, dt);
    }
    return withBomb(world, bot, input);
  }
  // --- moving. A path is asked for when there is none, when it runs out, when
  // it goes stale, or when the objective itself changed under the bot's feet.
  const objective = `${world.bomb.state}:${brain.site}`;
  const objective = `${world.bomb.state}:${job.site}`;
  const stale =
    brain.path.length === 0 || brain.step >= brain.path.length ||
    world.time > brain.repathAt || objective !== brain.plannedFor;
@@ -40,6 +40,7 @@
import { WEAPONS } from "./weapons.ts";
import { matchOf } from "../matchid.ts";
import { parseResult } from "../result.ts";
import { fakeStage, ORIGIN, type FakeStage } from "./stage.test-helper.ts";
import { parseSituation } from "../plan/situation.ts";
import { createWorld, type World } from "./world.ts";
/** Every frame booted here, so a stage can be asked what world it is running. */
@@ -69,7 +70,9 @@
function painted(stage: FakeStage): FakeStage {
/** A booted page, its atlas painted, and the match already started on it. */
function playing(
  options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
  options: {
    webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean; planEndpoint?: string;
  } = {},
): FakeStage {
  const stage = painted(start(fakeStage(options)));
  stage.by("play").fire("click");
@@ -1234,3 +1237,38 @@
test("the match being played is on the page: the id, the map, the link and the p
  expect(stage.by("mapname").textContent).toBe("de_forge");
  expect(stage.by("share").attributes.href).toBe(`/?match=${PASTED}&map=de_forge`);
});
// --- the round's plan -------------------------------------------------------
test("a round is planned in the page, and the bots are a team from the first tick", () => {
  const stage = playing();
  stage.step(FRAME);
  const world = worldOf(stage) as World;
  const plan = world.plan;
  expect(plan).not.toBeNull();
  expect(plan?.source).toBe("local");
  expect(plan?.round).toBe(world.match.round);
  // The call is on the screen where a round's call belongs.
  expect(world.messages[world.messages.length - 1]?.text).toContain(world.me.team.toUpperCase());
  // A page that named no endpoint asks nobody: the only post is the result.
  expect(stage.posts.filter((post) => post.url === "/api/plan")).toHaveLength(0);
});
test("a page that names a planner asks it, with the situation and nothing else", async () => {
  const stage = playing({ planEndpoint: "/api/plan" });
  stage.step(FRAME);
  const posted = stage.posts.filter((post) => post.url === "/api/plan");
  expect(posted).toHaveLength(1);
  const sent = JSON.parse(String(posted[0]?.body)) as Record<string, unknown>;
  expect(parseSituation(sent)).not.toBeNull();
  expect(sent.round).toBe(1);
  expect(Object.keys(sent).sort()).toEqual(["lastWinner", "map", "money", "round", "score"]);
  expect(JSON.stringify(sent)).not.toContain("matchId");
  // The stage answers every post with the leaderboard, which is not a plan: the
  // local plan stays in force and the round is played on it.
  await Promise.resolve();
  stage.step(FRAME);
  const world = worldOf(stage) as World;
  expect(world.plan?.source).toBe("local");
  expect(stepsRun(stage)).toBeGreaterThan(0);
});
@@ -60,21 +60,23 @@
import {
import { generateLevel, seedFrom } from "./generate.ts";
import { mapFrom, mapLink, nameOf, seedOf, type MapChoice } from "../mapname.ts";
import { matchFrom, playKey } from "../matchid.ts";
import { describe, localPlan, parsePlan, type RoundPlan } from "../plan/plan.ts";
import type { Situation } from "../plan/situation.ts";
import { DE_FORGE } from "./map.ts";
import type { Level } from "./level.ts";
import { FOV, fovFor, lookAt } from "./look.ts";
import { COMPETITIVE, SHORT, type Rules } from "./match.ts";
import { COMPETITIVE, SHORT, type Rules, type Team } from "./match.ts";
import { LAYERS, MATERIALS, TEX_SIZE } from "./materials.ts";
import { meshFor } from "./models.ts";
import { parsePacked } from "./packed.ts";
import { nextStep, type Answer } from "./pending.ts";
import { drawPreview, previewText } from "./preview.ts";
import { buildScene, createScene, SKY, type Scene } from "./scene.ts";
import { usePolicy } from "./bots.ts";
import { usePlan, usePolicy } from "./bots.ts";
import { createSpectator, cycle, follow } from "./spectate.ts";
import { buyable, WEAPONS } from "./weapons.ts";
import { buy, canBuy, priceOf, type BuyItem } from "./economy.ts";
import { createWorld, eyePos, update, type Player, type World } from "./world.ts";
import { createWorld, eyePos, say as showMessage, update, type Player, type World } from "./world.ts";
import { unpack } from "../engine/index.ts";
const TICK = 1 / 64;
@@ -328,6 +330,14 @@
export function boot(host: Host): Frame {
  // Where this game's weights are: the shell put the link in the head with the
  // content-hashed URL on it, so this is the only place the path is known.
  const weightsLink = doc.getElementById("weights") as Link | null;
  /**
   * Where this deployment plans a round, if it plans one anywhere but here: the
   * `<meta>` the shell renders for an endpoint, read by its id, so no path to
   * this server is written into this file. A page that named none — every
   * deployment without a TypeSafe key — plans every round in the browser.
   */
  const planMeta = doc.getElementById("botplan") as Link | null;
  const planEndpoint = planMeta === null ? null : planMeta.getAttribute("content");
  const resumeButton = by("resume");
  // The line in the pause panel that says what Escape just did on this browser.
  const escHint = by("esc");
@@ -851,6 +861,7 @@
export function boot(host: Host): Frame {
    pauseId.textContent = `Match ${matchId} on ${level.name}.`;
    share.setAttribute("href", `/?match=${matchId}&map=${choice}`);
    world = createWorld(level, rules, name, team, 5, seed);
    plannedRound = 0;
    posted = -1;
    loop.reset();
    controls.sensitivity = clamp(Number(sensField.value) || 2.2, 0.2, 12);
@@ -908,6 +919,75 @@
export function boot(host: Host): Frame {
    lastSound = current.time;
  }
  /**
   * The round the bots have been planned for, and whether a request for a
   * better plan is in the air. Both are per match: a new world is round one
   * again, and `planFor` below is what puts the first plan in place before the
   * first freeze time is over.
   */
  let plannedRound = 0;
  let planning = false;
  /**
   * Plan the round about to be played. The local plan goes in at once, so the
   * bots are a team from the first tick whatever happens next; then, on a
   * deployment that named an endpoint for it, the same situation is put to the
   * server, which puts it to TypeSafe AI. Whatever comes back is validated
   * (`parsePlan`) and replaces the local one, and anything else — a refusal, a
   * 500, junk, a connection that died — leaves the local plan exactly where it
   * is. Nothing here is awaited by the frame.
   */
  function planFor(current: World): void {
    const match = current.match;
    plannedRound = match.round;
    const situation: Situation = {
      map: mapFrom(current.level.name),
      round: match.round,
      score: { t: match.score.t, ct: match.score.ct },
      money: { t: teamMoney(current, "t"), ct: teamMoney(current, "ct") },
      lastWinner: match.winner,
    };
    const local = localPlan(situation);
    usePlan(current, local);
    announce(current, local);
    if (planEndpoint === null || planning) return;
    planning = true;
    void (async (): Promise<void> => {
      try {
        const response = await host.fetch(planEndpoint, {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(situation),
        });
        const plan = response.ok ? parsePlan(JSON.parse(await response.text())) : null;
        // A plan that arrived for a round that has already ended is last
        // round's plan: the bots keep the one they are playing.
        if (plan !== null && world === current && current.match.round === plan.round) {
          usePlan(current, plan);
          announce(current, plan);
        }
      } catch {
        // The local plan is already in force. A round is not lost because a
        // planner was.
      }
      planning = false;
    })();
  }
  /** What each side has to spend, per player, which is what a plan is told. */
  const teamMoney = (current: World, team: Team): number => {
    const side = current.players.filter((p) => p.team === team);
    const total = side.reduce((sum, p) => sum + p.money, 0);
    return side.length === 0 ? 0 : Math.max(0, Math.min(16_000, Math.round(total / side.length)));
  };
  /** The plan, in the words the HUD's message line shows for a few seconds. */
  const announce = (current: World, plan: RoundPlan): void => {
    // `say` in this file is the line by the leaderboard; this is the line in
    // the middle of the screen, which is where a round's call belongs.
    showMessage(current, describe(plan[current.me.team], current.me.team));
  };
  function frame(elapsed: number): void {
    frameAverage += (elapsed * 1000 - frameAverage) * 0.05;
    // One layer of the atlas per frame, and the browser has the rest of it: the
@@ -933,6 +1013,10 @@
export function boot(host: Host): Frame {
    }
    if (world === null || !running) return;
    // A round nobody has planned yet — the first of a match, or the one that
    // just started — is planned here, on the frame that noticed it.
    if (world.match.round !== plannedRound) planFor(world);
    const me = world.me;
    const [dx, dy] = controls.takeLook();
    if (me.alive && controls.locked) {
@@ -107,6 +107,9 @@
export const ORIGIN = "https://cs.example";
 */
export const WEIGHTS_URL = "/static/weights.0123456789.json";
/** The id of the meta that names where a round is planned, as the shell writes it. */
export const PLAN_ID = "botplan";
/** The committed policy document, which is the file the build copies to static/. */
const WEIGHTS_TEXT = readFileSync(join(import.meta.dir, "weights.json"), "utf8");
@@ -232,10 +235,16 @@
export function fakeStage(
    hold?: boolean;
    /** Leave the `#weights` link off the page entirely: a page that named nothing. */
    unlinked?: boolean;
    /**
     * The endpoint meta a deployment with a TypeSafe key renders: where the page
     * asks for a round to be planned. Absent is every other deployment, which
     * plans its rounds in the browser and posts nothing.
     */
    planEndpoint?: string;
  } = {},
): FakeStage {
  const page = fakePage({
    ids: PAGE_IDS,
    ids: options.planEndpoint === undefined ? PAGE_IDS : [...PAGE_IDS, PLAN_ID],
    canvases: ["scene", "hud", "plan"],
    hidden: HIDDEN,
    actions: PAGE_ACTIONS,
@@ -248,6 +257,8 @@
export function fakeStage(
  // The link the shell renders in the head, with the content-hashed URL on it.
  // `unlinked: true` leaves it blank: a page that named no weights at all.
  if (options.unlinked !== true) page.by("weights").setAttribute("href", WEIGHTS_URL);
  // And the meta the shell renders for an endpoint, when this page has one.
  if (options.planEndpoint !== undefined) page.by(PLAN_ID).setAttribute("content", options.planEndpoint);
  // The same switch on both sides of the seam: `webgl: false` is a browser with
  // no context to give, whether the frame asks this page's `host` for a renderer
  // or — as the committed bundle does — asks the canvas itself.
@@ -22,6 +22,7 @@
import {
  type Grenade, type GrenadeSound,
} from "./grenade.ts";
import type { Level } from "./level.ts";
import type { RoundPlan } from "../plan/plan.ts";
import {
  angleVectors, angleDelta, clamp, createEffects, dist, expireEffects, eyeHeight, hullHeight, move,
  normalize, pushEffect, rng, sub, visible,
@@ -173,6 +174,14 @@
export type World = {
  grenades: Grenade[];
  feed: FeedEntry[];
  messages: { at: number; text: string }[];
  /**
   * The round these bots are playing, or null when nobody planned one. It hangs
   * on the world rather than in a module because a plan is one match's: the
   * arena's duels and the trainer's rounds are worlds nobody planned for, and a
   * plan left in a module would be last match's orders arriving in this one.
   * `src/client/bots.ts` puts it here (`usePlan`) and reads it back.
   */
  plan: RoundPlan | null;
  random: () => number;
  /**
   * The map this round is played on, whole. Everything that needs to know where
@@ -252,7 +261,7 @@
export function createWorld(
  const world: World = {
    match, players, me, time: 0,
    bomb: newBomb(),
    effects: createEffects<Effect>(EFFECT_CAPACITY), grenades: [], feed: [], messages: [],
    effects: createEffects<Effect>(EFFECT_CAPACITY), grenades: [], feed: [], messages: [], plan: null,
    random, level, bombPlanted: false, pendingBuy: false,
  };
  startRound(world);
@@ -317,7 +326,12 @@
export const alive = (world: World, team: Team): Player[] =>
export const eyePos = (p: Player): Vec3 => [p.pos[0], p.pos[1], p.pos[2] + eyeHeight(p, CS_HULL)];
function say(world: World, text: string): void {
/**
 * A line in the middle of the screen for a few seconds. Exported because the
 * round's plan is announced the same way the round's start is: `src/client/main.ts`
 * says what the bots were told to do the moment they are told it.
 */
export function say(world: World, text: string): void {
  world.messages.push({ at: world.time, text });
  if (world.messages.length > 6) world.messages.shift();
}
@@ -60,6 +60,16 @@
export type Game = {
/**
 * In the order the header lists them, which is also the order they are built.
 *
 * #228 gave the bots a round to play rather than five separate ones — a site, a
 * shape, a tempo and a save per side, and a job per bot cut from it — and the
 * app grew 3,804 raw bytes for it (92,978 raw / 36,716 gzipped now): `src/plan/plan.ts` (the plan,
 * the jobs and the parser, all of which ship), the situation the page sends, and
 * the wiring in the entry that asks for one a round. It fits today's 98,000 /
 * 39,000 with 5,022 raw and 2,284 gzipped bytes to spare, so no ceiling moved.
 * The planner itself — `src/plan/typesafe.ts` and `@typesafe-ai/sdk` — is behind
 * the door like the trainer and the digest: it holds the key, it runs on the
 * server, and no bundle gained a byte of it. The range and the example are
 * unchanged to the byte: they have no bots to plan for. Measured 2026-09-21.
 * The ceilings are today's sizes plus about 10%, rounded up to a round number:
 * enough headroom that an honest feature lands without a ceiling edit, tight
 * enough that a stray import of something large trips the test. Measured
@@ -69,13 +69,20 @@
export const namedMap = (map: MapChoice): string | null =>
  map === "de_forge" || map === "generated" ? null : map;
/** What the shell needs that this page cannot know: the environment it runs in. */
export type PageOptions = Pick<ShellOptions, "env" | "pull" | "commit" | "script" | "assets" | "ssh"> & {
export type PageOptions = Pick<ShellOptions, "env" | "pull" | "commit" | "script" | "assets" | "endpoints" | "ssh"> & {
  /** The forge identity the request carried, verified in `src/who.ts`. */
  who: Who;
  /** What `/?match=…&map=…` asked for. Absent is `NOTHING_ASKED`. */
  asked?: Asked;
  /** The policy card the prose is made of. Absent is the shipped weights'. */
  card?: Card;
  /**
   * Whether this deployment plans the bots' rounds with TypeSafe AI — which is
   * whether it was given a key. It changes one sentence and one `<meta>`: with
   * no key the page never asks the server to plan anything and the bots plan
   * every round in the page, which is what the paragraph then says.
   */
  planning?: boolean;
};
/**
@@ -250,10 +257,34 @@
export const policyHtml = (card: Card): string =>
      still wins ${num(card.unseenWinRate)}% against the same bots' ${num(card.unseenBaselineWinRate)}%, which is
      what a map made the moment you press play asks of it. Its weights are about eight kilobytes
      of int8, downloaded once beside the bundle and cached under their own name — there is no
      inference server and nothing is sent anywhere. Each
      inference server and nothing about the fight is sent anywhere. Each
      bot's own skill still decides how fast it can turn, how steady its hands are and how long it
      takes to react, so there is still a ladder from fodder to uncomfortable.</p>`;
/**
 * What the page says about the layer above the fight: who decides the round.
 * Two sentences, and which second one is true is whether this deployment was
 * given a key — the page never claims a model is planning anything when the
 * only planner running is the arithmetic in the page.
 */
export const planHtml = (planning: boolean): string =>
  `<p>Above the fight the bots now plan a round rather than five separate ones. Each side gets a
      site, a shape — everyone through one site, a split across both, or a fake with a lurker on the
      other — a tempo and a decision about whether to save, and every bot gets a job cut from it:
      which site it walks to, whether it goes in first or gives the entry its beat, and how far off
      the site it is willing to stand. ${
        planning
          ? `Which round each side plays is asked of <a href="https://typesafe.ai">TypeSafe AI</a> once
      a round, as typed questions — a choice between the two sites, a rubric for the tempo, a yes or
      no for the save — and the answer is validated back into the same shape the page can play, or
      dropped for the local plan. The request is this server's, made from this server: the key is in
      this deployment's environment, nothing about you is in the question, and the fight itself never
      leaves your browser.`
          : `This deployment has no TypeSafe key, so every round is planned in your browser by the same
      arithmetic the server would use as its fallback: nothing is sent anywhere, and the plan is
      still a plan.`
      }</p>`;
/**
 * The pause panel. Its line about Escape is rendered with the sentence that is
 * true before any key has been pressed, and `src/client/main.ts` replaces it on
@@ -308,7 +339,7 @@
const SAVED_LINE = `<p class="hint" id="saved" role="status" aria-live="polite">
export function gamePage(
  db: Database,
  { who: visitor, asked = NOTHING_ASKED, card = CARD, ...options }: PageOptions,
  { who: visitor, asked = NOTHING_ASKED, card = CARD, planning = false, ...options }: PageOptions,
): string {
  return page({
    ...options,
@@ -359,6 +390,7 @@
export function gamePage(
      Everything you see is generated — the map, the textures, the models and the sounds — so the
      whole game is one small download and no asset files.</p>
    ${policyHtml(card)}
    ${planHtml(planning)}
    <p>The match runs entirely in your browser; the leaderboard here is what your browser
      reported about it, checked against what a match can produce. The name on a row is not
      the browser's word, though: signed in to the forge, your results are recorded under
@@ -160,6 +160,12 @@
export const preloads = (assets: readonly Linked[] = []): string =>
    )
    .join("");
/** The endpoint metas, in the head: one per endpoint, each read by its id. */
export const endpoints = (posts: readonly Linked[] = []): string =>
  posts
    .map((post) => `<meta name="endpoint" id="${escape(post.id)}" content="${escape(post.href)}">\n`)
    .join("");
/** One touch button: the action `src/engine/controls.ts` holds, and its label. */
export type TouchButton = { action: string; label: string };
@@ -258,6 +264,14 @@
export type PageOptions = {
   * by its id. Absent, or empty, is a page that downloads nothing but its script.
   */
  assets?: readonly Linked[];
  /**
   * The endpoints this page's game posts to, each findable by its id — the
   * same bargain as an asset, one step further: no path to this server is ever
   * written into a client. A `<meta>` rather than a preload link, because a
   * POST is not a file and there is nothing to fetch ahead of time. Absent, or
   * empty, is a page that posts nowhere it was not already told about.
   */
  endpoints?: readonly Linked[];
  ssh: string | undefined;
  /** The sentence in front of the ssh command, when there is one. */
  terminalLead: string;
@@ -281,7 +295,7 @@
export function page(options: PageOptions): string {
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<link rel="icon" href="${FAVICON}">
${preloads(options.assets)}<title>${escape(options.title)}</title>
${preloads(options.assets)}${endpoints(options.endpoints)}<title>${escape(options.title)}</title>
<meta name="description" content="${escape(options.description)}">
<style>${styleFor(options.extraStyle)}</style>
<header>
@@ -0,0 +1,172 @@
/**
 * The planning layer, without a network anywhere near it: the local plan is
 * arithmetic, the jobs are a function of a plan and a roster, and everything
 * that arrives from outside goes through `parsePlan` first.
 */
import { expect, test } from "bun:test";
import { assign, delayOf, describe, DEFAULT_JOB, hash, localPlan, parsePlan, type RoundPlan } from "./plan.ts";
import { keyOf, parseSituation, type Situation } from "./situation.ts";
const situation = (over: Partial<Situation> = {}): Situation => ({
  map: "de_forge",
  round: 1,
  score: { t: 0, ct: 0 },
  money: { t: 800, ct: 800 },
  lastWinner: null,
  ...over,
});
const roster = (n: number): { id: number; skill: number }[] =>
  Array.from({ length: n }, (_, i) => ({ id: i + 1, skill: (i + 1) / n }));
test("the local plan is the same plan everywhere, and a different one each round", () => {
  const first = localPlan(situation());
  expect(localPlan(situation())).toEqual(first);
  expect(first.source).toBe("local");
  expect(first.model).toBe("local");
  // Over a match's worth of rounds both sites and all three shapes come up:
  // a fallback that always answered A would be a coin that is not a plan.
  const sites = new Set<string>();
  const shapes = new Set<string>();
  for (let round = 1; round <= 24; round++) {
    const plan = localPlan(situation({ round }));
    sites.add(plan.t.site);
    shapes.add(plan.t.shape);
    expect(plan.round).toBe(round);
  }
  expect([...sites].sort()).toEqual(["A", "B"]);
  expect([...shapes].sort()).toEqual(["fake", "split", "stack"]);
});
test("a side with no money saves, and a side that is behind plays faster", () => {
  expect(localPlan(situation({ money: { t: 800, ct: 4000 } })).t.save).toBe(true);
  expect(localPlan(situation({ money: { t: 800, ct: 4000 } })).ct.save).toBe(false);
  const level = localPlan(situation({ round: 7, score: { t: 3, ct: 3 }, money: { t: 5000, ct: 5000 } }));
  const behind = localPlan(situation({ round: 7, score: { t: 1, ct: 5 }, money: { t: 5000, ct: 5000 } }));
  expect(behind.t.tempo).toBeGreaterThan(level.t.tempo);
});
test("a hash is a hash: the same string, the same number, and different strings differ", () => {
  expect(hash("de_forge|1|t")).toBe(hash("de_forge|1|t"));
  expect(hash("de_forge|1|t")).not.toBe(hash("de_forge|1|ct"));
  expect(hash("")).toBe(0x811c9dc5);
});
test("a stack sends everyone to one site, best in first", () => {
  const jobs = assign({ site: "B", shape: "stack", tempo: 2, save: false }, "t", roster(5));
  expect(jobs.every((job) => job.site === "B")).toBe(true);
  // The roster's last entry is its most skilled, so that is the one that entries.
  expect(jobs[4]?.role).toBe("entry");
  expect(jobs[4]?.delay).toBe(0);
  expect(jobs.filter((job) => job.role === "support")).toHaveLength(4);
  // Support follows rather than arrives together: that beat is the coordination.
  expect(jobs[0]?.delay).toBeGreaterThan(0);
});
test("a split puts a group on each site, and each group has its own entry", () => {
  const jobs = assign({ site: "A", shape: "split", tempo: 1, save: false }, "t", roster(4));
  expect(jobs.filter((job) => job.site === "A")).toHaveLength(2);
  expect(jobs.filter((job) => job.site === "B")).toHaveLength(2);
  expect(jobs.filter((job) => job.role === "entry")).toHaveLength(2);
});
test("a fake leaves one bot alone on the other site, late", () => {
  const plan = { site: "A", shape: "fake", tempo: 2, save: false } as const;
  const jobs = assign(plan, "t", roster(5));
  const lurkers = jobs.filter((job) => job.role === "lurk");
  expect(lurkers).toHaveLength(1);
  expect(lurkers[0]?.site).toBe("B");
  expect(lurkers[0]?.delay).toBeGreaterThan(jobs.filter((job) => job.role === "support")[0]?.delay ?? 0);
  expect(jobs.filter((job) => job.site === "A")).toHaveLength(4);
});
test("defenders take their positions at once, whatever the tempo says", () => {
  const jobs = assign({ site: "A", shape: "stack", tempo: 0, save: false }, "ct", roster(5));
  expect(jobs.every((job) => job.delay === 0)).toBe(true);
  expect(jobs.some((job) => job.role === "anchor")).toBe(true);
  expect(jobs.some((job) => job.role === "entry")).toBe(false);
  expect(delayOf("entry", 0, "ct")).toBe(0);
});
test("a faster tempo is a shorter wait", () => {
  expect(delayOf("support", 3, "t")).toBeLessThan(delayOf("support", 0, "t"));
  expect(delayOf("support", 0, "t")).toBeGreaterThan(0);
  // A tempo from outside is clamped rather than believed.
  expect(delayOf("support", 99, "t")).toBe(delayOf("support", 3, "t"));
  expect(delayOf("support", -5, "t")).toBe(delayOf("support", 0, "t"));
});
test("jobs come back in the order the bots were handed over", () => {
  const bots = [
    { id: 9, skill: 0.1 },
    { id: 3, skill: 0.9 },
    { id: 7, skill: 0.5 },
  ];
  const jobs = assign({ site: "A", shape: "stack", tempo: 1, save: false }, "t", bots);
  expect(jobs).toHaveLength(3);
  expect(jobs[1]?.role).toBe("entry"); // id 3 is the best of them
  expect(assign({ site: "A", shape: "stack", tempo: 1, save: false }, "t", [])).toEqual([]);
});
test("the default job is what a bot does with no plan at all", () => {
  expect(DEFAULT_JOB.delay).toBe(0);
  expect(DEFAULT_JOB.spread).toBe(250);
});
test("a plan says what it is in one line", () => {
  expect(describe({ site: "B", shape: "split", tempo: 3, save: false }, "t")).toBe("T: split B, rush");
  expect(describe({ site: "A", shape: "stack", tempo: 1, save: true }, "ct")).toBe("CT: stack A, default, saving");
});
const good: RoundPlan = {
  round: 4,
  source: "typesafe",
  model: "jev-latest",
  t: { site: "A", shape: "stack", tempo: 2, save: false },
  ct: { site: "B", shape: "split", tempo: 1, save: true },
};
test("a plan from outside is checked field by field", () => {
  expect(parsePlan(good)).toEqual(good);
  expect(parsePlan(JSON.parse(JSON.stringify(good)))).toEqual(good);
  expect(parsePlan(null)).toBeNull();
  expect(parsePlan("a plan")).toBeNull();
  expect(parsePlan({ ...good, source: "guess" })).toBeNull();
  expect(parsePlan({ ...good, round: 0 })).toBeNull();
  expect(parsePlan({ ...good, round: 1.5 })).toBeNull();
  expect(parsePlan({ ...good, model: "x".repeat(65) })).toBeNull();
  expect(parsePlan({ ...good, t: { ...good.t, site: "Middle" } })).toBeNull();
  expect(parsePlan({ ...good, t: { ...good.t, site: "a" } })).toBeNull();
  expect(parsePlan({ ...good, t: { ...good.t, shape: "rush" } })).toBeNull();
  expect(parsePlan({ ...good, t: { ...good.t, save: "yes" } })).toBeNull();
  expect(parsePlan({ ...good, t: { ...good.t, tempo: Number.NaN } })).toBeNull();
  expect(parsePlan({ ...good, ct: undefined })).toBeNull();
  // A tempo outside the rubric is clamped into it, not refused: the number is
  // the only field where a wide answer still means something.
  expect(parsePlan({ ...good, t: { ...good.t, tempo: 12 } })?.t.tempo).toBe(3);
});
test("a situation is checked at the boundary too", () => {
  expect(parseSituation(situation())).toEqual(situation());
  expect(parseSituation({ ...situation(), map: "gen_14u5j6g" })?.map).toBe("gen_14u5j6g");
  expect(parseSituation({ ...situation(), map: "generated" })).toBeNull();
  expect(parseSituation({ ...situation(), map: "../../etc/passwd" })).toBeNull();
  expect(parseSituation({ ...situation(), map: "gen_0014" })).toBeNull();
  expect(parseSituation({ ...situation(), round: 0 })).toBeNull();
  expect(parseSituation({ ...situation(), round: 61 })).toBeNull();
  expect(parseSituation({ ...situation(), money: { t: 800, ct: 99_000 } })).toBeNull();
  expect(parseSituation({ ...situation(), money: { t: -1, ct: 0 } })).toBeNull();
  expect(parseSituation({ ...situation(), score: { t: 1 } })).toBeNull();
  expect(parseSituation({ ...situation(), lastWinner: "T" })).toBeNull();
  expect(parseSituation({ ...situation(), lastWinner: "ct" })?.lastWinner).toBe("ct");
  expect(parseSituation(null)).toBeNull();
  expect(parseSituation([])).toBeNull();
});
test("the cache key holds a situation and buckets the money", () => {
  expect(keyOf(situation())).toBe(keyOf(situation()));
  expect(keyOf(situation({ money: { t: 4100, ct: 800 } }))).toBe(keyOf(situation({ money: { t: 4900, ct: 800 } })));
  expect(keyOf(situation({ money: { t: 4100, ct: 800 } }))).not.toBe(keyOf(situation({ money: { t: 5200, ct: 800 } })));
  expect(keyOf(situation({ round: 2 }))).not.toBe(keyOf(situation()));
});
@@ -0,0 +1,231 @@
/**
 * A round's plan: what each side does with this round, and what each bot's job
 * in it is. Plain data in, plain data out — no world, no level, no network — so
 * both ends of the wire and every test speak the same three functions.
 *
 * The split this adds is the one the bots were missing. `src/client/bots.ts`
 * already has two layers: A* solves the objective and a trained policy runs the
 * fight. Between them there was nothing — every bot flipped its own coin for a
 * site, so five attackers arrived at two sites in ones and twos and no round
 * was ever *played* a particular way. This is that missing layer: one team plan
 * (a site, a shape, a tempo, whether the round is a save) and one job per bot
 * cut from it (a site of its own, a role, how long it waits, how wide it
 * spreads). The fight is untouched.
 *
 * Where the plan comes from is a different question, answered twice.
 * `localPlan` is here: deterministic arithmetic over the situation, the same
 * answer on the server and in the page, and the only planner a deployment with
 * no API key ever runs. `src/plan/typesafe.ts` is the other: TypeSafe AI is
 * asked the same questions as typed choices and scores, and whatever it answers
 * is validated back into this shape or dropped for the local one. A plan is
 * always a `RoundPlan` by the time anything acts on it.
 */
import type { Situation } from "./situation.ts";
/** The two bombsites every map in this game has. */
export type SiteName = "A" | "B";
export type Side = "t" | "ct";
/**
 * How a side arrives. `stack` is everyone through one site, `split` is two
 * groups on the two sites, and `fake` is the team at one site with one player
 * making the other side's life complicated at the other.
 */
export type Shape = "stack" | "split" | "fake";
/**
 * What one bot is doing. `entry` goes first and goes straight in, `support`
 * follows a beat later, `lurk` plays the other site alone, `anchor` holds the
 * site it is standing on.
 */
export type Role = "entry" | "support" | "lurk" | "anchor";
/** One side's round. */
export type TeamPlan = {
  site: SiteName;
  shape: Shape;
  /** 0 slow to 3 rushing: how fast the team commits. */
  tempo: number;
  /** True when the round is an eco: pistols and armour, nothing else. */
  save: boolean;
};
/** Both sides' rounds, and where the answer came from. */
export type RoundPlan = {
  round: number;
  /** `typesafe` when a model answered, `local` when this file did. */
  source: "typesafe" | "local";
  /** The model that answered, or `local` — shown, never trusted. */
  model: string;
  t: TeamPlan;
  ct: TeamPlan;
};
/** One bot's share of its side's plan. */
export type Job = {
  site: SiteName;
  role: Role;
  /** Seconds after the round goes live before this bot moves off. */
  delay: number;
  /** How far from the site the bot is willing to stand, in units. */
  spread: number;
  /** True when this bot's side is saving: it buys nothing this round. */
  save: boolean;
};
/** The job a bot has when nobody has planned anything: today's behaviour. */
export const DEFAULT_JOB: Job = { site: "A", role: "support", delay: 0, spread: 250, save: false };
export const SHAPES: Shape[] = ["stack", "split", "fake"];
/** The fastest tempo, and the slowest. A tempo outside this is not a tempo. */
export const TEMPO_MAX = 3;
/** Money below which a side cannot arm itself, and so should not try. */
export const ECO = 2500;
/**
 * A number out of a string, FNV-1a, 32 bits. The plan has to be the same in the
 * page and on the server — a bot that planned one thing while the page
 * announced another is worse than no plan — so the fallback is arithmetic over
 * the situation rather than any `Math.random`.
 */
export function hash(text: string): number {
  let h = 0x811c9dc5;
  for (let i = 0; i < text.length; i++) {
    h ^= text.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h >>> 0;
}
/**
 * The plan when nothing was asked: a site from the map, the round and the side,
 * a shape and a tempo from the same number, and a save when the side cannot
 * afford a rifle. It is not clever and it is not meant to be — it is what makes
 * a team a team without a network in the loop, and it is what the page plays
 * while a request is still in the air.
 */
export function localPlan(situation: Situation): RoundPlan {
  return {
    round: situation.round,
    source: "local",
    model: "local",
    t: localTeam(situation, "t"),
    ct: localTeam(situation, "ct"),
  };
}
function localTeam(situation: Situation, side: Side): TeamPlan {
  const mix = hash(`${situation.map}|${situation.round}|${side}`);
  const behind = situation.score[side] < situation.score[side === "t" ? "ct" : "t"];
  return {
    site: (mix & 1) === 0 ? "A" : "B",
    shape: SHAPES[(mix >>> 1) % SHAPES.length] as Shape,
    // A side that is behind plays faster, which is what a person does.
    tempo: ((mix >>> 3) % 2) + (behind ? 2 : 1),
    save: situation.money[side] < ECO,
  };
}
/**
 * Cut a team plan into one job per bot. The bots arrive in whatever order the
 * world holds them and come back in that same order, so the caller can hand the
 * result straight back to its own list; inside, they are ranked by skill, then
 * by id, so the same roster always gets the same jobs and the best shot goes in
 * first.
 *
 * The shapes are the whole of the coordination:
 *   stack — everyone on the plan's site, the best in first and the rest behind.
 *   split — the roster cut in half across both sites, each half with its own
 *           entry, which is the only way both sites are ever pressured at once.
 *   fake  — the team on the plan's site and one bot alone on the other, late.
 *
 * Defenders never wait: a CT that stands at spawn for two seconds has lost the
 * site it was supposed to be standing on. They get the same sites and the same
 * shapes, and their roles are anchors and lurkers rather than entries.
 */
export function assign(plan: TeamPlan, side: Side, bots: { id: number; skill: number }[]): Job[] {
  const order = bots
    .map((bot, at) => ({ at, id: bot.id, skill: bot.skill }))
    .sort((a, b) => b.skill - a.skill || a.id - b.id);
  const other: SiteName = plan.site === "A" ? "B" : "A";
  const jobs: Job[] = new Array(bots.length).fill(DEFAULT_JOB);
  order.forEach((bot, rank) => {
    const role = roleOf(plan.shape, rank, order.length, side);
    const site = role === "lurk" ? other : plan.shape === "split" && rank % 2 === 1 ? other : plan.site;
    jobs[bot.at] = { site, role, delay: delayOf(role, plan.tempo, side), spread: SPREAD[role], save: plan.save };
  });
  return jobs;
}
function roleOf(shape: Shape, rank: number, size: number, side: Side): Role {
  if (shape === "fake" && rank === size - 1 && size > 1) return "lurk";
  if (side === "ct") return rank === 0 || shape === "split" ? "anchor" : rank === size - 1 && size > 2 ? "lurk" : "support";
  // Split sends two groups, so the top of each half is the one that goes in.
  if (rank === 0 || (shape === "split" && rank === 1)) return "entry";
  return "support";
}
/** How far from its site a role is content to stand. */
const SPREAD: Record<Role, number> = { entry: 130, support: 300, lurk: 520, anchor: 200 };
/** What a role waits before it moves off, before the tempo speeds it up. */
const WAIT: Record<Role, number> = { entry: 0, support: 2.2, lurk: 6, anchor: 0 };
/**
 * The seconds a job waits. Tempo 0 is a team playing for the clock and tempo 3
 * is a team through the door on the buzzer, so the wait is scaled from one and
 * a half times the role's own to none of it. Defenders take their positions at
 * once whatever the tempo says.
 */
export function delayOf(role: Role, tempo: number, side: Side): number {
  if (side === "ct") return 0;
  const speed = 1.5 - clampTempo(tempo) * 0.5;
  return Math.round(WAIT[role] * speed * 10) / 10;
}
const clampTempo = (tempo: number): number => Math.min(TEMPO_MAX, Math.max(0, Math.round(tempo)));
/** One side's plan in the words the HUD and the terminal print. */
export function describe(plan: TeamPlan, side: Side): string {
  const pace = ["slow", "default", "fast", "rush"][clampTempo(plan.tempo)] ?? "default";
  const what = side === "t" ? plan.shape : plan.shape === "fake" ? "bait" : plan.shape;
  return `${side.toUpperCase()}: ${what} ${plan.site}, ${pace}${plan.save ? ", saving" : ""}`;
}
// --- the boundary ---------------------------------------------------------
const isSite = (value: unknown): value is SiteName => value === "A" || value === "B";
const isShape = (value: unknown): value is Shape => SHAPES.includes(value as Shape);
function parseTeam(value: unknown): TeamPlan | null {
  if (typeof value !== "object" || value === null) return null;
  const team = value as Record<string, unknown>;
  if (!isSite(team.site) || !isShape(team.shape)) return null;
  if (typeof team.tempo !== "number" || !Number.isFinite(team.tempo)) return null;
  if (typeof team.save !== "boolean") return null;
  return { site: team.site, shape: team.shape, tempo: clampTempo(team.tempo), save: team.save };
}
/**
 * A plan as it arrives from somewhere else, or null. The page reads its own
 * server's answer through this and the server reads a model's answer through
 * the two parsers around it: nothing acts on a plan that was not checked field
 * by field, because "the site is A" arriving as `"a"` or `"Middle"` is a bot
 * pathing to undefined.
 */
export function parsePlan(value: unknown): RoundPlan | null {
  if (typeof value !== "object" || value === null) return null;
  const plan = value as Record<string, unknown>;
  const round = plan.round;
  if (typeof round !== "number" || !Number.isInteger(round) || round < 1 || round > 1000) return null;
  if (plan.source !== "typesafe" && plan.source !== "local") return null;
  if (typeof plan.model !== "string" || plan.model.length > 64) return null;
  const t = parseTeam(plan.t);
  const ct = parseTeam(plan.ct);
  if (t === null || ct === null) return null;
  return { round, source: plan.source, model: plan.model, t, ct };
}
@@ -0,0 +1,87 @@
/**
 * The round a plan is asked about: which map, which round, the score, what each
 * side can afford, and who won the last one. It is everything the planner is
 * told and it is the whole of what crosses the wire — no positions, no names,
 * no identity, nothing about the person playing.
 *
 * That shortness is deliberate on three counts. It is a request body a page
 * sends every round, so it is a few hundred bytes. It is the cache key, so two
 * players in the same situation cost one call upstream and not two. And it is
 * what a third party is shown, so there is nothing in it worth showing them.
 *
 * `parseSituation` is the boundary: the page's claim about a map is checked
 * against `src/mapname.ts` like every other map name this server is handed, and
 * every number has to be an integer inside a range a match can actually reach.
 */
import { mapFrom } from "../mapname.ts";
import type { Side } from "./plan.ts";
export type Situation = {
  /** `de_forge` or a generated map's canonical name, `gen_14u5j6g`. */
  map: string;
  round: number;
  score: Record<Side, number>;
  /** What each side has to spend, averaged over its players. */
  money: Record<Side, number>;
  lastWinner: Side | null;
};
/** The longest match this server will plan for: a round number past it is junk. */
export const MAX_ROUND = 60;
/** The most a player can hold in this game's economy. */
export const MAX_MONEY = 16_000;
const int = (value: unknown, max: number): number | null => {
  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > max) return null;
  return value;
};
const pair = (value: unknown, max: number): Record<Side, number> | null => {
  if (typeof value !== "object" || value === null) return null;
  const both = value as Record<string, unknown>;
  const t = int(both.t, max);
  const ct = int(both.ct, max);
  return t === null || ct === null ? null : { t, ct };
};
/**
 * A situation as it arrived, or null. A map name that is not one is not
 * corrected into the default here the way a query string's is: this body was
 * written by our own page, so a name nothing recognises is a caller making
 * things up, and the answer to that is 422 rather than a plan for de_forge.
 */
export function parseSituation(value: unknown): Situation | null {
  if (typeof value !== "object" || value === null) return null;
  const asked = value as Record<string, unknown>;
  // A match is played on a map, never on the menu's word for "carve me one":
  // `generated` is a choice, not a place, so it is not a situation either.
  if (typeof asked.map !== "string" || asked.map === "generated" || mapFrom(asked.map) !== asked.map) return null;
  const round = int(asked.round, MAX_ROUND);
  if (round === null || round < 1) return null;
  const score = pair(asked.score, MAX_ROUND);
  const money = pair(asked.money, MAX_MONEY);
  if (score === null || money === null) return null;
  const last = asked.lastWinner;
  if (last !== null && last !== "t" && last !== "ct") return null;
  return { map: asked.map, round, score, money, lastWinner: last };
}
/**
 * One string for one situation, which is what the planner's cache and its spend
 * ceiling are keyed by. Two browsers in the same round of the same match ask the
 * same question, and the second one is free.
 */
export const keyOf = (situation: Situation): string =>
  [
    situation.map,
    situation.round,
    situation.score.t,
    situation.score.ct,
    // Money is bucketed: a plan does not change between $4,100 and $4,150, and
    // a key that moves with every dollar is a cache that never hits.
    Math.floor(situation.money.t / 1000),
    Math.floor(situation.money.ct / 1000),
    situation.lastWinner ?? "-",
  ].join("|");
@@ -0,0 +1,166 @@
/**
 * The TypeSafe planner, against a stub transport. Nothing here reaches the
 * network and nothing here needs a key that works: the SDK takes its `fetch` as
 * an option, so every path — a good answer, a bad one, a 500, a timeout, no key
 * at all — is a function of what this file hands back.
 */
import { expect, test } from "bun:test";
import { localPlan } from "./plan.ts";
import { createPlanner } from "./typesafe.ts";
import type { Situation } from "./situation.ts";
const situation = (over: Partial<Situation> = {}): Situation => ({
  map: "de_forge",
  round: 3,
  score: { t: 1, ct: 1 },
  money: { t: 4200, ct: 3800 },
  lastWinner: "t",
  ...over,
});
type Answers = Record<string, unknown>;
/** What the API sends back for the eight questions this planner asks. */
const answers = (over: Answers = {}): Answers => ({
  tSite: { type: "choice", choice: "B", confidence: 0.7, probabilities: { A: 0.3, B: 0.7 } },
  tShape: { type: "choice", choice: "split", confidence: 0.6, probabilities: { stack: 0.2, split: 0.6, fake: 0.2 } },
  tTempo: { type: "score", score: 2.4, confidence: 0.5, legend: {}, probabilities: {} },
  tSave: { type: "noul", noul: 0.1 },
  ctSite: { type: "choice", choice: "A", confidence: 0.8, probabilities: { A: 0.8, B: 0.2 } },
  ctShape: { type: "choice", choice: "stack", confidence: 0.6, probabilities: { stack: 0.6, split: 0.2, fake: 0.2 } },
  ctTempo: { type: "score", score: 1, confidence: 0.5, legend: {}, probabilities: {} },
  ctSave: { type: "noul", noul: 0.9 },
  ...over,
});
const reply = (over: Answers = {}, model = "jev-1"): Response =>
  new Response(JSON.stringify({ model, answers: answers(over), usage: { input_tokens: 1, output_tokens: 1 } }), {
    headers: { "content-type": "application/json" },
  });
test("no key is no planner: a deployment that was given nothing runs the local plan", () => {
  expect(createPlanner({})).toBeNull();
  expect(createPlanner({ apiKey: "" })).toBeNull();
  expect(createPlanner({ apiKey: "   " })).toBeNull();
});
test("the answers become a plan, and the question set is the round", async () => {
  const sent: { url: string; body: unknown }[] = [];
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async (url, init) => {
      sent.push({ url, body: JSON.parse(String(init?.body)) });
      return reply();
    },
  });
  const plan = await planner?.plan(situation());
  expect(plan).toEqual({
    round: 3,
    source: "typesafe",
    model: "jev-1",
    t: { site: "B", shape: "split", tempo: 2, save: false },
    ct: { site: "A", shape: "stack", tempo: 1, save: true },
  });
  expect(sent).toHaveLength(1);
  expect(sent[0]?.url).toBe("https://api.typesafe.ai/v1/systemone");
  const body = sent[0]?.body as { state: Record<string, unknown>; questions: Record<string, { type: string }> };
  // Both sides in one request, because they are one round.
  expect(Object.keys(body.questions).sort()).toEqual(
    ["ctSave", "ctShape", "ctSite", "ctTempo", "tSave", "tShape", "tSite", "tTempo"],
  );
  expect(body.questions.tSite?.type).toBe("choice");
  expect(body.questions.tTempo?.type).toBe("score");
  expect(body.questions.tSave?.type).toBe("noul");
  // The state is the situation and nothing else: no name, no identity, no id.
  expect(body.state.map).toBe("de_forge");
  expect(body.state.round).toBe(3);
  expect(JSON.stringify(body.state)).not.toContain("session");
});
test("the same situation is asked once, and two callers at once share the one request", async () => {
  let calls = 0;
  let release = (): void => {};
  const held = new Promise<void>((resolve) => {
    release = resolve;
  });
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async () => {
      calls += 1;
      await held;
      return reply();
    },
  });
  const both = Promise.all([planner?.plan(situation()), planner?.plan(situation())]);
  release();
  const [first, second] = await both;
  expect(calls).toBe(1);
  expect(first).toEqual(second);
  // And again after it has landed: the answer is remembered.
  await planner?.plan(situation());
  expect(calls).toBe(1);
  expect(planner?.size()).toBe(1);
  // A different round is a different question.
  await planner?.plan(situation({ round: 4 }));
  expect(calls).toBe(2);
  expect(planner?.size()).toBe(2);
});
test("a failed call is the local plan, and the local plan is not cached", async () => {
  let calls = 0;
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async () => {
      calls += 1;
      return new Response("nope", { status: 500 });
    },
  });
  const plan = await planner?.plan(situation());
  expect(plan?.source).toBe("local");
  expect(plan?.round).toBe(3);
  expect(planner?.size()).toBe(0);
  // One retry behind the attempt, so a 500 is two calls and never more.
  expect(calls).toBe(2);
});
test("an answer that is not a plan this game can play is refused whole", async () => {
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async () => reply({ tSite: { type: "choice", choice: "Middle", confidence: 1, probabilities: {} } }),
  });
  const plan = await planner?.plan(situation());
  expect(plan?.source).toBe("local");
  // The half that did validate is not kept: both sides play the same round.
  expect(plan?.ct).toEqual(localPlan(situation()).ct);
  expect(planner?.size()).toBe(0);
});
test("junk on the wire is the local plan too, not a crash", async () => {
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async () => new Response("<html>a proxy said something</html>", { headers: { "content-type": "text/html" } }),
  });
  expect((await planner?.plan(situation()))?.source).toBe("local");
});
test("a model name from the wire is bounded before it is ever shown", async () => {
  const planner = createPlanner({
    apiKey: "sk-test",
    fetch: async () => reply({}, "m".repeat(200)),
  });
  expect((await planner?.plan(situation()))?.model).toBe("typesafe");
});
test("the cache is bounded: past the ceiling it is dropped rather than grown", async () => {
  const planner = createPlanner({ apiKey: "sk-test", ceiling: 2, fetch: async () => reply() });
  await planner?.plan(situation({ round: 1 }));
  await planner?.plan(situation({ round: 2 }));
  expect(planner?.size()).toBe(2);
  await planner?.plan(situation({ round: 3 }));
  expect(planner?.size()).toBe(1);
});
@@ -0,0 +1,206 @@
/**
 * The bots' planner, asked of TypeSafe AI. Server-side only: the key lives in
 * this process's environment and never in a page.
 *
 * ## What TypeSafe is, and why it is the one thing here that is a dependency
 *
 * TypeSafe (typesafe.ai) does not answer with prose. You hand it a state — text
 * or a JSON object — and *named questions* of three kinds, and it answers each
 * one inside the shape the question declared:
 *
 *   choice  — one of the labels you listed, with a probability for each
 *   noul    — yes or no, as the probability of yes
 *   score   — a rubric you wrote, indexed from zero, and an expected score
 *
 * That is exactly the shape of a round's plan. "Which site does this team take"
 * is a choice over the two sites the map has; "does this side save" is a noul;
 * "how fast do they commit" is a four-step rubric from holding for the clock to
 * rushing from the gate. Nothing comes back that has to be parsed out of a
 * sentence, and nothing comes back that could be a site this map does not have.
 *
 * `@typesafe-ai/sdk` is this repository's only runtime dependency. It is the
 * vendor's own client, MIT, with no dependencies of its own, and what it buys
 * is the half of an HTTP client nobody should write twice: the retry policy
 * with jittered backoff, `Retry-After`, per-attempt timeouts, an error class
 * per status, and answer types inferred from the questions — the product's
 * whole point, which a hand-rolled `fetch` would throw away. It takes its
 * `fetch` as an option, so every test below runs against a stub and this file
 * is exercised without a key and without the network.
 *
 * ## What it is allowed to cost, and what happens when it fails
 *
 * A round asks one question set, once. Identical situations share one answer
 * (`keyOf`), requests in flight for the same key are joined rather than
 * duplicated, and the cache is bounded. Anything that goes wrong — no key, a
 * timeout, a 500, a rate limit, an answer that does not validate — is
 * `localPlan`: the deterministic plan in `src/plan/plan.ts`, which is what a
 * deployment with no key runs all the time. The game never waits on this and
 * never fails because of it.
 */
import { choice, noul, score, TypeSafeClient, type Fetch } from "@typesafe-ai/sdk";
import { localPlan, type RoundPlan, type Shape, type SiteName, type TeamPlan } from "./plan.ts";
import { keyOf, type Situation } from "./situation.ts";
export type Planner = {
  /** The plan for this round: a model's, or the local one when it could not be. */
  plan(situation: Situation): Promise<RoundPlan>;
  /** How many answers are being remembered. For the tests. */
  size(): number;
};
export type PlannerOptions = {
  /** The key, from the environment. Absent, empty or blank is no planner. */
  apiKey?: string | undefined;
  /** Defaults to the SDK's `jev-latest`. */
  model?: string | undefined;
  /** Milliseconds for one attempt. A round's freeze time is eight seconds. */
  timeout?: number;
  /** How many answers are remembered before the oldest are dropped. */
  ceiling?: number;
  /** The transport, so a test is not the network. */
  fetch?: Fetch;
};
/** One attempt gets this long, and there is one retry behind it. */
const TIMEOUT = 2500;
const CEILING = 500;
/**
 * The planner, or null when this deployment has no key — which is the state
 * every preview is in, and the reason the caller has to handle it rather than
 * be handed something that quietly does nothing.
 */
export function createPlanner(options: PlannerOptions): Planner | null {
  if (typeof options.apiKey !== "string" || options.apiKey.trim() === "") return null;
  const { model, timeout = TIMEOUT, ceiling = CEILING, fetch } = options;
  const client = new TypeSafeClient({
    apiKey: options.apiKey,
    ...(model === undefined ? {} : { defaultModel: model }),
    timeout,
    retry: { maxRetries: 1 },
    ...(fetch === undefined ? {} : { fetch }),
  });
  const answers = new Map<string, RoundPlan>();
  const flight = new Map<string, Promise<RoundPlan>>();
  return {
    size: () => answers.size,
    async plan(situation) {
      const key = keyOf(situation);
      // The key is the situation, round included, so two browsers playing the
      // same round of the same match ask upstream once between them.
      const held = answers.get(key);
      if (held !== undefined) return held;
      const running = flight.get(key);
      if (running !== undefined) return running;
      const asking = ask(client, situation).catch((error: unknown) => {
        console.warn(`plan: falling back to the local plan — ${describeError(error)}`);
        return localPlan(situation);
      });
      flight.set(key, asking);
      const plan = await asking;
      flight.delete(key);
      // A local plan is not worth remembering: it is free to compute, and
      // caching it would keep a deployment on the fallback after one timeout.
      if (plan.source === "typesafe") {
        if (answers.size >= ceiling) answers.clear();
        answers.set(key, plan);
      }
      return plan;
    },
  };
}
const describeError = (error: unknown): string =>
  error instanceof Error ? `${error.name}: ${error.message}` : "the planner threw something that is not an error";
/**
 * The questions, and the answers turned back into a plan. Both sides are asked
 * in one request because they are one round: a defence that stacks A is an
 * answer about the attack it expects, and two requests could not know that
 * about each other.
 */
async function ask(client: TypeSafeClient, situation: Situation): Promise<RoundPlan> {
  const { answers, model } = await client.systemOne({
    state: {
      game: "a five-a-side bomb-defusal round, Counter-Strike rules, on a map with two bombsites called A and B",
      map: situation.map,
      round: situation.round,
      score: situation.score,
      averageMoneyPerPlayer: situation.money,
      lastRoundWonBy: situation.lastWinner,
      note: "T attack and carry the bomb; CT defend both sites. A side under $2,500 a player cannot arm itself.",
    },
    questions: {
      tSite: choice("Which bombsite should the attacking side (T) commit to this round?", {
        A: "the A site",
        B: "the B site",
      }),
      tShape: choice("How should the attackers arrive?", SHAPE_CRITERIA.t),
      tTempo: score("How fast should the attackers commit?", TEMPO_CRITERIA),
      tSave: noul("Should the attackers save their money this round instead of buying?", SAVE_CRITERIA),
      ctSite: choice("Which bombsite should the defending side (CT) weight this round?", {
        A: "the A site",
        B: "the B site",
      }),
      ctShape: choice("How should the defenders set up?", SHAPE_CRITERIA.ct),
      ctTempo: score("How far forward should the defenders play?", TEMPO_CRITERIA),
      ctSave: noul("Should the defenders save their money this round instead of buying?", SAVE_CRITERIA),
    },
  });
  const t = teamFrom(answers.tSite.choice, answers.tShape.choice, answers.tTempo.score, answers.tSave.noul);
  const ct = teamFrom(answers.ctSite.choice, answers.ctShape.choice, answers.ctTempo.score, answers.ctSave.noul);
  // An answer that is not a plan is not half-used: the round gets the local one
  // whole, so both sides are always playing the same kind of round.
  if (t === null || ct === null) throw new Error("the answers were not a plan this game can play");
  return { round: situation.round, source: "typesafe", model: modelName(model), t, ct };
}
const SHAPE_CRITERIA = {
  t: {
    stack: "all five through one site together",
    split: "two groups, one at each site, pressuring both at once",
    fake: "the team at one site and one player alone at the other",
  },
  ct: {
    stack: "weight the defence heavily onto one site",
    split: "hold both sites evenly",
    fake: "hold one site and leave a player deep on the other to catch a rotation",
  },
} as const;
const TEMPO_CRITERIA = [
  "play for the clock and take the round late",
  "default: move up, trade information, decide later",
  "commit early and take the site on the timer",
  "rush it from the gate",
] as const;
const SAVE_CRITERIA = {
  true: "the side cannot arm itself and should keep the money for next round",
  false: "the side should buy what it can afford and play the round",
} as const;
/** A model name is a string from somewhere else: it is shown, so it is bounded. */
const modelName = (model: unknown): string =>
  typeof model === "string" && model.length > 0 && model.length <= 64 ? model : "typesafe";
/**
 * One side's answers, validated into a plan, or null. The SDK types these by
 * the questions above, and the checks are here anyway: types are what this
 * process compiled, and the body is what arrived.
 */
function teamFrom(site: unknown, shape: unknown, tempo: unknown, save: unknown): TeamPlan | null {
  if (site !== "A" && site !== "B") return null;
  if (shape !== "stack" && shape !== "split" && shape !== "fake") return null;
  if (typeof tempo !== "number" || !Number.isFinite(tempo)) return null;
  if (typeof save !== "number" || !Number.isFinite(save) || save < 0 || save > 1) return null;
  return {
    site: site as SiteName,
    shape: shape as Shape,
    tempo: Math.min(3, Math.max(0, Math.round(tempo))),
    save: save >= 0.5,
  };
}
@@ -9,7 +9,9 @@
import { GAMES } from "./games.ts";
import { matchOf, playKey } from "./matchid.ts";
import { NOTHING_POSTED } from "./client/pending.ts";
import { BAD_ID, BAD_MAP, UNDRAWN } from "./pages/game.ts";
import { escape } from "./pages/shell.ts";
import { endpoints, escape } from "./pages/shell.ts";
import { localPlan, parsePlan } from "./plan/plan.ts";
import { parseSituation, type Situation } from "./plan/situation.ts";
import { sign } from "./who.ts";
import { PAGE_ACTIONS, PAGE_IDS } from "./client/stage.test-helper.ts";
import { EXAMPLE_ACTIONS, EXAMPLE_IDS } from "./example/stage.test-helper.ts";
@@ -19,7 +21,7 @@
process.env.PORT = "0";
// The test is the forge: it holds the same key and signs identities with it.
const KEY = "the-key-the-forge-signs-with";
process.env.FORGE_APP_IDENTITY_KEY = KEY;
const { server, MATCH_LIMIT, GUEST_ADDRESS_LIMIT, onError, findScripts } = await import("./server.ts");
const { server, MATCH_LIMIT, GUEST_ADDRESS_LIMIT, PLAN_ID, onError, findScripts } = await import("./server.ts");
const base = `http://${server.hostname}:${server.port}`;
/** The two headers the forge puts on a request it proxies for a signed-in person. */
@@ -830,3 +832,78 @@
test("a guest cannot buy a fresh bucket by rewriting the cookie it was given", a
  // And a signed-in player is not behind that bucket: guests cannot lock them out.
  expect((await post(result({ name: "steady" }), "", as("u-50", "steady"))).status).toBe(200);
});
// --- POST /api/plan ---------------------------------------------------------
/**
 * The round the bots are about to play. This process has no TYPESAFE_API_KEY —
 * no test may spend anybody's money — so every answer here is the local plan,
 * which is the whole point: the route answers with a plan whatever is or is not
 * configured behind it, and `src/plan/typesafe.test.ts` is where the model's
 * half is exercised, against a stub.
 */
const situation = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
  map: "de_forge",
  round: 3,
  score: { t: 1, ct: 1 },
  money: { t: 4200, ct: 3800 },
  lastWinner: "t",
  ...over,
});
const askPlan = (body: string, headers: Record<string, string> = {}): Promise<Response> =>
  fetch(base + "/api/plan", { method: "POST", headers: { "content-type": "application/json", ...headers }, body });
test("a round is planned, and the plan is a plan this game can play", async () => {
  const response = await askPlan(JSON.stringify(situation()));
  expect(response.status).toBe(200);
  expect(response.headers.get("content-type")).toBe("application/json; charset=utf-8");
  expect(response.headers.get("cache-control")).toBe("no-store");
  // The floor is on it like it is on everything else here.
  expect(response.headers.get("x-content-type-options")).toBe("nosniff");
  const plan = parsePlan(await response.json());
  expect(plan).not.toBeNull();
  expect(plan?.round).toBe(3);
  // No key in this process, so the planner is the local one, named as such.
  expect(plan?.source).toBe("local");
  expect(plan?.model).toBe("local");
  expect(plan).toEqual(localPlan(parseSituation(situation()) as Situation));
});
test("a situation that is not one is refused, and junk is not a plan", async () => {
  expect((await askPlan("{")).status).toBe(400);
  expect((await askPlan(JSON.stringify(situation({ map: "de_dust2" })))).status).toBe(422);
  expect((await askPlan(JSON.stringify(situation({ round: 0 })))).status).toBe(422);
  expect((await askPlan(JSON.stringify(situation({ money: { t: 99_999, ct: 0 } })))).status).toBe(422);
  expect((await askPlan("[]")).status).toBe(422);
  // The body is capped by the bytes read, not by anything the caller declared.
  expect((await askPlan(`{"map":"de_forge","pad":"${"x".repeat(4096)}"}`)).status).toBe(413);
});
test("planning a round is a POST, and a POST from another site is refused", async () => {
  const cross = await fetch(base + "/api/plan", {
    method: "POST",
    headers: { "content-type": "application/json", origin: "https://evil.example" },
    body: JSON.stringify(situation()),
  });
  expect(cross.status).toBe(403);
  // And it is not a read: nothing plans a round for a GET.
  expect((await fetch(base + "/api/plan")).status).toBe(404);
});
test("a page with no planner behind it never tells a browser to ask for one", async () => {
  const body = await (await fetch(base + "/")).text();
  expect(body).not.toContain(`id="${PLAN_ID}"`);
  expect(body).not.toContain(`name="endpoint"`);
  // And it says so, rather than claiming a model is planning anything.
  expect(body).toContain("no TypeSafe key");
  expect(body).toContain(escape("Above the fight the bots now plan a round"));
});
test("the endpoint meta is how a page names where a plan comes from", () => {
  expect(endpoints([{ id: PLAN_ID, href: "/api/plan" }]))
    .toBe(`<meta name="endpoint" id="${PLAN_ID}" content="/api/plan">\n`);
  expect(endpoints()).toBe("");
  // Escaped like everything else the shell is handed.
  expect(endpoints([{ id: 'x"y', href: '/a"b' }])).toContain('id="x&quot;y" content="/a&quot;b"');
});
@@ -41,6 +41,9 @@
import { createLimiter } from "./limit.ts";
import { examplePage } from "./pages/example.ts";
import { type Asked, gamePage, STYLE as GAME_STYLE, statsHtml } from "./pages/game.ts";
import { mapFrom } from "./mapname.ts";
import { localPlan } from "./plan/plan.ts";
import { parseSituation } from "./plan/situation.ts";
import { createPlanner, type Planner } from "./plan/typesafe.ts";
import { matchFrom } from "./matchid.ts";
import { errorPage, notFoundPage, STYLE as MISS_STYLE } from "./pages/miss.ts";
import { rangePage } from "./pages/range.ts";
@@ -60,6 +63,18 @@
const ssh = process.env.FORGE_APP_SSH;
// every visitor is a guest, and a guest's score is labelled as one.
const identityKey = process.env.FORGE_APP_IDENTITY_KEY;
/**
 * Who plans the bots\' rounds. With `TYPESAFE_API_KEY` in this deployment\'s
 * environment the round is put to TypeSafe AI as typed questions
 * (`src/plan/typesafe.ts`); without one this is null and every round is planned
 * by `localPlan`, which is arithmetic in this process and costs nothing. The key
 * is read here, once, and never reaches a page: the browser asks this server.
 */
const planner = createPlanner({
  apiKey: process.env.TYPESAFE_API_KEY,
  ...(process.env.TYPESAFE_MODEL === undefined ? {} : { model: process.env.TYPESAFE_MODEL }),
});
// The security floor every response stands on. Everything comes from this
// origin, nothing frames us, browsers never guess a content type, and referrers
// stay on this site. The app's public address is what the forge told us, never
@@ -103,6 +118,12 @@
const html = (body: string, security: Headers = SECURITY, status = 200, extra: H
    headers: { "content-type": "text/html; charset=utf-8", ...security, ...extra },
  });
/** The floor under a document that is data: never stored, never a page. */
const json = (value: unknown): Response =>
  new Response(JSON.stringify(value), {
    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", ...SECURITY },
  });
// A browser on another site can make a person's browser POST here; it cannot
// make that request look same-origin. Browsers say where a request came from
// (Sec-Fetch-Site, or Origin); a request that names another site is refused.
@@ -119,6 +140,8 @@
const sameOrigin = (request: Request): boolean => {
// cap the rest is drained and dropped so the connection stays usable for
// the next request; past eight times the cap it is cut off instead.
const BODY_MAX = 16 * 1024;
/** A situation is a map name and five numbers; a kilobyte is already generous. */
const PLAN_BODY_MAX = 1024;
async function readBody(request: Request, max = BODY_MAX): Promise<Uint8Array | undefined> {
  const reader = request.body?.getReader();
  if (reader === undefined) return new Uint8Array();
@@ -198,6 +221,24 @@
const mayWrite = (visitor: Who, session: string | null, address: string | undefi
  return matchLimit.take(limitKey(visitor, session, address));
};
/**
 * How often one caller may ask for a round to be planned, and how much this
 * deployment will spend on planning at all.
 *
 * A match asks once a round and a round is minutes long, so twelve back to back
 * and one more every three seconds is a player nobody notices and a script that
 * gets nowhere. The second bucket is not per caller: it is the whole process,
 * and it is the ceiling on what a third party can be asked for in an hour —
 * thirty answers back to back, one more every two seconds. Past it the round is
 * planned locally, which is a plan and not a refusal, so a flood costs money it
 * cannot spend and costs a player nothing.
 */
export const PLAN_ID = "botplan";
export const PLAN_LIMIT = { burst: 12, per: 3000 };
const planLimit = createLimiter(PLAN_LIMIT);
export const PLAN_SPEND = { burst: 30, per: 2000 };
const planSpend = createLimiter(PLAN_SPEND);
/**
 * Who a result is recorded as. A verified forge identity plays under its own
 * name and the browser's claim is ignored; everyone else is a guest, whose
@@ -326,6 +367,11 @@
const RENDER: Record<string, Render> = {
      return {
        body: gamePage(db, {
          env, pull, commit, script, assets: linked, ssh,
          // The page is told where to ask for a plan only when there is
          // something here to ask: with no key the bots plan in the browser and
          // the page makes no request at all.
          endpoints: planner === null ? [] : [{ id: PLAN_ID, href: "/api/plan" }],
          planning: planner !== null,
          who: who(request, identityKey), asked: asked(request),
        }),
        extra,
@@ -434,6 +480,35 @@
export const server = Bun.serve({
      return html(statsHtml(db), SECURITY, 200, { "set-cookie": sessionCookie(session) });
    }
    /**
     * The round the bots are about to play. The page sends the situation — the
     * map, the round, the score and what each side can afford, and nothing about
     * whoever is playing — and gets back a plan for both sides.
     *
     * It is a POST because it is not free: it may cost this deployment a call
     * to a third party, so it is same-origin (refused above), rate-limited per
     * caller, under a spend ceiling for the process, and capped at a body no
     * honest situation comes close to. Every answer is a plan: a caller over
     * its limit, a deployment with no key and an upstream that fell over all
     * get the local one rather than an error, because a bot with no plan is a
     * bot standing still.
     */
    if (request.method === "POST" && url.pathname === "/api/plan") {
      const body = await readBody(request, PLAN_BODY_MAX);
      if (body === undefined) return new Response("too large", { status: 413, headers: SECURITY });
      let parsed: unknown;
      try {
        parsed = JSON.parse(new TextDecoder().decode(body));
      } catch {
        return new Response("bad json", { status: 400, headers: SECURITY });
      }
      const situation = parseSituation(parsed);
      if (situation === null) return new Response("bad situation", { status: 422, headers: SECURITY });
      const caller = `plan:${listener.requestIP(request)?.address ?? "?"}|${readSession(request) ?? "-"}`;
      const mine = planner !== null && planLimit.take(caller) && planSpend.take("all");
      return json(mine ? await (planner as Planner).plan(situation) : localPlan(situation));
    }
    // The games, one table rather than one branch each. HEAD is GET without a
    // body, so a health check on `/` sees the app up.
    if (isRead(request)) {
@@ -465,5 +540,6 @@
if (listen.unusable !== undefined)
console.log(
  `cs listening on http://${server.hostname}:${server.port} (${env}) serving ${[...scripts.values()].join(", ")}` +
    `${identityKey ? "" : " — no FORGE_APP_IDENTITY_KEY: every visitor plays as a guest"}`,
    `${identityKey ? "" : " — no FORGE_APP_IDENTITY_KEY: every visitor plays as a guest"}` +
    `${planner ? "" : " — no TYPESAFE_API_KEY: the bots plan their rounds locally"}`,
);
		@@ -30,6 +30,45 @@ bun run scripts/mutate-result.ts # break each rule in src
30	30	FORGE_APP_DATA=./data bun run src/tty.ts # the terminal interface
31	31	```
32	32
	33
	34	## The bots' round: planning with TypeSafe AI
	35
	36	The bots have had two layers for a while — A* solves the objective, a trained
	37	policy runs the fight — and nothing in between: every bot flipped its own coin
	38	for a site, so five attackers arrived at two sites in ones and twos. There is
	39	now a third layer, the round itself.
	40
	41	A round plan is one site, one shape (`stack`, `split` or `fake`), a tempo
	42	and a save, per side. `src/plan/plan.ts` cuts it into one job per bot — the
	43	site it walks to, whether it goes in first or gives the entry its beat, how far
	44	off the site it is willing to stand, and whether it buys at all — and
	45	`src/client/bots.ts` plays it. The fight is untouched: the policy and its
	46	weights are exactly what they were.
	47
	48	Where the plan comes from depends on one environment variable:
	49
	50	- No `TYPESAFE_API_KEY` (every preview, and production until somebody sets
	51	one): the page plans every round itself with `localPlan`, which is
	52	arithmetic over the situation. Nothing is sent anywhere, and the bots are
	53	still a team.
	54	- With a key: the page posts the round's situation — the map, the round
	55	number, the score, what each side can afford, and nothing about you — to
	56	`POST /api/plan` on this server, which puts it to
	57	[TypeSafe AI](https://typesafe.ai) as typed questions: a choice between the
	58	two sites, a rubric for the tempo, a yes/no for the save. The answer is
	59	validated back into a plan or dropped for the local one. The key is read from
	60	this process's environment at start-up and never reaches a page.
	61
	62	What is real and what is not: the plan is real — a model really answers it when
	63	a key is set, and you can watch the call in the round's line on the HUD, which
	64	says which side is doing what. Everything else about the game is still local:
	65	the match, the fight, the physics and the weights all run in your browser.
	66
	67	`TYPESAFE_MODEL` overrides the model (the SDK's default is `jev-latest`).
	68	Planning is rate-limited per caller and under a spend ceiling for the whole
	69	process; over either, or on any failure, the round gets the local plan, which is
	70	a plan and not an error.
	71
33	72	## What is real and what is not
34	73
35	74	- Real. The game: WebGL2 written by hand, a fixed 64 Hz simulation, Source-style
		@@ -4,6 +4,9 @@
4	4	"workspaces": {
5	5	"": {
6	6	"name": "cs-engine",
	7	"dependencies": {
	8	"@typesafe-ai/sdk": "^0.6.0",
	9	},
7	10	"devDependencies": {
8	11	"@types/bun": "^1.4.2",
9	12	"typescript": "^7.0.2",
		@@ -15,6 +18,8 @@
15	18
16	19	"@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g=="],
17	20
	21	"@typesafe-ai/sdk": ["@typesafe-ai/[email protected]", "", {}, "sha512-IddX+Q0XM+VagOUZFeP7wZjaO4SHMdvnh2zEBdrZZnXedWI3BNK1lKhMx3ayrkFWvVLbVcUHJy6AVZlY+e6Jaw=="],
	22
18	23	"@typescript/typescript-aix-ppc64": ["@typescript/[email protected]", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
19	24
20	25	"@typescript/typescript-darwin-arm64": ["@typescript/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
		@@ -11,5 +11,8 @@
11	11	"devDependencies": {
12	12	"@types/bun": "^1.4.2",
13	13	"typescript": "^7.0.2"
	14	},
	15	"dependencies": {
	16	"@typesafe-ai/sdk": "^0.6.0"
14	17	}
15	18	}
		@@ -2,9 +2,10 @@ import { expect, test } from "bun:test";
2	2	import { PACKED, useShipped } from "./shipped.ts";
3	3	import { unpack, type Policy } from "../engine/index.ts";
4	4	import {
5		applyIntent, blindness, botThink, dry, flashed, makeBrain, nextWeapon, NO_POLICY, pathTo, policy, usePolicy,
6		ride, think,
	5	applyIntent, blindness, botBuy, botThink, dry, flashed, makeBrain, nextWeapon, NO_POLICY, pathTo, policy,
	6	ride, roundPlan, think, usePlan, usePolicy,
7	7	} from "./bots.ts";
	8	import type { RoundPlan, TeamPlan } from "../plan/plan.ts";
8	9	import { grip } from "./spray.ts";
9	10	import { colOf, findPath, rowOf, walkable, worldOf } from "./level.ts";
10	11	import { dist, type Vec3 } from "../engine/index.ts";
		@@ -327,3 +328,102 @@ test("a bot with bullets left plays exactly as it did: no swap, no knife", () =>
327	328	expect(d.bot.weapon).toBe("ak47");
328	329	expect(shots).toBeGreaterThan(0);
329	330	});
	331
	332	// --- the round's plan -------------------------------------------------------
	333
	334	const planned = (over: Partial<TeamPlan> = {}): RoundPlan => ({
	335	round: 1,
	336	source: "typesafe",
	337	model: "jev-1",
	338	t: { site: "A", shape: "stack", tempo: 2, save: false, ...over },
	339	ct: { site: "A", shape: "stack", tempo: 2, save: false, ...over },
	340	});
	341
	342	/** A full ten-bot round, frozen on the first tick, with every brain made. */
	343	const round = (seed = 77): ReturnType<typeof createWorld> => {
	344	const world = createWorld(DE_FORGE, COMPETITIVE, "you", "ct", 5, seed);
	345	world.match.phase = "freeze";
	346	return world;
	347	};
	348
	349	const bots = (world: ReturnType<typeof createWorld>, team: "t" \| "ct"): Player[] =>
	350	world.players.filter((p) => p.team === team && p !== world.me);
	351
	352	test("with no plan a bot is what it always was: its own coin flip, no wait", () => {
	353	const world = round();
	354	const bot = bots(world, "t")[0] as Player;
	355	botThink(world, bot, 1 / 64);
	356	expect(roundPlan(world)).toBeNull();
	357	expect(bot.brain?.job.role).toBe("support");
	358	expect(bot.brain?.job.delay).toBe(0);
	359	expect(["A", "B"]).toContain(bot.brain?.job.site ?? "");
	360	});
	361
	362	test("a plan makes a team a team: one site between them, and one of them first", () => {
	363	const world = round();
	364	usePlan(world, planned({ site: "B" }));
	365	for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
	366	const attackers = bots(world, "t");
	367	expect(attackers.every((bot) => bot.brain?.job.site === "B")).toBe(true);
	368	expect(attackers.filter((bot) => bot.brain?.job.role === "entry")).toHaveLength(1);
	369	// The entry goes now and the rest give it its beat: that is the coordination.
	370	const entry = attackers.find((bot) => bot.brain?.job.role === "entry") as Player;
	371	expect(entry.brain?.job.delay).toBe(0);
	372	expect(attackers.some((bot) => (bot.brain?.job.delay ?? 0) > 0)).toBe(true);
	373	});
	374
	375	test("a split sends the attackers to both sites at once", () => {
	376	const world = round();
	377	usePlan(world, planned({ site: "A", shape: "split" }));
	378	for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
	379	const sites = bots(world, "t").map((bot) => bot.brain?.job.site);
	380	expect(sites.filter((site) => site === "A").length).toBeGreaterThan(0);
	381	expect(sites.filter((site) => site === "B").length).toBeGreaterThan(0);
	382	});
	383
	384	test("a bot waiting for its beat stands still, and goes when the beat comes", () => {
	385	const world = round();
	386	usePlan(world, planned());
	387	world.match.phase = "freeze";
	388	for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
	389	const waiting = bots(world, "t").find((bot) => (bot.brain?.job.delay ?? 0) > 0) as Player;
	390	waiting.hasBomb = false;
	391	world.match.phase = "live";
	392	world.time += 0.5;
	393	const held = botThink(world, waiting, 1 / 64);
	394	expect(held.forward).toBe(0);
	395	expect(held.side).toBe(0);
	396	// Past the wait it moves off towards the site like any other bot.
	397	world.time = (waiting.brain?.pushAt ?? 0) + 0.1;
	398	const moving = botThink(world, waiting, 1 / 64);
	399	expect(Math.abs(moving.forward) + Math.abs(moving.side)).toBeGreaterThan(0);
	400	});
	401
	402	test("a plan that says save is a round nothing is spent on a rifle", () => {
	403	const world = round();
	404	const bot = bots(world, "t")[0] as Player;
	405	bot.money = 2400;
	406	usePlan(world, planned({ save: true }));
	407	botBuy(world, bot);
	408	expect(bot.primary).toBeNull();
	409	expect(bot.money).toBe(2400);
	410
	411	// The same money with the same plan, on a side that is not saving: it buys.
	412	const spending = round(78);
	413	const other = bots(spending, "t")[0] as Player;
	414	other.money = 2400;
	415	usePlan(spending, planned({ save: false }));
	416	botBuy(spending, other);
	417	expect(other.money).toBeLessThan(2400);
	418	});
	419
	420	test("a plan that lands mid-round re-tasks the team it was cut for", () => {
	421	const world = round();
	422	usePlan(world, planned({ site: "A" }));
	423	for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
	424	expect(bots(world, "t").every((bot) => bot.brain?.job.site === "A")).toBe(true);
	425	usePlan(world, planned({ site: "B" }));
	426	for (const bot of world.players) if (bot !== world.me) botThink(world, bot, 1 / 64);
	427	expect(bots(world, "t").every((bot) => bot.brain?.job.site === "B")).toBe(true);
	428	expect(roundPlan(world)?.t.site).toBe("B");
	429	});
		@@ -9,6 +9,16 @@
9	9	* reflex is what reinforcement learning is good at: src/rl trains this policy
10	10	* on millions of duels in the same simulation you are playing.
11	11	*
	12	* Between the two there is now a third thing, and it is the round: `usePlan`
	13	* hands the bots a `RoundPlan` — a site, a shape, a tempo and a save for each
	14	* side — and `src/plan/plan.ts` cuts it into one job per bot, so five attackers
	15	* arrive at one site together, or at two sites in two groups, instead of each
	16	* flipping its own coin. Where that plan came from is not this file's business:
	17	* the page asks its own server, and the server asks TypeSafe AI when it has a
	18	* key and answers with the local plan when it has not. Bots nobody planned for
	19	* — the arena's, the trainer's — behave exactly as they did before, down to the
	20	* coin flip, because `usePlan` was never called on them.
	21	*
12	22	* The weights are not in here and are not imported: they arrive as data. In a
13	23	* browser `src/client/main.ts` downloads `weights.json` as this game's own
14	24	* asset and calls `usePolicy` before Play is pressable; in Bun
		@@ -22,6 +32,7 @@ import {
22	32	angleDelta, clamp, dist, forward, newActivations, rng, sample,
23	33	type Activations, type Policy, type Vec3,
24	34	} from "../engine/index.ts";
	35	import { assign, DEFAULT_JOB, type Job, type RoundPlan } from "../plan/plan.ts";
25	36	import { colOf, findPath, rowOf, siteAt, walkable, worldOf, type Level } from "./level.ts";
26	37	import { CS_HULL } from "./movement.ts";
27	38	import { observe, OBS_SIZE, type Memory } from "./observe.ts";
		@@ -58,6 +69,24 @@ export function policy(): Policy {
58	69	return learned;
59	70	}
60	71
	72	/**
	73	* Hand one world's bots the round they are playing. `main.ts` does this every
	74	* round: the local plan the moment the round starts, and the planned one if a
	75	* better one arrives while it is still that round.
	76	*
	77	* It is the world's and not this module's, unlike the policy above, because a
	78	* plan is one match's round and a policy is the whole game's: a plan in a
	79	* module would be one match's orders reaching the next match's bots, and the
	80	* arena's duels and the trainer's rounds — worlds nobody plans for — would be
	81	* playing whatever the last page happened to ask for.
	82	*/
	83	export function usePlan(world: World, plan: RoundPlan \| null): void {
	84	world.plan = plan;
	85	}
	86
	87	/** The round this world's bots are playing, or null when nobody planned one. */
	88	export const roundPlan = (world: World): RoundPlan \| null => world.plan;
	89
61	90	/** The policy decides at 16 Hz and holds it, exactly as it was trained. */
62	91	const SKIP = 4;
63	92
		@@ -82,7 +111,13 @@ export type BotBrain = {
82	111	strafeUntil: number;
83	112	suspect: Vec3 \| null;
84	113	plannedFor: string;
85		site: "A" \| "B";
	114	/** This bot's share of the round: a site, a role, a beat to wait, a spread. */
	115	job: Job;
	116	/** The plan the job was cut from, and the round it was cut for. */
	117	jobPlan: RoundPlan \| null;
	118	jobRound: number;
	119	/** The clock the job's wait is up at. Set while the round is still frozen. */
	120	pushAt: number;
86	121	reset: boolean;
87	122	random: () => number;
88	123	// What the policy needs to run, one set per bot so nothing is shared.
		@@ -111,7 +146,8 @@ export function makeBrain(skill: number, seed: number, useLearned = true): BotBr
111	146	goal: null, path: [], step: 0, repathAt: 0,
112	147	targetId: null, seenAt: 0, burstUntil: 0, restUntil: 0,
113	148	strafe: 0, strafeUntil: 0, suspect: null, plannedFor: "",
114		site: "A", reset: true,
	149	job: DEFAULT_JOB, jobPlan: null, jobRound: -1, pushAt: 0,
	150	reset: true,
115	151	random: rng(seed),
116	152	obs: new Float32Array(OBS_SIZE),
117	153	// Sized from the shape the game asks for rather than from a policy: a
		@@ -194,9 +230,23 @@ export function ride(bot: Player, brain: BotBrain, grip: number, dt: number): vo
194	230	/** How far a bot notices an enemy at all, in units, with its eyes working. */
195	231	const SIGHT = 4000;
196	232
	233	/**
	234	* A bot rich enough that a save costs it nothing buys anyway, which is what a
	235	* person does with a round's worth of money already in the bank.
	236	*/
	237	const FORCE = 5000;
	238
197	239	/** What a bot spends its money on, roughly in the order a person would. */
198	240	export function botBuy(world: World, bot: Player): void {
199	241	const brain = brainOf(world, bot);
	242	const job = jobOf(world, bot, brain);
	243	// The economy half of a plan: a round the side is saving is a round nothing
	244	// leaves the bank, so the next one is a full buy for five rather than a rifle
	245	// for two. Armour is still worth it to whoever can spare the change.
	246	if (job.save && bot.money < FORCE) {
	247	if (bot.armor < 100 && bot.money >= 2000) buy(world, bot, "armor");
	248	return;
	249	}
200	250	const rich = bot.money >= 4000;
201	251	const wants: WeaponId[] = [];
202	252	if (rich && brain.random() < 0.15 && bot.money >= WEAPONS.awp.price + 1000) wants.push("awp");
		@@ -258,11 +308,48 @@ function brainOf(world: World, bot: Player): BotBrain {
258	308	return bot.brain;
259	309	}
260	310
	311	/**
	312	* This bot's job, cut from the round's plan the first time anyone asks for it
	313	* after that plan arrived. A job belongs to a team and not to a bot — an entry
	314	* only means anything if somebody else is the support — so asking for one bot's
	315	* re-tasks its whole side at once, in one `assign`, and the other four find
	316	* theirs already waiting.
	317	*
	318	* With no plan handed in this is whatever `botThink` put there at the start of
	319	* the round, which is the coin flip these bots have always made. Nothing about
	320	* the arena or the trainer changes until somebody calls `usePlan`.
	321	*/
	322	function jobOf(world: World, bot: Player, brain: BotBrain): Job {
	323	const plan = world.plan;
	324	if (plan === null) return brain.job;
	325	// The plan itself is the stamp: a new one is a new object, and a bot holding
	326	// a job cut from another one is a bot with yesterday's orders.
	327	if (brain.jobPlan === plan && brain.jobRound === world.match.round) return brain.job;
	328	const mates = world.players.filter((p) => p.team === bot.team);
	329	const brains = mates.map((mate) => brainOf(world, mate));
	330	const jobs = assign(plan[bot.team], bot.team, mates.map((mate, at) => ({
	331	id: mate.id,
	332	skill: brains[at]?.skill ?? 0,
	333	})));
	334	brains.forEach((mate, at) => {
	335	mate.job = jobs[at] ?? DEFAULT_JOB;
	336	mate.jobPlan = plan;
	337	mate.jobRound = world.match.round;
	338	// The wait runs from the moment the round goes live, and the freeze time is
	339	// still running: `botThink` pushes this forward on every frozen tick.
	340	mate.pushAt = world.time + mate.job.delay;
	341	// A goal cut for the site this bot is no longer going to is not a goal.
	342	mate.plannedFor = "";
	343	});
	344	return brain.job;
	345	}
	346
261	347	/** Where this bot is trying to be, given what the round is doing. */
262	348	function chooseGoal(world: World, bot: Player, brain: BotBrain): Vec3 {
263	349	const bomb = world.bomb;
264	350	const level = world.level;
265		const site = level.sites[brain.site];
	351	const job = brain.job;
	352	const site = level.sites[job.site];
266	353	if (bot.team === "t") {
267	354	if (bomb.state === "planted") {
268	355	// Hold near the bomb rather than walk onto it.
		@@ -270,10 +357,12 @@ function chooseGoal(world: World, bot: Player, brain: BotBrain): Vec3 {
270	357	}
271	358	if (bot.hasBomb) return site;
272	359	if (bomb.state === "dropped") return bomb.pos;
273		return nearby(level, brain, site, 200);
	360	// An entry walks onto the site; a lurker is happy five hundred units off
	361	// it, watching the way somebody would come. That is what a role is worth.
	362	return nearby(level, brain, site, job.spread * 0.8);
274	363	}
275	364	if (bomb.state === "planted") return bomb.pos;
276		return nearby(level, brain, site, 250);
	365	return nearby(level, brain, site, job.spread);
277	366	}
278	367
279	368	const nearby = (level: Level, brain: BotBrain, at: Vec3, spread: number): Vec3 => {
		@@ -466,7 +555,12 @@ export function botThink(world: World, bot: Player, dt: number): Input {
466	555	const input: Input = { ...NO_INPUT };
467	556	if (brain.reset) {
468	557	brain.reset = false;
469		brain.site = brain.random() < 0.5 ? "A" : "B";
	558	// The job a bot has when no round was planned for it: its own coin flip for
	559	// a site, no wait and the spread these bots have always used. A plan, if one
	560	// arrived, replaces this on the next line and for the rest of the round.
	561	brain.job = { ...DEFAULT_JOB, site: brain.random() < 0.5 ? "A" : "B" };
	562	brain.jobPlan = null;
	563	brain.pushAt = 0;
470	564	brain.goal = null;
471	565	brain.path = [];
472	566	brain.targetId = null;
		@@ -479,7 +573,12 @@ export function botThink(world: World, bot: Player, dt: number): Input {
479	573	brain.pull = [0, 0];
480	574	input.switchTo = bot.primary ?? bot.secondary;
481	575	}
	576	const job = jobOf(world, bot, brain);
482	577	if (world.match.phase === "freeze") {
	578	// Nobody moves in the freeze time, so a job's wait cannot start running
	579	// inside it: it is pushed along in front of the clock and starts the moment
	580	// the round goes live, which is the beat an entry is ahead by.
	581	brain.pushAt = world.time + job.delay;
483	582	return input;
484	583	}
485	584
		@@ -532,9 +631,21 @@ export function botThink(world: World, bot: Player, dt: number): Input {
532	631	return withBomb(world, bot, input);
533	632	}
534	633
	634	// --- waiting. A support does not walk out with the entry; it gives it its
	635	// beat and follows. The bomb never waits — a round where the bomb stands at
	636	// spawn for two seconds is two seconds off the clock — and neither does a bot
	637	// with something in front of it, because the fight above returned already.
	638	if (world.time < brain.pushAt && !bot.hasBomb && world.bomb.state === "carried") {
	639	if (brain.suspect !== null) {
	640	const look = aimAt(bot, brain.suspect);
	641	turnTowards(bot, { yaw: look.yaw, pitch: clamp(look.pitch, -20, 20) }, brain.aimSpeed * 0.5, dt);
	642	}
	643	return withBomb(world, bot, input);
	644	}
	645
535	646	// --- moving. A path is asked for when there is none, when it runs out, when
536	647	// it goes stale, or when the objective itself changed under the bot's feet.
537		const objective = `${world.bomb.state}:${brain.site}`;
	648	const objective = `${world.bomb.state}:${job.site}`;
538	649	const stale =
539	650	brain.path.length === 0 \|\| brain.step >= brain.path.length \|\|
540	651	world.time > brain.repathAt \|\| objective !== brain.plannedFor;
		@@ -40,6 +40,7 @@ import { WEAPONS } from "./weapons.ts";
40	40	import { matchOf } from "../matchid.ts";
41	41	import { parseResult } from "../result.ts";
42	42	import { fakeStage, ORIGIN, type FakeStage } from "./stage.test-helper.ts";
	43	import { parseSituation } from "../plan/situation.ts";
43	44	import { createWorld, type World } from "./world.ts";
44	45
45	46	/** Every frame booted here, so a stage can be asked what world it is running. */
		@@ -69,7 +70,9 @@ function painted(stage: FakeStage): FakeStage {
69	70
70	71	/** A booted page, its atlas painted, and the match already started on it. */
71	72	function playing(
72		options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
	73	options: {
	74	webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean; planEndpoint?: string;
	75	} = {},
73	76	): FakeStage {
74	77	const stage = painted(start(fakeStage(options)));
75	78	stage.by("play").fire("click");
		@@ -1234,3 +1237,38 @@ test("the match being played is on the page: the id, the map, the link and the p
1234	1237	expect(stage.by("mapname").textContent).toBe("de_forge");
1235	1238	expect(stage.by("share").attributes.href).toBe(`/?match=${PASTED}&map=de_forge`);
1236	1239	});
	1240
	1241	// --- the round's plan -------------------------------------------------------
	1242
	1243	test("a round is planned in the page, and the bots are a team from the first tick", () => {
	1244	const stage = playing();
	1245	stage.step(FRAME);
	1246	const world = worldOf(stage) as World;
	1247	const plan = world.plan;
	1248	expect(plan).not.toBeNull();
	1249	expect(plan?.source).toBe("local");
	1250	expect(plan?.round).toBe(world.match.round);
	1251	// The call is on the screen where a round's call belongs.
	1252	expect(world.messages[world.messages.length - 1]?.text).toContain(world.me.team.toUpperCase());
	1253	// A page that named no endpoint asks nobody: the only post is the result.
	1254	expect(stage.posts.filter((post) => post.url === "/api/plan")).toHaveLength(0);
	1255	});
	1256
	1257	test("a page that names a planner asks it, with the situation and nothing else", async () => {
	1258	const stage = playing({ planEndpoint: "/api/plan" });
	1259	stage.step(FRAME);
	1260	const posted = stage.posts.filter((post) => post.url === "/api/plan");
	1261	expect(posted).toHaveLength(1);
	1262	const sent = JSON.parse(String(posted[0]?.body)) as Record<string, unknown>;
	1263	expect(parseSituation(sent)).not.toBeNull();
	1264	expect(sent.round).toBe(1);
	1265	expect(Object.keys(sent).sort()).toEqual(["lastWinner", "map", "money", "round", "score"]);
	1266	expect(JSON.stringify(sent)).not.toContain("matchId");
	1267	// The stage answers every post with the leaderboard, which is not a plan: the
	1268	// local plan stays in force and the round is played on it.
	1269	await Promise.resolve();
	1270	stage.step(FRAME);
	1271	const world = worldOf(stage) as World;
	1272	expect(world.plan?.source).toBe("local");
	1273	expect(stepsRun(stage)).toBeGreaterThan(0);
	1274	});
		@@ -60,21 +60,23 @@ import {
60	60	import { generateLevel, seedFrom } from "./generate.ts";
61	61	import { mapFrom, mapLink, nameOf, seedOf, type MapChoice } from "../mapname.ts";
62	62	import { matchFrom, playKey } from "../matchid.ts";
	63	import { describe, localPlan, parsePlan, type RoundPlan } from "../plan/plan.ts";
	64	import type { Situation } from "../plan/situation.ts";
63	65	import { DE_FORGE } from "./map.ts";
64	66	import type { Level } from "./level.ts";
65	67	import { FOV, fovFor, lookAt } from "./look.ts";
66		import { COMPETITIVE, SHORT, type Rules } from "./match.ts";
	68	import { COMPETITIVE, SHORT, type Rules, type Team } from "./match.ts";
67	69	import { LAYERS, MATERIALS, TEX_SIZE } from "./materials.ts";
68	70	import { meshFor } from "./models.ts";
69	71	import { parsePacked } from "./packed.ts";
70	72	import { nextStep, type Answer } from "./pending.ts";
71	73	import { drawPreview, previewText } from "./preview.ts";
72	74	import { buildScene, createScene, SKY, type Scene } from "./scene.ts";
73		import { usePolicy } from "./bots.ts";
	75	import { usePlan, usePolicy } from "./bots.ts";
74	76	import { createSpectator, cycle, follow } from "./spectate.ts";
75	77	import { buyable, WEAPONS } from "./weapons.ts";
76	78	import { buy, canBuy, priceOf, type BuyItem } from "./economy.ts";
77		import { createWorld, eyePos, update, type Player, type World } from "./world.ts";
	79	import { createWorld, eyePos, say as showMessage, update, type Player, type World } from "./world.ts";
78	80	import { unpack } from "../engine/index.ts";
79	81
80	82	const TICK = 1 / 64;
		@@ -328,6 +330,14 @@ export function boot(host: Host): Frame {
328	330	// Where this game's weights are: the shell put the link in the head with the
329	331	// content-hashed URL on it, so this is the only place the path is known.
330	332	const weightsLink = doc.getElementById("weights") as Link \| null;
	333	/**
	334	* Where this deployment plans a round, if it plans one anywhere but here: the
	335	* `<meta>` the shell renders for an endpoint, read by its id, so no path to
	336	* this server is written into this file. A page that named none — every
	337	* deployment without a TypeSafe key — plans every round in the browser.
	338	*/
	339	const planMeta = doc.getElementById("botplan") as Link \| null;
	340	const planEndpoint = planMeta === null ? null : planMeta.getAttribute("content");
331	341	const resumeButton = by("resume");
332	342	// The line in the pause panel that says what Escape just did on this browser.
333	343	const escHint = by("esc");
		@@ -851,6 +861,7 @@ export function boot(host: Host): Frame {
851	861	pauseId.textContent = `Match ${matchId} on ${level.name}.`;
852	862	share.setAttribute("href", `/?match=${matchId}&map=${choice}`);
853	863	world = createWorld(level, rules, name, team, 5, seed);
	864	plannedRound = 0;
854	865	posted = -1;
855	866	loop.reset();
856	867	controls.sensitivity = clamp(Number(sensField.value) \|\| 2.2, 0.2, 12);
		@@ -908,6 +919,75 @@ export function boot(host: Host): Frame {
908	919	lastSound = current.time;
909	920	}
910	921
	922	/**
	923	* The round the bots have been planned for, and whether a request for a
	924	* better plan is in the air. Both are per match: a new world is round one
	925	* again, and `planFor` below is what puts the first plan in place before the
	926	* first freeze time is over.
	927	*/
	928	let plannedRound = 0;
	929	let planning = false;
	930
	931	/**
	932	* Plan the round about to be played. The local plan goes in at once, so the
	933	* bots are a team from the first tick whatever happens next; then, on a
	934	* deployment that named an endpoint for it, the same situation is put to the
	935	* server, which puts it to TypeSafe AI. Whatever comes back is validated
	936	* (`parsePlan`) and replaces the local one, and anything else — a refusal, a
	937	* 500, junk, a connection that died — leaves the local plan exactly where it
	938	* is. Nothing here is awaited by the frame.
	939	*/
	940	function planFor(current: World): void {
	941	const match = current.match;
	942	plannedRound = match.round;
	943	const situation: Situation = {
	944	map: mapFrom(current.level.name),
	945	round: match.round,
	946	score: { t: match.score.t, ct: match.score.ct },
	947	money: { t: teamMoney(current, "t"), ct: teamMoney(current, "ct") },
	948	lastWinner: match.winner,
	949	};
	950	const local = localPlan(situation);
	951	usePlan(current, local);
	952	announce(current, local);
	953	if (planEndpoint === null \|\| planning) return;
	954	planning = true;
	955	void (async (): Promise<void> => {
	956	try {
	957	const response = await host.fetch(planEndpoint, {
	958	method: "POST",
	959	headers: { "content-type": "application/json" },
	960	body: JSON.stringify(situation),
	961	});
	962	const plan = response.ok ? parsePlan(JSON.parse(await response.text())) : null;
	963	// A plan that arrived for a round that has already ended is last
	964	// round's plan: the bots keep the one they are playing.
	965	if (plan !== null && world === current && current.match.round === plan.round) {
	966	usePlan(current, plan);
	967	announce(current, plan);
	968	}
	969	} catch {
	970	// The local plan is already in force. A round is not lost because a
	971	// planner was.
	972	}
	973	planning = false;
	974	})();
	975	}
	976
	977	/** What each side has to spend, per player, which is what a plan is told. */
	978	const teamMoney = (current: World, team: Team): number => {
	979	const side = current.players.filter((p) => p.team === team);
	980	const total = side.reduce((sum, p) => sum + p.money, 0);
	981	return side.length === 0 ? 0 : Math.max(0, Math.min(16_000, Math.round(total / side.length)));
	982	};
	983
	984	/** The plan, in the words the HUD's message line shows for a few seconds. */
	985	const announce = (current: World, plan: RoundPlan): void => {
	986	// `say` in this file is the line by the leaderboard; this is the line in
	987	// the middle of the screen, which is where a round's call belongs.
	988	showMessage(current, describe(plan[current.me.team], current.me.team));
	989	};
	990
911	991	function frame(elapsed: number): void {
912	992	frameAverage += (elapsed * 1000 - frameAverage) * 0.05;
913	993	// One layer of the atlas per frame, and the browser has the rest of it: the
		@@ -933,6 +1013,10 @@ export function boot(host: Host): Frame {
933	1013	}
934	1014	if (world === null \|\| !running) return;
935	1015
	1016	// A round nobody has planned yet — the first of a match, or the one that
	1017	// just started — is planned here, on the frame that noticed it.
	1018	if (world.match.round !== plannedRound) planFor(world);
	1019
936	1020	const me = world.me;
937	1021	const [dx, dy] = controls.takeLook();
938	1022	if (me.alive && controls.locked) {
		@@ -107,6 +107,9 @@ export const ORIGIN = "https://cs.example";
107	107	*/
108	108	export const WEIGHTS_URL = "/static/weights.0123456789.json";
109	109
	110	/** The id of the meta that names where a round is planned, as the shell writes it. */
	111	export const PLAN_ID = "botplan";
	112
110	113	/** The committed policy document, which is the file the build copies to static/. */
111	114	const WEIGHTS_TEXT = readFileSync(join(import.meta.dir, "weights.json"), "utf8");
112	115
		@@ -232,10 +235,16 @@ export function fakeStage(
232	235	hold?: boolean;
233	236	/** Leave the `#weights` link off the page entirely: a page that named nothing. */
234	237	unlinked?: boolean;
	238	/**
	239	* The endpoint meta a deployment with a TypeSafe key renders: where the page
	240	* asks for a round to be planned. Absent is every other deployment, which
	241	* plans its rounds in the browser and posts nothing.
	242	*/
	243	planEndpoint?: string;
235	244	} = {},
236	245	): FakeStage {
237	246	const page = fakePage({
238		ids: PAGE_IDS,
	247	ids: options.planEndpoint === undefined ? PAGE_IDS : [...PAGE_IDS, PLAN_ID],
239	248	canvases: ["scene", "hud", "plan"],
240	249	hidden: HIDDEN,
241	250	actions: PAGE_ACTIONS,
		@@ -248,6 +257,8 @@ export function fakeStage(
248	257	// The link the shell renders in the head, with the content-hashed URL on it.
249	258	// `unlinked: true` leaves it blank: a page that named no weights at all.
250	259	if (options.unlinked !== true) page.by("weights").setAttribute("href", WEIGHTS_URL);
	260	// And the meta the shell renders for an endpoint, when this page has one.
	261	if (options.planEndpoint !== undefined) page.by(PLAN_ID).setAttribute("content", options.planEndpoint);
251	262	// The same switch on both sides of the seam: `webgl: false` is a browser with
252	263	// no context to give, whether the frame asks this page's `host` for a renderer
253	264	// or — as the committed bundle does — asks the canvas itself.
		@@ -22,6 +22,7 @@ import {
22	22	type Grenade, type GrenadeSound,
23	23	} from "./grenade.ts";
24	24	import type { Level } from "./level.ts";
	25	import type { RoundPlan } from "../plan/plan.ts";
25	26	import {
26	27	angleVectors, angleDelta, clamp, createEffects, dist, expireEffects, eyeHeight, hullHeight, move,
27	28	normalize, pushEffect, rng, sub, visible,
		@@ -173,6 +174,14 @@ export type World = {
173	174	grenades: Grenade[];
174	175	feed: FeedEntry[];
175	176	messages: { at: number; text: string }[];
	177	/**
	178	* The round these bots are playing, or null when nobody planned one. It hangs
	179	* on the world rather than in a module because a plan is one match's: the
	180	* arena's duels and the trainer's rounds are worlds nobody planned for, and a
	181	* plan left in a module would be last match's orders arriving in this one.
	182	* `src/client/bots.ts` puts it here (`usePlan`) and reads it back.
	183	*/
	184	plan: RoundPlan \| null;
176	185	random: () => number;
177	186	/**
178	187	* The map this round is played on, whole. Everything that needs to know where
		@@ -252,7 +261,7 @@ export function createWorld(
252	261	const world: World = {
253	262	match, players, me, time: 0,
254	263	bomb: newBomb(),
255		effects: createEffects<Effect>(EFFECT_CAPACITY), grenades: [], feed: [], messages: [],
	264	effects: createEffects<Effect>(EFFECT_CAPACITY), grenades: [], feed: [], messages: [], plan: null,
256	265	random, level, bombPlanted: false, pendingBuy: false,
257	266	};
258	267	startRound(world);
		@@ -317,7 +326,12 @@ export const alive = (world: World, team: Team): Player[] =>
317	326
318	327	export const eyePos = (p: Player): Vec3 => [p.pos[0], p.pos[1], p.pos[2] + eyeHeight(p, CS_HULL)];
319	328
320		function say(world: World, text: string): void {
	329	/**
	330	* A line in the middle of the screen for a few seconds. Exported because the
	331	* round's plan is announced the same way the round's start is: `src/client/main.ts`
	332	* says what the bots were told to do the moment they are told it.
	333	*/
	334	export function say(world: World, text: string): void {
321	335	world.messages.push({ at: world.time, text });
322	336	if (world.messages.length > 6) world.messages.shift();
323	337	}
		@@ -60,6 +60,16 @@ export type Game = {
60	60	/**
61	61	* In the order the header lists them, which is also the order they are built.
62	62	*
	63	* #228 gave the bots a round to play rather than five separate ones — a site, a
	64	* shape, a tempo and a save per side, and a job per bot cut from it — and the
	65	* app grew 3,804 raw bytes for it (92,978 raw / 36,716 gzipped now): `src/plan/plan.ts` (the plan,
	66	* the jobs and the parser, all of which ship), the situation the page sends, and
	67	* the wiring in the entry that asks for one a round. It fits today's 98,000 /
	68	* 39,000 with 5,022 raw and 2,284 gzipped bytes to spare, so no ceiling moved.
	69	* The planner itself — `src/plan/typesafe.ts` and `@typesafe-ai/sdk` — is behind
	70	* the door like the trainer and the digest: it holds the key, it runs on the
	71	* server, and no bundle gained a byte of it. The range and the example are
	72	* unchanged to the byte: they have no bots to plan for. Measured 2026-09-21.
63	73	* The ceilings are today's sizes plus about 10%, rounded up to a round number:
64	74	* enough headroom that an honest feature lands without a ceiling edit, tight
65	75	* enough that a stray import of something large trips the test. Measured