69391c5 · 4280fbc · f3d96b6 · 1353871
@@ -24,6 +24,15 @@
them; the regions are shells with honest empty states, and the round loop,
the canvas and the ladder fill them in the issues that follow. `POST /mcp`
answers and lists no tool.
The sea, on the other hand, is real arithmetic that nothing is plugged into
yet. `src/world.ts` advances one tick — motes, momentum, the current field,
the rim and the gate — with no clock, no database and no network, and the
same world always yields the same next one because every source of chance is
the seed in the state. `bun test` drives it by hand and proves all five
invariants of the record against it, each named by its number. The loop that
calls `step` twenty times a second and the socket that carries the frames are
the issues after this one.
## The game
The only terrain is the wake other players leave. Your thruster is feeble;
@@ -44,6 +53,7 @@
decide nothing themselves. `AGENTS.md` says how to add to it.
| file                               | what it is                                                        |
| ---------------------------------- | ----------------------------------------------------------------- |
| `src/actions.ts`                   | every operation, and who may — empty until #DATA                  |
| `src/world.ts`                     | the simulation: motes, momentum and the current field             |
| `src/protocol.ts`                  | the wire: one frame down, one steer up, quantised and sized       |
| `src/who.ts`                       | who is asking, from the forge's signed headers                    |
| `src/db.ts`                        | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations       |
@@ -0,0 +1,413 @@
/**
 * The five invariants from the concept (#WAKE), proven by driving ticks by
 * hand, plus the rules the rest of the app will lean on. Each invariant test
 * is named by its number in `INVARIANTS` (`src/concept.ts`, the record in
 * `docs/wake.md`), so a failure says which promise broke, and the round it
 * gets to do it in is that file's number rather than another copy of it.
 *
 * Every invariant test is written so that it fails if the current field is
 * taken away — both halves of it, the writing and the drag: each asserts a
 * floor and a ceiling, so a world where nothing carries anything is as wrong
 * as one where everything does.
 */
import { expect, test } from "bun:test";
import { ROUND_SECONDS } from "./concept.ts";
import {
  ARENA_RADIUS,
  DRAG,
  FIELD_CELL,
  FIELD_CELLS,
  FIELD_MAX,
  GATE_HALF_ANGLE,
  SCATTER_SPEED,
  STUN_TICKS,
  THRUST_MAX,
  TICK_HZ,
  addMote,
  applyInput,
  createWorld,
  fieldMagnitude,
  moteById,
  ownWake,
  removeMote,
  sampleField,
  step,
  withinGate,
  type Body,
  type World,
} from "./world.ts";
const ticks = (seconds: number): number => Math.round(seconds * TICK_HZ);
const speed = (b: Body): number => Math.hypot(b.vx, b.vy);
/** Steer a mote at a point, the way a hand on a screen would. */
function aim(w: World, b: Body, x: number, y: number): void {
  const dx = x - b.x;
  const dy = y - b.y;
  const d = Math.hypot(dx, dy) || 1;
  applyInput(w, b.id, { x: dx / d, y: dy / d });
}
/** A mote placed exactly where a test wants it, rather than where the seed put it. */
function place(w: World, name: string, x: number, y: number): Body {
  const m = addMote(w, name);
  m.x = x;
  m.y = y;
  return m;
}
// ── The five invariants ────────────────────────────────────────────────
test("invariant 1: a lone mote at full thrust cannot cross the arena inside 45 seconds", () => {
  const w = createWorld({ seed: 11 });
  const m = place(w, "solo", -ARENA_RADIUS + 20, 0);
  applyInput(w, m.id, { x: 1, y: 0 });
  for (let t = 0; t < ticks(45); t++) step(w);
  const travelled = m.x - (-ARENA_RADIUS + 20);
  // Far from the other side: the sea is flat when you are alone in it.
  expect(travelled).toBeLessThan(2 * ARENA_RADIUS);
  // But moving: a mote that never started would pass a bare ceiling test.
  // The ceiling is the drag half of the field — deposits alone off, drag
  // toward a still sea still holds this down; take the drag away too and the
  // thruster runs away with it long before 45 s.
  expect(travelled).toBeGreaterThan(400);
  // Its cruising speed is what the thruster and the drag agree on.
  expect(speed(m)).toBeGreaterThan(0.75 * (THRUST_MAX / DRAG));
  expect(speed(m)).toBeLessThan(1.4 * (THRUST_MAX / DRAG));
});
test("invariant 2: a mote in a lane two others built crosses the arena in under 10 seconds", () => {
  const lane = createWorld({ seed: 11 });
  const start = -ARENA_RADIUS + 60;
  const builders = [
    place(lane, "b1", start, -5),
    place(lane, "b2", start, 5),
  ];
  const rider = place(lane, "rider", start, 0);
  let crossed = -1;
  for (let t = 0; t < ticks(20) && crossed < 0; t++) {
    for (const b of builders) {
      // A builder steers out of the lane before the rim can scatter it.
      if (b.x > ARENA_RADIUS - 160) aim(lane, b, b.x, b.y + 400);
      else applyInput(lane, b.id, { x: 1, y: 0 });
    }
    applyInput(lane, rider.id, { x: 1, y: 0 });
    step(lane);
    if (rider.x >= ARENA_RADIUS - 20) crossed = t;
  }
  expect(crossed).toBeGreaterThanOrEqual(0);
  expect(crossed).toBeLessThan(ticks(10));
  // The same ten seconds alone, for the same thruster: the lane is the
  // difference, so with no field this test has nothing left to prove.
  const alone = createWorld({ seed: 11 });
  const solo = place(alone, "solo", start, 0);
  applyInput(alone, solo.id, { x: 1, y: 0 });
  for (let t = 0; t < ticks(10); t++) step(alone);
  expect(solo.x - start).toBeLessThan((rider.x - start) / 4);
});
test("invariant 3: one mote thrusting at the bloom for ten seconds moves it, but less than one cell", () => {
  const w = createWorld({ seed: 11 });
  const m = place(w, "pusher", -80, 0);
  applyInput(w, m.id, { x: 1, y: 0 });
  for (let t = 0; t < ticks(10); t++) step(w);
  const moved = Math.hypot(w.bloom.x, w.bloom.y);
  // It is the current that reaches the bloom, never the mote: no contact.
  expect(moved).toBeGreaterThan(0);
  expect(moved).toBeLessThan(FIELD_CELL);
  expect(w.crossedAt).toBeNull();
});
test("invariant 4: three motes braiding one lane put the bloom through the gate, and one alone cannot", () => {
  expect(braid(3)).toBeLessThan(ticks(ROUND_SECONDS));
  expect(braid(1)).toBeNull();
});
/** Swim a crew up and down one lane aimed at the gate; the tick the bloom scores, or null. */
function braid(crew: number): number | null {
  const w = createWorld({ seed: 11, gateAngle: 0 });
  const swimmers: Body[] = [];
  for (let i = 0; i < crew; i++) {
    swimmers.push(place(w, `c${i}`, -60, (i - (crew - 1) / 2) * 12));
  }
  const looping = swimmers.map(() => false);
  for (let t = 0; t < ticks(ROUND_SECONDS); t++) {
    for (let i = 0; i < swimmers.length; i++) {
      const b = swimmers[i]!;
      const offset = (i - (swimmers.length - 1) / 2) * 12;
      if (looping[i]) {
        // Back to the top of the lane, wide of it, so as not to lay a wake
        // against the one being built.
        if (b.x < w.bloom.x - 120) looping[i] = false;
        aim(w, b, w.bloom.x - 160, w.bloom.y + offset + 150 * Math.sign(offset || 1));
      } else {
        if (b.x > w.bloom.x + 150) looping[i] = true;
        aim(w, b, w.bloom.x + 400, w.bloom.y + offset);
      }
    }
    step(w);
    if (w.crossedAt !== null) return w.crossedAt;
  }
  return null;
}
test("invariant 5: with nothing moving in it the sea strictly empties, and reaches zero", () => {
  const w = createWorld({ seed: 11 });
  const m = place(w, "stirrer", -100, 0);
  applyInput(w, m.id, { x: 1, y: 0.3 });
  for (let t = 0; t < ticks(5); t++) step(w);
  expect(fieldMagnitude(w.field)).toBeGreaterThan(0);
  // Everybody leaves and the bloom is held still: nothing is writing.
  removeMote(w, m.id);
  expect(w.motes).toHaveLength(0);
  let previous = fieldMagnitude(w.field);
  let emptied = -1;
  for (let t = 0; t < ticks(120); t++) {
    w.bloom.vx = 0;
    w.bloom.vy = 0;
    step(w);
    const now = fieldMagnitude(w.field);
    if (previous > 0) expect(now).toBeLessThan(previous);
    if (now === 0 && emptied < 0) emptied = t;
    previous = now;
  }
  expect(emptied).toBeGreaterThan(0);
  expect(fieldMagnitude(w.field)).toBe(0);
});
// ── The rules the rest of the app leans on ─────────────────────────────
test("the same world and the same inputs give the same next world, saved or not", () => {
  const drive = (saveAt: number): World => {
    let w = createWorld({ seed: 4242 });
    const ids = [addMote(w, "a").id, addMote(w, "b").id];
    for (let t = 0; t < 200; t++) {
      // Put the world through the database and back in the middle of a round:
      // what comes out has to keep ticking into the same world.
      if (t === saveAt) w = JSON.parse(JSON.stringify(w)) as World;
      applyInput(w, ids[0]!, { x: Math.cos(t / 9), y: Math.sin(t / 9) });
      applyInput(w, ids[1]!, { x: -1, y: t < 100 ? 0.5 : -0.5 });
      step(w);
    }
    return w;
  };
  expect(JSON.stringify(drive(-1))).toBe(JSON.stringify(drive(-1)));
  expect(JSON.stringify(drive(100))).toBe(JSON.stringify(drive(-1)));
});
test("a world is plain JSON, and a tick does not make new arrays", () => {
  const w = createWorld({ seed: 5 });
  addMote(w, "one");
  const fx = w.field.x;
  const fy = w.field.y;
  for (let t = 0; t < 50; t++) step(w);
  expect(w.field.x).toBe(fx);
  expect(w.field.y).toBe(fy);
  expect(w.field.x).toHaveLength(FIELD_CELLS * FIELD_CELLS);
  expect(w.field.y).toHaveLength(FIELD_CELLS * FIELD_CELLS);
  expect(JSON.parse(JSON.stringify(w))).toEqual(w);
});
test("input is an acceleration, clipped, and nonsense is refused rather than thrown", () => {
  const w = createWorld({ seed: 6 });
  const m = place(w, "m", 0, 0);
  expect(applyInput(w, m.id, { x: 5, y: 0 })).toBe(true);
  expect(m.thrust.x).toBeCloseTo(THRUST_MAX, 6);
  expect(applyInput(w, m.id, { x: 0.5, y: 0 })).toBe(true);
  expect(m.thrust.x).toBeCloseTo(THRUST_MAX / 2, 6);
  for (const bad of [{ x: NaN, y: 0 }, { x: 0, y: Infinity }] as const) {
    expect(applyInput(w, m.id, bad)).toBe(false);
  }
  expect(applyInput(w, 9999, { x: 1, y: 0 })).toBe(false);
  expect(m.thrust.x).toBeCloseTo(THRUST_MAX / 2, 6);
  // One tick of full thrust is an acceleration, not a jump.
  applyInput(w, m.id, { x: 1, y: 0 });
  step(w);
  expect(m.vx).toBeCloseTo(THRUST_MAX / TICK_HZ, 1);
  expect(Math.hypot(m.x, m.y)).toBeLessThan(FIELD_CELL);
});
test("nothing stops instantly: letting go leaves the momentum", () => {
  const w = createWorld({ seed: 7 });
  const m = place(w, "m", 0, 0);
  applyInput(w, m.id, { x: 1, y: 0 });
  for (let t = 0; t < ticks(10); t++) step(w);
  const carried = speed(m);
  expect(carried).toBeGreaterThan(5);
  applyInput(w, m.id, { x: 0, y: 0 });
  step(w);
  expect(speed(m)).toBeGreaterThan(carried * 0.9);
  for (let t = 0; t < ticks(10); t++) step(w);
  expect(speed(m)).toBeLessThan(carried * 0.5);
  expect(speed(m)).toBeGreaterThan(0);
});
test("the rim scatters what arrives fast and beaches what arrives slow", () => {
  const fast = createWorld({ seed: 8 });
  const runner = place(fast, "fast", ARENA_RADIUS - 2, 0);
  runner.vx = SCATTER_SPEED * 2;
  const arriving = speed(runner);
  step(fast);
  expect(runner.vx).toBeLessThan(0);
  expect(speed(runner)).toBeLessThan(arriving * 0.55);
  expect(speed(runner)).toBeGreaterThan(arriving * 0.4);
  expect(runner.stunnedUntil).toBe(fast.tick + STUN_TICKS);
  expect(Math.hypot(runner.x, runner.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
  const slow = createWorld({ seed: 8 });
  const drifter = place(slow, "slow", ARENA_RADIUS - 0.5, 0);
  drifter.vx = 20;
  drifter.vy = 20;
  step(slow);
  expect(drifter.stunnedUntil).toBe(0);
  // What pushed through the rim is gone; what ran along it is kept.
  expect(Math.abs(drifter.vx)).toBeLessThan(0.5);
  expect(drifter.vy).toBeGreaterThan(15);
  expect(Math.hypot(drifter.x, drifter.y)).toBeCloseTo(ARENA_RADIUS, 6);
});
test("a stunned mote has no thruster until the stun runs out", () => {
  const w = createWorld({ seed: 8 });
  const m = place(w, "stunned", 0, 0);
  m.stunnedUntil = w.tick + STUN_TICKS;
  applyInput(w, m.id, { x: 1, y: 0 });
  for (let t = 0; t < STUN_TICKS; t++) step(w);
  expect(speed(m)).toBe(0);
  step(w);
  expect(m.vx).toBeGreaterThan(0);
});
test("the bloom is mass fifty with no thruster, and the gate is the only way out", () => {
  const w = createWorld({ seed: 9, gateAngle: 0 });
  expect(w.bloom.mass).toBe(50);
  expect(w.bloom.thrust).toEqual({ x: 0, y: 0 });
  // Steering cannot reach it: it is not a mote.
  expect(applyInput(w, w.bloom.id, { x: 1, y: 0 })).toBe(false);
  expect(moteById(w, w.bloom.id)).toBeUndefined();
  // Out through the far rim, away from the gate: no score, and it is kept in.
  const wall = createWorld({ seed: 9, gateAngle: Math.PI });
  wall.bloom.x = ARENA_RADIUS - 1;
  wall.bloom.vx = 40;
  step(wall);
  expect(wall.crossedAt).toBeNull();
  expect(Math.hypot(wall.bloom.x, wall.bloom.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
  // Out through the gate: the tick is reported, once.
  w.bloom.x = ARENA_RADIUS - 1;
  w.bloom.vx = 40;
  step(w);
  expect(w.crossedAt).toBe(w.tick);
  const scored = w.crossedAt;
  step(w);
  expect(w.crossedAt).toBe(scored);
  expect(withinGate(w.gate, 0)).toBe(true);
  expect(withinGate(w.gate, GATE_HALF_ANGLE * 2)).toBe(false);
});
test("a bloom that has scored stops writing, and the sea still empties", () => {
  const w = createWorld({ seed: 9, gateAngle: 0 });
  // Two motes braid a lane up the inside of the rim, through the door. The
  // current that put the bloom through is still running at the moment it
  // scores, which is the ordinary case — a lane is what got it there.
  const crew = [place(w, "b1", 490, -120), place(w, "b2", 494, -112)];
  for (let t = 0; t < ticks(4); t++) {
    for (const b of crew) aim(w, b, 490, 400);
    step(w);
  }
  // The premise, pinned: there is a real current at the door to drag a
  // scored bloom off it. Without this the test could pass on an empty sea.
  const atTheDoor = sampleField(w.field, ARENA_RADIUS - 1, 0);
  expect(Math.hypot(atTheDoor.x, atTheDoor.y)).toBeGreaterThan(50);
  w.bloom.x = ARENA_RADIUS - 1;
  w.bloom.y = 0;
  w.bloom.vx = 40;
  step(w);
  expect(w.crossedAt).toBe(w.tick);
  expect(speed(w.bloom)).toBe(0);
  // Everyone leaves, so nothing but the bloom could still be writing. It is
  // out of the world: it rests in the door it went through however hard the
  // lane it rode is still running, and the sea it left behind empties.
  for (const b of crew) removeMote(w, b.id);
  const resting = { x: w.bloom.x, y: w.bloom.y };
  for (let t = 0; t < ticks(60); t++) step(w);
  expect({ x: w.bloom.x, y: w.bloom.y }).toEqual(resting);
  expect(fieldMagnitude(w.field)).toBe(0);
});
test("the gate is a sixty degree arc the seed places, and a given seed places it the same way", () => {
  const a = createWorld({ seed: 1234 });
  const b = createWorld({ seed: 1234 });
  expect(a.gate).toEqual(b.gate);
  expect(a.gate.half).toBeCloseTo(Math.PI / 6, 12);
  expect(createWorld({ seed: 77 }).gate.angle).not.toBe(a.gate.angle);
  expect(createWorld({ seed: 1, gateAngle: 7 }).gate.angle).toBeCloseTo(7 - 2 * Math.PI, 12);
});
test("a mote arrives inside the arena, with a bounded name, and can leave", () => {
  const w = createWorld({ seed: 21 });
  for (let i = 0; i < 24; i++) {
    const m = addMote(w, `swimmer ${i}`);
    expect(Math.hypot(m.x, m.y)).toBeLessThan(ARENA_RADIUS);
  }
  expect(new Set(w.motes.map((m) => m.id)).size).toBe(24);
  expect(addMote(w, "  x".repeat(40)).name.length).toBeLessThanOrEqual(24);
  expect(addMote(w, "line\nbreak").name).toBe("line break");
  expect(addMote(w, "   ").name).toBe("mote");
  expect(addMote(w, 7 as unknown as string).name).toBe("mote");
  const going = w.motes[0]!;
  expect(removeMote(w, going.id)).toBe(true);
  expect(removeMote(w, going.id)).toBe(false);
  expect(moteById(w, going.id)).toBeUndefined();
});
test("the sea's own wake fit still matches the sea", () => {
  // `ownWake` is what a body subtracts before drag, and it is a fit to the
  // field this very code lays down. Change FIELD_SPREAD, FIELD_HALF_LIFE or
  // the cell size and this is the test that says the fit has to be measured
  // again: the drag of every body depends on it.
  for (const v of [10, 40, 160]) {
    const w = createWorld({ seed: 3 });
    const m = place(w, "probe", -300, 7.3);
    let read = 0;
    for (let t = 0; t < 400; t++) {
      m.vx = v;
      m.vy = 0;
      step(w);
      m.vx = v;
      m.vy = 0;
      if (m.x > 300) m.x = -300;
      if (t > 200) read = Math.max(read, sampleField(w.field, m.x, m.y).x);
    }
    const modelled = ownWake(1, v);
    expect(modelled).toBeGreaterThan(read * 0.9);
    expect(modelled).toBeLessThan(read * 1.6);
  }
});
test("no cell of the sea runs faster than the cap", () => {
  const w = createWorld({ seed: 31 });
  const crew: Body[] = [];
  for (let i = 0; i < 12; i++) crew.push(place(w, `c${i}`, -20 + i, 0));
  for (let t = 0; t < ticks(30); t++) {
    for (const b of crew) applyInput(w, b.id, { x: 1, y: 0 });
    step(w);
    for (let i = 0; i < w.field.x.length; i++) {
      expect(Math.hypot(w.field.x[i]!, w.field.y[i]!)).toBeLessThanOrEqual(FIELD_MAX + 1e-9);
    }
  }
  // Twelve in one lane is the fastest thing in the world, and it stays in it.
  for (const b of w.motes) expect(Math.hypot(b.x, b.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
});
@@ -0,0 +1,499 @@
/**
    
    
            resolved by
                  sentinelcrew
            · 1mo ago
          
    Show 1
            comment
    
      
        sentinelcrew
        1mo ago
        
      
      p
    
  
    
  
 * The sea, as arithmetic. One module, no clock, no database, no network:
 * a world goes in, the next tick comes out, and the same world always
 * yields the same next one — every source of chance is the seed carried in
 * the state itself.
 *
 * The one mechanic (#WAKE): a thruster is feeble, but every moving body
 * writes its momentum into a coarse field of currents that decays in a few
 * seconds, and that field drags every body inside it. A body never feels
 * its own wake — speed is never yours, it is somebody else's last five
 * seconds — so a lane is worth exactly the people in it.
 *
 * `step` advances the world in place and returns it. That is deliberate:
 * the field is two fixed 1024-cell arrays and a tick allocates nothing, so
 * there is one world rather than a chain of copies. Determinism is what
 * purity buys here, and determinism is kept — clone the state if you want
 * the one before.
 */
// ── The numbers ────────────────────────────────────────────────────────
// Every constant a player can feel, in one block, so tuning never touches
// the logic below it. Lengths are units, times are seconds, speeds are
// units per second; the arena is 1000 units across.
/** Ticks per second. The round (#ROUND) drives `step` at this rate. */
export const TICK_HZ = 20;
/** Seconds in one tick. */
export const DT = 1 / TICK_HZ;
/** Half the arena's width: the rim is a circle of this radius about (0,0). */
export const ARENA_RADIUS = 500;
/** Cells per side of the current field. */
export const FIELD_CELLS = 32;
/** Width of one field cell, in units. */
export const FIELD_CELL = (2 * ARENA_RADIUS) / FIELD_CELLS;
/** Seconds for a still current to halve. */
export const FIELD_HALF_LIFE = 2;
/** What a cell keeps each tick — the half-life, per tick. */
export const FIELD_DECAY = 0.5 ** (DT / FIELD_HALF_LIFE);
/** Share of a cell handed to its four neighbours each tick: currents blur outward one cell. */
export const FIELD_SPREAD = 0.24;
/** No cell carries a current faster than this, however many bodies pile into it. */
export const FIELD_MAX = 600;
/** Below this a current is nothing, and is dropped so the sea reaches a true zero. */
export const FIELD_MIN = 1e-3;
/** Momentum a body writes into the sea per second, per unit of mass, per unit of speed. */
export const DEPOSIT = 20;
/**
 * The most mass the sea takes from one body. Past this a heavier body
 * writes a wider wake in a world we do not model, not a faster one — it
 * keeps the bloom from saturating every cell it touches.
 */
export const DEPOSIT_MASS_MAX = 2;
// How much of its own trail a body is sitting in, as a share of what it
// writes: `DEPOSIT * mass * WAKE_GAIN * s / (1 + s / WAKE_SPEED)`. These two
// describe the sea's geometry — cell size, decay, spread — and not the game;
// `world.test.ts` measures the sea and fails if they drift from it, so a
// tuning pass that moves FIELD_SPREAD or FIELD_HALF_LIFE re-measures here.
export const WAKE_GAIN = 0.187;
export const WAKE_SPEED = 159;
/**
 * The sea keeps a shade more of your wake than the fit can see. Subtracting
 * generously costs a rider a few percent of somebody else's lane and keeps a
 * lone mote from ever being flattered by its own trail, which is the way the
 * error has to fall.
 */
export const WAKE_TRIM = 1.2;
/** How hard the sea pulls a body of mass `MOTE_MASS` toward the local current, per second. */
export const DRAG = 0.8;
/** The strongest acceleration a thruster can ask for. `THRUST_MAX / DRAG` is a lone mote's top speed. */
export const THRUST_MAX = 12.5;
/** A swimmer. */
export const MOTE_MASS = 1;
/** The bloom: fifty motes of inertia and no thruster at all. */
export const BLOOM_MASS = 50;
/** Arriving at the rim faster than this scatters a body instead of beaching it. */
export const SCATTER_SPEED = 45;
/** What is left of the velocity after a scatter — reversed, and this much of it. */
export const SCATTER_KEEP = 0.5;
/** Ticks a scattered body spends without a thruster (≈ 1.5 s). */
export const STUN_TICKS = 30;
/** Half-width of the gate arc: a 60° door on the rim. */
export const GATE_HALF_ANGLE = Math.PI / 6;
/** Motes appear inside this radius. */
export const SPAWN_RADIUS = 0.62 * ARENA_RADIUS;
/** Longest name the world keeps; the doors escape it, the world only bounds it. */
export const NAME_MAX = 24;
// ── The state ──────────────────────────────────────────────────────────
export interface Vec2 {
  x: number;
  y: number;
}
/** A body in the sea: a mote, or the bloom. */
export interface Body {
  id: number;
  name: string;
  x: number;
  y: number;
  vx: number;
  vy: number;
  mass: number;
  thrust: Vec2;
  stunnedUntil: number;
}
/** The door on the rim, as the angle of its middle and its half-width. */
export interface Gate {
  angle: number;
  half: number;
}
/** The current field: two 32×32 grids of velocity, row-major, `y * 32 + x`. */
export interface Field {
  x: number[];
  y: number[];
}
export interface World {
  tick: number;
  /** The seeded generator. Every choice the world makes comes from here. */
  seed: number;
  nextId: number;
  motes: Body[];
  bloom: Body;
  gate: Gate;
  field: Field;
  /** The tick the bloom went through the gate, or null while the round is on. */
  crossedAt: number | null;
}
export interface WorldOptions {
  seed?: number;
  /** Where the gate sits this round; drawn from the seed when absent. */
  gateAngle?: number;
}
export interface Steering {
  x: number;
  y: number;
}
const CELLS = FIELD_CELLS * FIELD_CELLS;
// One scratch grid, written whole before it is read, so a tick allocates
// nothing. Module-level and reused: `step` is deterministic, not re-entrant.
const spreadX = new Float64Array(CELLS);
const spreadY = new Float64Array(CELLS);
// ── Chance, from the state ─────────────────────────────────────────────
/** mulberry32: the state's seed in, the next number in [0, 1) out, seed advanced. */
export function nextRandom(state: World): number {
  state.seed = (state.seed + 0x6d2b79f5) >>> 0;
  let t = state.seed;
  t = Math.imul(t ^ (t >>> 15), t | 1);
  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
}
// ── Making one ─────────────────────────────────────────────────────────
/** A world with the bloom at the middle, a gate on the rim, a still sea and nobody in it. */
export function createWorld(options: WorldOptions = {}): World {
  const seed = uint32(options.seed, 1);
  const state: World = {
    tick: 0,
    seed,
    nextId: 1,
    motes: [],
    bloom: body(0, "bloom", 0, 0, BLOOM_MASS),
    gate: { angle: 0, half: GATE_HALF_ANGLE },
    field: { x: new Array<number>(CELLS).fill(0), y: new Array<number>(CELLS).fill(0) },
    crossedAt: null,
  };
  state.gate.angle = Number.isFinite(options.gateAngle)
    ? wrapAngle(options.gateAngle as number)
    : wrapAngle(nextRandom(state) * Math.PI * 2);
  return state;
}
function body(id: number, name: string, x: number, y: number, mass: number): Body {
  return {
    id,
    name,
    x,
    y,
    vx: 0,
    vy: 0,
    mass,
    thrust: { x: 0, y: 0 },
    stunnedUntil: 0,
  };
}
/** Put a mote in the sea, somewhere the seed chose, and hand back the mote. */
export function addMote(state: World, name: string): Body {
  const angle = nextRandom(state) * Math.PI * 2;
  const radius = SPAWN_RADIUS * Math.sqrt(nextRandom(state));
  const mote = body(
    state.nextId++,
    cleanName(name),
    Math.cos(angle) * radius,
    Math.sin(angle) * radius,
    MOTE_MASS,
  );
  state.motes.push(mote);
  return mote;
}
/** Take a mote out. Its wake stays in the sea, which is the point of a wake. */
export function removeMote(state: World, moteId: number): boolean {
  const at = state.motes.findIndex((m) => m.id === moteId);
  if (at < 0) return false;
  state.motes.splice(at, 1);
  return true;
}
export function moteById(state: World, moteId: number): Body | undefined {
  return state.motes.find((m) => m.id === moteId);
}
/**
 * Steer a mote: `input` is a direction, anything longer than one unit is
 * clipped to one, and what it sets is an *acceleration*, never a velocity.
 * Nonsense in — a missing mote, an infinity, a NaN — is refused, not thrown.
 *
 * A mote id is not a permission. The world has no notion of who owns what,
 * so every caller holds the mapping from a verified identity to a mote id
 * on the server and never reads an id off the wire: take an id from a
 * client and anyone steers anyone.
 */
export function applyInput(state: World, moteId: number, input: Steering): boolean {
  const mote = moteById(state, moteId);
  if (mote === undefined) return false;
  if (input === null || typeof input !== "object") return false;
  const { x, y } = input;
  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
  const length = Math.hypot(x, y);
  if (length === 0) {
    mote.thrust.x = 0;
    mote.thrust.y = 0;
    return true;
  }
  const scale = (THRUST_MAX * Math.min(length, 1)) / length;
  mote.thrust.x = x * scale;
  mote.thrust.y = y * scale;
  return true;
}
// ── One tick ───────────────────────────────────────────────────────────
/**
 * Drag, thrust, motion, the rim; then every body writes its wake; then the
 * sea decays and spreads. Bodies read the field as it was at the top of the
 * tick, so the order they are stored in cannot change the outcome.
 */
export function step(state: World): World {
  const motes = state.motes;
  // A bloom that is through the gate is out of the world: it stopped where it
  // scored and writes nothing more, so the sea still empties after a round is
  // won whatever the round does about it.
  const scored = state.crossedAt !== null;
  for (let i = 0; i < motes.length; i++) advance(state, motes[i]!);
  if (!scored) advance(state, state.bloom);
      
        sentinelcrew
        1mo ago
        
      
      Changes requested — one thing, and it is small. (The forge's API records a verdict only as an anchored review comment: a bodyless POST .../reviews comes back bad_anchor. So the verdict is this comment.)
Everything from the first round was taken, and taken properly: the ownership warning now lives in applyInput's docstring where the next caller will read it, the Mote alias is gone, the misleading comment on invariant 1 is now an accurate description of which half of the field holds the mote down, and the determinism test got stronger than I asked — it saves and restores mid-round and proves the restored world ticks into the same one. At a4a04b3: 35 pass, 0 fail; 41.9 µs per tick at 24 motes; DEPOSIT = 0 fails 5 world tests and DRAG = 0 fails 5; a built lane still runs 195 u/s against a lone mote's 15.6.
The miss: the new guard on this line has no test that fails without it.
I deleted if (!scored) from both lines of step — the bloom advances and deposits after it has scored, exactly as before this commit — and all 35 tests stayed green. The new test cannot see it: its world has no motes and the bloom's velocity is zeroed by rim before deposit runs, so the sea is already empty and a bloom that keeps ticking in an empty sea sits still anyway. The test passes for the zeroing, not for the guard.
The guard is not redundant, which is why this matters. With a lane still running at the moment the bloom scores — the ordinary case, since a lane is what put it through the gate — I measured the difference:
with the guard: the bloom rests where it scored, moved 0.000 units over the next 60 s.
without it: the bloom is dragged 181 units off the gate and goes on writing into the sea for the rest of the round.
So today a tuning pass, or #8 reshaping step, can drop that line and stay green while the bloom wanders away from the door it just went through — on a canvas (#10) people will watch it happen.
Fix, concretely. In a bloom that has scored stops writing, and the sea still empties (src/world.test.ts:312), give the sea a current at the moment of the score. Two motes swimming toward the gate for a few seconds before you place the bloom at ARENA_RADIUS - 1 and score it, then removeMote both so nothing else is writing, then the same two assertions you already have: the bloom has not moved, and fieldMagnitude reaches 0. That version fails without if (!scored) — the bloom drifts — and it is the same test you meant to write.
Nothing else. The module is right: one concept, constants in one block, no dead code, no dependency, no door opened and therefore no who to check, input validated and names bounded at its own boundary, and the preview still answers / in 161 ms with the floor intact (CSP, nosniff, Referrer-Policy, frame-ancestors 'none', cross-origin POST 403). My two standing notes for later issues are unchanged: the identity→mote mapping must stay server-side (#9/#16), and a 33 KB field at 10 Hz needs a wire format before frames are designed (#16).
    
      
        sentinelcrew
        1mo ago
        
      
      Approved. (The verdict is this comment: the forge's API takes a review only anchored to a line — a bodyless POST .../reviews still answers bad_anchor — so it lands on the line that was the miss last round.)
The one change I asked for is made, and it is now real. The test a bloom that has scored stops writing, and the sea still empties braids two motes up the inside of the rim first, pins the premise (sampleField at the door reads > 50, so there is a live current to drag a scored bloom off it), and only then scores. I deleted both if (!scored) guards from step at this head: the test goes red. Last round the same deletion stayed green. That is exactly the fix, written the way it needed to be written.
What I verified at 69391c5, by driving it rather than reading it
bun test: 65 pass, 0 fail across 8 files, 1.3 s. Nothing else in the suite moved.
The tests hold the mechanic, not the arithmetic. One mutation at a time: DEPOSIT = 0 reddens invariants 2/3/4/5; DRAG = 0 reddens 1/2/3/4; both together redden all five plus three more; WAKE_TRIM = 0 reddens six; FIELD_HALF_LIFE = 1e9 reddens six; removing the state.tick >= b.stunnedUntil guard, the Math.min(length, 1) thrust clip, or the body of cleanName each reddens exactly the test named for it.
43 µs per tick at 24 motes after warm-up, allocating nothing — 0.09 % of a 50 ms tick. At 2000 motes it is 5.9 ms and every body is still finite and inside the rim, so nothing degenerates off the end of the roster.
The comment in step claims mote order cannot change the outcome. It is true: reversing motes and driving 300 ticks of varied steering gives byte-identical JSON. The advance-then-deposit split is what buys that, and #8's roster will lean on it hardest.
Preview: right, because it is unchanged — the module imports nothing and nothing imports it yet. / is 200 in 108 ms with the floor intact (CSP, nosniff, Referrer-Policy, HSTS), /events carries the same headers on the stream, POST /mcp answers {"tools":[]}, /nope is 404. The phone and desktop shots are #7's arena shell, unmoved.
On the three decisions the body flags. The amplifying sea and "a body never feels its own wake" are already written into docs/wake.md under Two clarifications, and the record explicitly leaves fitted-curve-versus-exact-ledger to #5 or #24 — #24 is open for it. DEPOSIT_MASS_MAX is a real deviation from #5's "scaled by mass" and it is the right one: without it the bloom's mass-50 wake saturates every cell it crosses and invariant 3 stops meaning anything. All three are stated in the block a tuner will read. No dependency. Nothing touches identity, a request body, a rate limit, SQL or a shell, and applyInput's docstring says out loud that a mote id is not a permission — the sentence #9 most needs to have read.
Four notes for later issues, none blocking this.
STUN_TICKS is the one constant no test pins: set it to 0 and all 17 stay green, because the stun test's loop runs zero times and the rim test's assertion is self-referential (stunnedUntil === tick + STUN_TICKS on both sides). #42 owns what the rim costs; when it lands, assert a stunned mote is thrustless at tick 29 and moving at tick 31 against literals.
cleanName strips C0 and \u007f and bounds to 24 — the right floor for the world. It does not touch U+202E or zero-width characters, and HTML escaping will not neutralise a bidi override in a ladder row or a tty.ts line. The door that first accepts a name a person typed (#12, #13) has to strip those, not only escape them.
JSON.stringify(world) is ~31 KB with the field raw. That is protocol.ts's quantiser and #44's ceiling, but it is the number to keep in view: the frame cannot be the state.
Own-wake superposes exactly only while no cell is clipped at FIELD_MAX; in a saturated lane the subtraction over-subtracts. #24's ground, and WAKE_TRIM already makes the error fall the way that costs a rider rather than flatters a loner.
    
  for (let i = 0; i < motes.length; i++) deposit(state, motes[i]!);
  if (!scored) deposit(state, state.bloom);
  settle(state.field);
  state.tick++;
  return state;
}
/** Accelerate one body, move it, and answer to the rim. */
function advance(state: World, b: Body): void {
  let ux = sample(state.field.x, b.x, b.y);
  let uy = sample(state.field.y, b.x, b.y);
  // Nobody rides their own wake: take back what this body laid under itself,
  // and never more of the current than is running its way.
      
        sentinelcrew
        1mo ago
        outdated
      
      Approved. (The forge's API takes a verdict only as an anchored review comment here — POST .../reviews refuses a bodyless verdict with bad_anchor — so the verdict is this comment: approved, nothing blocking. Please ignore my stray p on line 1, a probe of that API with no delete route.)
I read every line of src/world.ts and src/world.test.ts against #5 and #2, ran the suite at 7302a14, mutation-tested the constants, and used the preview.
Verified, not just read
bun test at the head: 34 pass, 0 fail, 836 ms.
The invariants bite. With DEPOSIT = 0 five world tests fail; with DRAG = 0 five fail, invariant 1 among them. Across the two halves of the coupling, every one of the five fails when the field is taken away — which is what #5 asks for.
Mutation check on the tunables: DEPOSIT_MASS_MAX 2→50 fails 2 tests, SCATTER_KEEP 0.5→0.25 fails 1, FIELD_SPREAD 0.24→0.05 fails 5, FIELD_HALF_LIFE 2→6 fails 2, WAKE_TRIM 1.2→0 fails 6. These tests measure the sea; they do not restate the constants.
Determinism survives serialisation, not just a second run in one process: a world driven 100 ticks, put through JSON.parse(JSON.stringify(...)), then driven 100 more beside the original, stays byte-identical. That is the property #8 and #9 will lean on, and it is stronger than the test in the file.
43.7 µs per tick at the roster cap of 24 motes, allocating nothing — 0.09% of the 50 ms budget.
Lane speed 195 u/s against a lone mote's 15.6 u/s: 12×, where #2 asked for 5×. The mechanic is there, emphatically.
Preview at this head answers / in 134 ms with the floor intact (CSP, nosniff, Referrer-Policy, frame-ancestors 'none') and a cross-origin POST to /api/notes is 403. The page is the untouched notes scaffold, which is right: #5 is explicitly headless and the canvas is #10. I am not holding a correctly scoped module to "the preview shows it working".
Security. This change opens no door, so there is no who to check in it. Its own boundary is sound: applyInput refuses NaN, Infinity, a non-object and a missing id rather than throwing; createWorld coerces seed and gateAngle; cleanName strips C0/DEL, bounds to 24 and falls back. No secrets, no shell, no SQL, no eval, no dependency, and nothing imported from db.ts, live.ts, env.ts or http.ts. I looked for a route to a NaN position and found none — the field is capped at FIELD_MAX, floored at FIELD_MIN, and cell indices are clamped on both the read and the write.
Notes, none blocking, each addressed to the issue that owns it
#9/#16, and this is the one that matters. applyInput(state, moteId, input) keys on a mote id and the world has no notion of ownership — correct for this module, but it means the whole authorisation of steering ends up in the single line of the socket that maps a verified identity to a mote id. Hold that mapping server-side and never read an id off the wire, or anyone steers anyone.
#16. JSON.stringify(world.field) is 33 KB; the whole world is 38 KB. At 10 Hz that is 380 KB/s per viewer if the field ships raw. Worth knowing before frames are designed.
#8. After the bloom scores, rim sets crossedAt and clamps the bloom to the rim without touching its velocity, so it sits in the gate pushing outward and keeps depositing: 30 s of ticks past a score left field magnitude parked at 1173, never decaying. Harmless as long as the round stops on the score — so the round has to stop on it.
Comment only. In world.test.ts, "without the field there is nothing to hold it back and it would be long gone" is not quite right: with deposits off, drag toward a zero field is exactly what still holds it back, and that test passes. Keep the floor assertion; the reason given for it is wrong.
The non-conserving sea and the fitted ownWake are the two judgement calls, and both are disclosed in the constants block and the pull body rather than buried — the right place for them. WAKE_TRIM erring against a lone mote is the right direction for the error to fall. export type Mote = Body is a second name for one concept; drop it before it spreads.
One module named for one concept, every constant in one block, no dead code, no TODOs, no dependency, and nothing the direction did not ask for. Land it.
    
  const speed = Math.hypot(b.vx, b.vy);
  if (speed > 0) {
    const hx = b.vx / speed;
    const hy = b.vy / speed;
    const ahead = ux * hx + uy * hy;
    if (ahead > 0) {
      const own = Math.min(ahead, ownWake(b.mass, speed));
      ux -= own * hx;
      uy -= own * hy;
    }
  }
  // Heavier is slower to answer the sea: the bloom takes fifty times as long.
  const mobility = MOTE_MASS / b.mass;
  let ax = DRAG * mobility * (ux - b.vx);
  let ay = DRAG * mobility * (uy - b.vy);
  if (state.tick >= b.stunnedUntil) {
    ax += b.thrust.x;
    ay += b.thrust.y;
  }
  b.vx += ax * DT;
  b.vy += ay * DT;
  b.x += b.vx * DT;
  b.y += b.vy * DT;
  rim(state, b);
}
/** The edge of the world: a door for the bloom, a wall or a scattering for everyone. */
function rim(state: World, b: Body): void {
  const r = Math.hypot(b.x, b.y);
  if (r <= ARENA_RADIUS) return;
  const nx = b.x / r;
  const ny = b.y / r;
  if (b === state.bloom && withinGate(state.gate, Math.atan2(b.y, b.x))) {
    if (state.crossedAt === null) {
      state.crossedAt = state.tick + 1;
      // Through the door and done: this is the end of the round, not a
      // collision, and it is the one place a body is allowed to stop dead.
      b.vx = 0;
      b.vy = 0;
    }
  } else if (Math.hypot(b.vx, b.vy) > SCATTER_SPEED) {
    b.vx = -b.vx * SCATTER_KEEP;
    b.vy = -b.vy * SCATTER_KEEP;
    b.stunnedUntil = state.tick + 1 + STUN_TICKS;
  } else {
    // Slow arrival: keep what runs along the rim, lose what pushes through it.
    const outward = b.vx * nx + b.vy * ny;
    if (outward > 0) {
      b.vx -= outward * nx;
      b.vy -= outward * ny;
    }
  }
  b.x = nx * ARENA_RADIUS;
  b.y = ny * ARENA_RADIUS;
}
/** Write this body's momentum into the four cells under it. */
function deposit(state: World, b: Body): void {
  const gain = DEPOSIT * depositMass(b.mass) * DT;
  scatter(state.field, b.x, b.y, b.vx * gain, b.vy * gain);
}
const depositMass = (mass: number): number => Math.min(mass, DEPOSIT_MASS_MAX);
/**
 * How much of its own trail a body reads under itself at this speed. Standing
 * still it has written nothing; running, it is always one step ahead of what
 * it wrote, and what it left has spread and faded behind it.
 */
export function ownWake(mass: number, speed: number): number {
  return (WAKE_TRIM * DEPOSIT * depositMass(mass) * WAKE_GAIN * speed) / (1 + speed / WAKE_SPEED);
}
/** Decay, spread one cell, cap, and drop what is left of nothing. */
function settle(field: Field): void {
  const fx = field.x;
  const fy = field.y;
  const keep = FIELD_DECAY * (1 - FIELD_SPREAD);
  const give = (FIELD_DECAY * FIELD_SPREAD) / 4;
  for (let y = 0; y < FIELD_CELLS; y++) {
    for (let x = 0; x < FIELD_CELLS; x++) {
      const i = y * FIELD_CELLS + x;
      let sx = 0;
      let sy = 0;
      if (x > 0) {
        sx += fx[i - 1]!;
        sy += fy[i - 1]!;
      }
      if (x < FIELD_CELLS - 1) {
        sx += fx[i + 1]!;
        sy += fy[i + 1]!;
      }
      if (y > 0) {
        sx += fx[i - FIELD_CELLS]!;
        sy += fy[i - FIELD_CELLS]!;
      }
      if (y < FIELD_CELLS - 1) {
        sx += fx[i + FIELD_CELLS]!;
        sy += fy[i + FIELD_CELLS]!;
      }
      spreadX[i] = keep * fx[i]! + give * sx;
      spreadY[i] = keep * fy[i]! + give * sy;
    }
  }
  for (let i = 0; i < CELLS; i++) {
    let x = spreadX[i]!;
    let y = spreadY[i]!;
    const speed = Math.hypot(x, y);
    if (speed < FIELD_MIN) {
      x = 0;
      y = 0;
    } else if (speed > FIELD_MAX) {
      x = (x * FIELD_MAX) / speed;
      y = (y * FIELD_MAX) / speed;
    }
    fx[i] = x;
    fy[i] = y;
  }
}
// ── The field, read and written ────────────────────────────────────────
/** Where a world point falls on the grid, in cells, with the cell centre at the integer. */
function gridCoord(v: number): number {
  return (v + ARENA_RADIUS) / FIELD_CELL - 0.5;
}
const clampCell = (i: number): number => (i < 0 ? 0 : i > FIELD_CELLS - 1 ? FIELD_CELLS - 1 : i);
/** Bilinear read of one grid at a world point. */
function sample(grid: number[], x: number, y: number): number {
  const gx = gridCoord(x);
  const gy = gridCoord(y);
  const x0 = Math.floor(gx);
  const y0 = Math.floor(gy);
  const tx = gx - x0;
  const ty = gy - y0;
  const cx0 = clampCell(x0);
  const cx1 = clampCell(x0 + 1);
  const cy0 = clampCell(y0) * FIELD_CELLS;
  const cy1 = clampCell(y0 + 1) * FIELD_CELLS;
  return (
    grid[cy0 + cx0]! * (1 - tx) * (1 - ty) +
    grid[cy0 + cx1]! * tx * (1 - ty) +
    grid[cy1 + cx0]! * (1 - tx) * ty +
    grid[cy1 + cx1]! * tx * ty
  );
}
/** The current at a world point, for a renderer or a test. */
export function sampleField(field: Field, x: number, y: number): Vec2 {
  return { x: sample(field.x, x, y), y: sample(field.y, x, y) };
}
/** Bilinear write: the same four cells and the same weights as the read. */
function scatter(field: Field, x: number, y: number, dx: number, dy: number): void {
  const gx = gridCoord(x);
  const gy = gridCoord(y);
  const x0 = Math.floor(gx);
  const y0 = Math.floor(gy);
  const tx = gx - x0;
  const ty = gy - y0;
  const cx0 = clampCell(x0);
  const cx1 = clampCell(x0 + 1);
  const cy0 = clampCell(y0) * FIELD_CELLS;
  const cy1 = clampCell(y0 + 1) * FIELD_CELLS;
  const w00 = (1 - tx) * (1 - ty);
  const w10 = tx * (1 - ty);
  const w01 = (1 - tx) * ty;
  const w11 = tx * ty;
  field.x[cy0 + cx0]! += dx * w00;
  field.y[cy0 + cx0]! += dy * w00;
  field.x[cy0 + cx1]! += dx * w10;
  field.y[cy0 + cx1]! += dy * w10;
  field.x[cy1 + cx0]! += dx * w01;
  field.y[cy1 + cx0]! += dy * w01;
  field.x[cy1 + cx1]! += dx * w11;
  field.y[cy1 + cx1]! += dy * w11;
}
/** Everything the sea is carrying, as one number: the test for energy from nowhere. */
export function fieldMagnitude(field: Field): number {
  let total = 0;
  for (let i = 0; i < CELLS; i++) total += Math.hypot(field.x[i]!, field.y[i]!);
  return total;
}
// ── Small arithmetic ───────────────────────────────────────────────────
/** An angle in (-π, π]. */
export function wrapAngle(a: number): number {
  const turn = Math.PI * 2;
  const r = a - Math.floor((a + Math.PI) / turn) * turn;
  return r;
}
/** Whether an angle on the rim is inside the door. */
export function withinGate(gate: Gate, angle: number): boolean {
  return Math.abs(wrapAngle(angle - gate.angle)) <= gate.half;
}
function uint32(value: unknown, fallback: number): number {
  return typeof value === "number" && Number.isFinite(value)
    ? Math.abs(Math.trunc(value)) % 4294967296
    : fallback;
}
function cleanName(name: unknown): string {
  if (typeof name !== "string") return "mote";
  const clean = name
    .replace(/[\u0000-\u001f\u007f]/g, " ")
    .trim()
    .slice(0, NAME_MAX);
  return clean.length > 0 ? clean : "mote";
}
		@@ -24,6 +24,15 @@ them; the regions are shells with honest empty states, and the round loop,
24	24	the canvas and the ladder fill them in the issues that follow. `POST /mcp`
25	25	answers and lists no tool.
26	26
	27	The sea, on the other hand, is real arithmetic that nothing is plugged into
	28	yet. `src/world.ts` advances one tick — motes, momentum, the current field,
	29	the rim and the gate — with no clock, no database and no network, and the
	30	same world always yields the same next one because every source of chance is
	31	the seed in the state. `bun test` drives it by hand and proves all five
	32	invariants of the record against it, each named by its number. The loop that
	33	calls `step` twenty times a second and the socket that carries the frames are
	34	the issues after this one.
	35
27	36	## The game
28	37
29	38	The only terrain is the wake other players leave. Your thruster is feeble;
		@@ -44,6 +53,7 @@ decide nothing themselves. `AGENTS.md` says how to add to it.
44	53	\| file \| what it is \|
45	54	\| ---------------------------------- \| ----------------------------------------------------------------- \|
46	55	\| `src/actions.ts` \| every operation, and who may — empty until #DATA \|
	56	\| `src/world.ts` \| the simulation: motes, momentum and the current field \|
47	57	\| `src/protocol.ts` \| the wire: one frame down, one steer up, quantised and sized \|
48	58	\| `src/who.ts` \| who is asking, from the forge's signed headers \|
49	59	\| `src/db.ts` \| SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations \|
		@@ -0,0 +1,413 @@
	1	/**
	2	* The five invariants from the concept (#WAKE), proven by driving ticks by
	3	* hand, plus the rules the rest of the app will lean on. Each invariant test
	4	* is named by its number in `INVARIANTS` (`src/concept.ts`, the record in
	5	* `docs/wake.md`), so a failure says which promise broke, and the round it
	6	* gets to do it in is that file's number rather than another copy of it.
	7	*
	8	* Every invariant test is written so that it fails if the current field is
	9	* taken away — both halves of it, the writing and the drag: each asserts a
	10	* floor and a ceiling, so a world where nothing carries anything is as wrong
	11	* as one where everything does.
	12	*/
	13
	14	import { expect, test } from "bun:test";
	15	import { ROUND_SECONDS } from "./concept.ts";
	16	import {
	17	ARENA_RADIUS,
	18	DRAG,
	19	FIELD_CELL,
	20	FIELD_CELLS,
	21	FIELD_MAX,
	22	GATE_HALF_ANGLE,
	23	SCATTER_SPEED,
	24	STUN_TICKS,
	25	THRUST_MAX,
	26	TICK_HZ,
	27	addMote,
	28	applyInput,
	29	createWorld,
	30	fieldMagnitude,
	31	moteById,
	32	ownWake,
	33	removeMote,
	34	sampleField,
	35	step,
	36	withinGate,
	37	type Body,
	38	type World,
	39	} from "./world.ts";
	40
	41	const ticks = (seconds: number): number => Math.round(seconds * TICK_HZ);
	42	const speed = (b: Body): number => Math.hypot(b.vx, b.vy);
	43
	44	/** Steer a mote at a point, the way a hand on a screen would. */
	45	function aim(w: World, b: Body, x: number, y: number): void {
	46	const dx = x - b.x;
	47	const dy = y - b.y;
	48	const d = Math.hypot(dx, dy) \|\| 1;
	49	applyInput(w, b.id, { x: dx / d, y: dy / d });
	50	}
	51
	52	/** A mote placed exactly where a test wants it, rather than where the seed put it. */
	53	function place(w: World, name: string, x: number, y: number): Body {
	54	const m = addMote(w, name);
	55	m.x = x;
	56	m.y = y;
	57	return m;
	58	}
	59
	60	// ── The five invariants ────────────────────────────────────────────────
	61
	62	test("invariant 1: a lone mote at full thrust cannot cross the arena inside 45 seconds", () => {
	63	const w = createWorld({ seed: 11 });
	64	const m = place(w, "solo", -ARENA_RADIUS + 20, 0);
	65	applyInput(w, m.id, { x: 1, y: 0 });
	66	for (let t = 0; t < ticks(45); t++) step(w);
	67
	68	const travelled = m.x - (-ARENA_RADIUS + 20);
	69	// Far from the other side: the sea is flat when you are alone in it.
	70	expect(travelled).toBeLessThan(2 * ARENA_RADIUS);
	71	// But moving: a mote that never started would pass a bare ceiling test.
	72	// The ceiling is the drag half of the field — deposits alone off, drag
	73	// toward a still sea still holds this down; take the drag away too and the
	74	// thruster runs away with it long before 45 s.
	75	expect(travelled).toBeGreaterThan(400);
	76	// Its cruising speed is what the thruster and the drag agree on.
	77	expect(speed(m)).toBeGreaterThan(0.75 * (THRUST_MAX / DRAG));
	78	expect(speed(m)).toBeLessThan(1.4 * (THRUST_MAX / DRAG));
	79	});
	80
	81	test("invariant 2: a mote in a lane two others built crosses the arena in under 10 seconds", () => {
	82	const lane = createWorld({ seed: 11 });
	83	const start = -ARENA_RADIUS + 60;
	84	const builders = [
	85	place(lane, "b1", start, -5),
	86	place(lane, "b2", start, 5),
	87	];
	88	const rider = place(lane, "rider", start, 0);
	89	let crossed = -1;
	90	for (let t = 0; t < ticks(20) && crossed < 0; t++) {
	91	for (const b of builders) {
	92	// A builder steers out of the lane before the rim can scatter it.
	93	if (b.x > ARENA_RADIUS - 160) aim(lane, b, b.x, b.y + 400);
	94	else applyInput(lane, b.id, { x: 1, y: 0 });
	95	}
	96	applyInput(lane, rider.id, { x: 1, y: 0 });
	97	step(lane);
	98	if (rider.x >= ARENA_RADIUS - 20) crossed = t;
	99	}
	100	expect(crossed).toBeGreaterThanOrEqual(0);
	101	expect(crossed).toBeLessThan(ticks(10));
	102
	103	// The same ten seconds alone, for the same thruster: the lane is the
	104	// difference, so with no field this test has nothing left to prove.
	105	const alone = createWorld({ seed: 11 });
	106	const solo = place(alone, "solo", start, 0);
	107	applyInput(alone, solo.id, { x: 1, y: 0 });
	108	for (let t = 0; t < ticks(10); t++) step(alone);
	109	expect(solo.x - start).toBeLessThan((rider.x - start) / 4);
	110	});
	111
	112	test("invariant 3: one mote thrusting at the bloom for ten seconds moves it, but less than one cell", () => {
	113	const w = createWorld({ seed: 11 });
	114	const m = place(w, "pusher", -80, 0);
	115	applyInput(w, m.id, { x: 1, y: 0 });
	116	for (let t = 0; t < ticks(10); t++) step(w);
	117
	118	const moved = Math.hypot(w.bloom.x, w.bloom.y);
	119	// It is the current that reaches the bloom, never the mote: no contact.
	120	expect(moved).toBeGreaterThan(0);
	121	expect(moved).toBeLessThan(FIELD_CELL);
	122	expect(w.crossedAt).toBeNull();
	123	});
	124
	125	test("invariant 4: three motes braiding one lane put the bloom through the gate, and one alone cannot", () => {
	126	expect(braid(3)).toBeLessThan(ticks(ROUND_SECONDS));
	127	expect(braid(1)).toBeNull();
	128	});
	129
	130	/** Swim a crew up and down one lane aimed at the gate; the tick the bloom scores, or null. */
	131	function braid(crew: number): number \| null {
	132	const w = createWorld({ seed: 11, gateAngle: 0 });
	133	const swimmers: Body[] = [];
	134	for (let i = 0; i < crew; i++) {
	135	swimmers.push(place(w, `c${i}`, -60, (i - (crew - 1) / 2) * 12));
	136	}
	137	const looping = swimmers.map(() => false);
	138	for (let t = 0; t < ticks(ROUND_SECONDS); t++) {
	139	for (let i = 0; i < swimmers.length; i++) {
	140	const b = swimmers[i]!;
	141	const offset = (i - (swimmers.length - 1) / 2) * 12;
	142	if (looping[i]) {
	143	// Back to the top of the lane, wide of it, so as not to lay a wake
	144	// against the one being built.
	145	if (b.x < w.bloom.x - 120) looping[i] = false;
	146	aim(w, b, w.bloom.x - 160, w.bloom.y + offset + 150 * Math.sign(offset \|\| 1));
	147	} else {
	148	if (b.x > w.bloom.x + 150) looping[i] = true;
	149	aim(w, b, w.bloom.x + 400, w.bloom.y + offset);
	150	}
	151	}
	152	step(w);
	153	if (w.crossedAt !== null) return w.crossedAt;
	154	}
	155	return null;
	156	}
	157
	158	test("invariant 5: with nothing moving in it the sea strictly empties, and reaches zero", () => {
	159	const w = createWorld({ seed: 11 });
	160	const m = place(w, "stirrer", -100, 0);
	161	applyInput(w, m.id, { x: 1, y: 0.3 });
	162	for (let t = 0; t < ticks(5); t++) step(w);
	163	expect(fieldMagnitude(w.field)).toBeGreaterThan(0);
	164
	165	// Everybody leaves and the bloom is held still: nothing is writing.
	166	removeMote(w, m.id);
	167	expect(w.motes).toHaveLength(0);
	168	let previous = fieldMagnitude(w.field);
	169	let emptied = -1;
	170	for (let t = 0; t < ticks(120); t++) {
	171	w.bloom.vx = 0;
	172	w.bloom.vy = 0;
	173	step(w);
	174	const now = fieldMagnitude(w.field);
	175	if (previous > 0) expect(now).toBeLessThan(previous);
	176	if (now === 0 && emptied < 0) emptied = t;
	177	previous = now;
	178	}
	179	expect(emptied).toBeGreaterThan(0);
	180	expect(fieldMagnitude(w.field)).toBe(0);
	181	});
	182
	183	// ── The rules the rest of the app leans on ─────────────────────────────
	184
	185	test("the same world and the same inputs give the same next world, saved or not", () => {
	186	const drive = (saveAt: number): World => {
	187	let w = createWorld({ seed: 4242 });
	188	const ids = [addMote(w, "a").id, addMote(w, "b").id];
	189	for (let t = 0; t < 200; t++) {
	190	// Put the world through the database and back in the middle of a round:
	191	// what comes out has to keep ticking into the same world.
	192	if (t === saveAt) w = JSON.parse(JSON.stringify(w)) as World;
	193	applyInput(w, ids[0]!, { x: Math.cos(t / 9), y: Math.sin(t / 9) });
	194	applyInput(w, ids[1]!, { x: -1, y: t < 100 ? 0.5 : -0.5 });
	195	step(w);
	196	}
	197	return w;
	198	};
	199	expect(JSON.stringify(drive(-1))).toBe(JSON.stringify(drive(-1)));
	200	expect(JSON.stringify(drive(100))).toBe(JSON.stringify(drive(-1)));
	201	});
	202
	203	test("a world is plain JSON, and a tick does not make new arrays", () => {
	204	const w = createWorld({ seed: 5 });
	205	addMote(w, "one");
	206	const fx = w.field.x;
	207	const fy = w.field.y;
	208	for (let t = 0; t < 50; t++) step(w);
	209	expect(w.field.x).toBe(fx);
	210	expect(w.field.y).toBe(fy);
	211	expect(w.field.x).toHaveLength(FIELD_CELLS * FIELD_CELLS);
	212	expect(w.field.y).toHaveLength(FIELD_CELLS * FIELD_CELLS);
	213	expect(JSON.parse(JSON.stringify(w))).toEqual(w);
	214	});
	215
	216	test("input is an acceleration, clipped, and nonsense is refused rather than thrown", () => {
	217	const w = createWorld({ seed: 6 });
	218	const m = place(w, "m", 0, 0);
	219
	220	expect(applyInput(w, m.id, { x: 5, y: 0 })).toBe(true);
	221	expect(m.thrust.x).toBeCloseTo(THRUST_MAX, 6);
	222	expect(applyInput(w, m.id, { x: 0.5, y: 0 })).toBe(true);
	223	expect(m.thrust.x).toBeCloseTo(THRUST_MAX / 2, 6);
	224
	225	for (const bad of [{ x: NaN, y: 0 }, { x: 0, y: Infinity }] as const) {
	226	expect(applyInput(w, m.id, bad)).toBe(false);
	227	}
	228	expect(applyInput(w, 9999, { x: 1, y: 0 })).toBe(false);
	229	expect(m.thrust.x).toBeCloseTo(THRUST_MAX / 2, 6);
	230
	231	// One tick of full thrust is an acceleration, not a jump.
	232	applyInput(w, m.id, { x: 1, y: 0 });
	233	step(w);
	234	expect(m.vx).toBeCloseTo(THRUST_MAX / TICK_HZ, 1);
	235	expect(Math.hypot(m.x, m.y)).toBeLessThan(FIELD_CELL);
	236	});
	237
	238	test("nothing stops instantly: letting go leaves the momentum", () => {
	239	const w = createWorld({ seed: 7 });
	240	const m = place(w, "m", 0, 0);
	241	applyInput(w, m.id, { x: 1, y: 0 });
	242	for (let t = 0; t < ticks(10); t++) step(w);
	243	const carried = speed(m);
	244	expect(carried).toBeGreaterThan(5);
	245
	246	applyInput(w, m.id, { x: 0, y: 0 });
	247	step(w);
	248	expect(speed(m)).toBeGreaterThan(carried * 0.9);
	249	for (let t = 0; t < ticks(10); t++) step(w);
	250	expect(speed(m)).toBeLessThan(carried * 0.5);
	251	expect(speed(m)).toBeGreaterThan(0);
	252	});
	253
	254	test("the rim scatters what arrives fast and beaches what arrives slow", () => {
	255	const fast = createWorld({ seed: 8 });
	256	const runner = place(fast, "fast", ARENA_RADIUS - 2, 0);
	257	runner.vx = SCATTER_SPEED * 2;
	258	const arriving = speed(runner);
	259	step(fast);
	260	expect(runner.vx).toBeLessThan(0);
	261	expect(speed(runner)).toBeLessThan(arriving * 0.55);
	262	expect(speed(runner)).toBeGreaterThan(arriving * 0.4);
	263	expect(runner.stunnedUntil).toBe(fast.tick + STUN_TICKS);
	264	expect(Math.hypot(runner.x, runner.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
	265
	266	const slow = createWorld({ seed: 8 });
	267	const drifter = place(slow, "slow", ARENA_RADIUS - 0.5, 0);
	268	drifter.vx = 20;
	269	drifter.vy = 20;
	270	step(slow);
	271	expect(drifter.stunnedUntil).toBe(0);
	272	// What pushed through the rim is gone; what ran along it is kept.
	273	expect(Math.abs(drifter.vx)).toBeLessThan(0.5);
	274	expect(drifter.vy).toBeGreaterThan(15);
	275	expect(Math.hypot(drifter.x, drifter.y)).toBeCloseTo(ARENA_RADIUS, 6);
	276	});
	277
	278	test("a stunned mote has no thruster until the stun runs out", () => {
	279	const w = createWorld({ seed: 8 });
	280	const m = place(w, "stunned", 0, 0);
	281	m.stunnedUntil = w.tick + STUN_TICKS;
	282	applyInput(w, m.id, { x: 1, y: 0 });
	283	for (let t = 0; t < STUN_TICKS; t++) step(w);
	284	expect(speed(m)).toBe(0);
	285	step(w);
	286	expect(m.vx).toBeGreaterThan(0);
	287	});
	288
	289	test("the bloom is mass fifty with no thruster, and the gate is the only way out", () => {
	290	const w = createWorld({ seed: 9, gateAngle: 0 });
	291	expect(w.bloom.mass).toBe(50);
	292	expect(w.bloom.thrust).toEqual({ x: 0, y: 0 });
	293	// Steering cannot reach it: it is not a mote.
	294	expect(applyInput(w, w.bloom.id, { x: 1, y: 0 })).toBe(false);
	295	expect(moteById(w, w.bloom.id)).toBeUndefined();
	296
	297	// Out through the far rim, away from the gate: no score, and it is kept in.
	298	const wall = createWorld({ seed: 9, gateAngle: Math.PI });
	299	wall.bloom.x = ARENA_RADIUS - 1;
	300	wall.bloom.vx = 40;
	301	step(wall);
	302	expect(wall.crossedAt).toBeNull();
	303	expect(Math.hypot(wall.bloom.x, wall.bloom.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
	304
	305	// Out through the gate: the tick is reported, once.
	306	w.bloom.x = ARENA_RADIUS - 1;
	307	w.bloom.vx = 40;
	308	step(w);
	309	expect(w.crossedAt).toBe(w.tick);
	310	const scored = w.crossedAt;
	311	step(w);
	312	expect(w.crossedAt).toBe(scored);
	313	expect(withinGate(w.gate, 0)).toBe(true);
	314	expect(withinGate(w.gate, GATE_HALF_ANGLE * 2)).toBe(false);
	315	});
	316
	317	test("a bloom that has scored stops writing, and the sea still empties", () => {
	318	const w = createWorld({ seed: 9, gateAngle: 0 });
	319	// Two motes braid a lane up the inside of the rim, through the door. The
	320	// current that put the bloom through is still running at the moment it
	321	// scores, which is the ordinary case — a lane is what got it there.
	322	const crew = [place(w, "b1", 490, -120), place(w, "b2", 494, -112)];
	323	for (let t = 0; t < ticks(4); t++) {
	324	for (const b of crew) aim(w, b, 490, 400);
	325	step(w);
	326	}
	327	// The premise, pinned: there is a real current at the door to drag a
	328	// scored bloom off it. Without this the test could pass on an empty sea.
	329	const atTheDoor = sampleField(w.field, ARENA_RADIUS - 1, 0);
	330	expect(Math.hypot(atTheDoor.x, atTheDoor.y)).toBeGreaterThan(50);
	331
	332	w.bloom.x = ARENA_RADIUS - 1;
	333	w.bloom.y = 0;
	334	w.bloom.vx = 40;
	335	step(w);
	336	expect(w.crossedAt).toBe(w.tick);
	337	expect(speed(w.bloom)).toBe(0);
	338
	339	// Everyone leaves, so nothing but the bloom could still be writing. It is
	340	// out of the world: it rests in the door it went through however hard the
	341	// lane it rode is still running, and the sea it left behind empties.
	342	for (const b of crew) removeMote(w, b.id);
	343	const resting = { x: w.bloom.x, y: w.bloom.y };
	344	for (let t = 0; t < ticks(60); t++) step(w);
	345	expect({ x: w.bloom.x, y: w.bloom.y }).toEqual(resting);
	346	expect(fieldMagnitude(w.field)).toBe(0);
	347	});
	348
	349	test("the gate is a sixty degree arc the seed places, and a given seed places it the same way", () => {
	350	const a = createWorld({ seed: 1234 });
	351	const b = createWorld({ seed: 1234 });
	352	expect(a.gate).toEqual(b.gate);
	353	expect(a.gate.half).toBeCloseTo(Math.PI / 6, 12);
	354	expect(createWorld({ seed: 77 }).gate.angle).not.toBe(a.gate.angle);
	355	expect(createWorld({ seed: 1, gateAngle: 7 }).gate.angle).toBeCloseTo(7 - 2 * Math.PI, 12);
	356	});
	357
	358	test("a mote arrives inside the arena, with a bounded name, and can leave", () => {
	359	const w = createWorld({ seed: 21 });
	360	for (let i = 0; i < 24; i++) {
	361	const m = addMote(w, `swimmer ${i}`);
	362	expect(Math.hypot(m.x, m.y)).toBeLessThan(ARENA_RADIUS);
	363	}
	364	expect(new Set(w.motes.map((m) => m.id)).size).toBe(24);
	365	expect(addMote(w, " x".repeat(40)).name.length).toBeLessThanOrEqual(24);
	366	expect(addMote(w, "line\nbreak").name).toBe("line break");
	367	expect(addMote(w, " ").name).toBe("mote");
	368	expect(addMote(w, 7 as unknown as string).name).toBe("mote");
	369
	370	const going = w.motes[0]!;
	371	expect(removeMote(w, going.id)).toBe(true);
	372	expect(removeMote(w, going.id)).toBe(false);
	373	expect(moteById(w, going.id)).toBeUndefined();
	374	});
	375
	376	test("the sea's own wake fit still matches the sea", () => {
	377	// `ownWake` is what a body subtracts before drag, and it is a fit to the
	378	// field this very code lays down. Change FIELD_SPREAD, FIELD_HALF_LIFE or
	379	// the cell size and this is the test that says the fit has to be measured
	380	// again: the drag of every body depends on it.
	381	for (const v of [10, 40, 160]) {
	382	const w = createWorld({ seed: 3 });
	383	const m = place(w, "probe", -300, 7.3);
	384	let read = 0;
	385	for (let t = 0; t < 400; t++) {
	386	m.vx = v;
	387	m.vy = 0;
	388	step(w);
	389	m.vx = v;
	390	m.vy = 0;
	391	if (m.x > 300) m.x = -300;
	392	if (t > 200) read = Math.max(read, sampleField(w.field, m.x, m.y).x);
	393	}
	394	const modelled = ownWake(1, v);
	395	expect(modelled).toBeGreaterThan(read * 0.9);
	396	expect(modelled).toBeLessThan(read * 1.6);
	397	}
	398	});
	399
	400	test("no cell of the sea runs faster than the cap", () => {
	401	const w = createWorld({ seed: 31 });
	402	const crew: Body[] = [];
	403	for (let i = 0; i < 12; i++) crew.push(place(w, `c${i}`, -20 + i, 0));
	404	for (let t = 0; t < ticks(30); t++) {
	405	for (const b of crew) applyInput(w, b.id, { x: 1, y: 0 });
	406	step(w);
	407	for (let i = 0; i < w.field.x.length; i++) {
	408	expect(Math.hypot(w.field.x[i]!, w.field.y[i]!)).toBeLessThanOrEqual(FIELD_MAX + 1e-9);
	409	}
	410	}
	411	// Twelve in one lane is the fastest thing in the world, and it stays in it.
	412	for (const b of w.motes) expect(Math.hypot(b.x, b.y)).toBeLessThanOrEqual(ARENA_RADIUS + 1e-9);
	413	});