@wenathlan/stealthhead 0.0.0-stage → 2.0.94

package/tests/netcode.test.ts

@@ -0,0 +1,251 @@
+// # netcode.test — honest unit tests for the deterministic netcode layer
+// (deltas, interpolation, reconciliation, rewind, jitter), runnable with
+// the vitest runner:
+//   pnpm test
+// Every case feeds plain snapshots and commands and checks exact output —
+// no sockets, no mocks, no timing, no randomness.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  applydelta,
+  bracketpair,
+  CMDSPEED,
+  DEFAULTINTERPDELAY,
+  duepackets,
+  type EntityState,
+  entityattick,
+  interpolateat,
+  jitterof,
+  latestsnapshot,
+  lerpentity,
+  makedelta,
+  makejitterbuffer,
+  needsreconcile,
+  positionerror,
+  pushpacket,
+  pushrewind,
+  RECONCILETHRESHOLD,
+  reconcile,
+  replaycmds,
+  rewindattick,
+  type Snapshot,
+  simulatecmd,
+  wrapangle,
+  yawlerp,
+} from "../netcode.ts";
+
+/** one entity standing at a spot. */
+function entityat(id: string, px: number, tick: number, yaw = 0): EntityState {
+  return { id, tick, px, py: 0, pz: 0, yaw };
+}
+
+/** one snapshot from id/px pairs. */
+function snapshot(tick: number, time: number, rows: Array<[string, number]>): Snapshot {
+  return { tick, time, entities: rows.map(([id, px]) => entityat(id, px, tick)) };
+}
+
+describe("angles", () => {
+  it("wraps angles into [0, 2π)", () => {
+    assert.ok(Math.abs(wrapangle(-0.1) - (Math.PI * 2 - 0.1)) < 1e-9);
+    assert.ok(Math.abs(wrapangle(Math.PI * 5) - Math.PI) < 1e-9);
+    assert.equal(wrapangle(0), 0);
+  });
+
+  it("interpolates yaw by the shortest arc", () => {
+    assert.ok(Math.abs(yawlerp(0, Math.PI / 2, 0.5) - Math.PI / 4) < 1e-9);
+    assert.ok(Math.abs(yawlerp(3, -3, 0.5) - Math.PI) < 1e-9);
+    assert.ok(Math.abs(yawlerp(1, 1, 0.9) - 1) < 1e-9);
+  });
+});
+
+describe("snapshot deltas", () => {
+  it("carries only movers, spawns and despawns", () => {
+    const base = snapshot(1, 10, [
+      ["a", 0],
+      ["b", 5],
+      ["gone", 9],
+    ]);
+    const next = snapshot(2, 20, [
+      ["a", 4],
+      ["b", 5],
+      ["new", 1],
+    ]);
+    const delta = makedelta(base, next);
+    assert.equal(delta.base, 1);
+    assert.deepEqual(delta.changed.map((entity) => entity.id).sort(), ["a", "new"]);
+    assert.deepEqual(delta.removed, ["gone"]);
+  });
+
+  it("rebuilds the full snapshot from base plus delta", () => {
+    const base = snapshot(1, 10, [
+      ["a", 0],
+      ["gone", 9],
+    ]);
+    const next = snapshot(2, 20, [
+      ["a", 4],
+      ["new", 1],
+    ]);
+    const rebuilt = applydelta(base, makedelta(base, next));
+    assert.equal(rebuilt.tick, 2);
+    assert.deepEqual(rebuilt.entities.map((entity) => entity.id).sort(), ["a", "new"]);
+    assert.equal(rebuilt.entities.find((entity) => entity.id === "a")?.px, 4);
+  });
+
+  it("answers the newest snapshot by tick", () => {
+    const stream = [snapshot(1, 0, []), snapshot(3, 20, []), snapshot(2, 10, [])];
+    assert.equal(latestsnapshot(stream)?.tick, 3);
+    assert.equal(latestsnapshot([]), null);
+  });
+});
+
+describe("entity interpolation", () => {
+  it("brackets the render time without extrapolating", () => {
+    const stream = [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])];
+    assert.deepEqual(
+      bracketpair(stream, 50)?.map((snap) => snap.tick),
+      [1, 2],
+    );
+    assert.equal(bracketpair(stream, 150), null);
+    assert.equal(bracketpair(stream, -1), null);
+  });
+
+  it("interpolates positions and yaw at the fraction", () => {
+    const stream = [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])];
+    const state = interpolateat(stream, 50).find((entity) => entity.id === "a");
+    assert.equal(state?.px, 5);
+    const turn = interpolateat(
+      [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])].map((snap, i) => ({
+        ...snap,
+        entities: snap.entities.map((entity) => ({ ...entity, yaw: i === 0 ? 0 : Math.PI })),
+      })),
+      50,
+    );
+    assert.ok(Math.abs((turn.find((entity) => entity.id === "a")?.yaw ?? 0) - Math.PI / 2) < 1e-9);
+  });
+
+  it("spawns newer-only entities and drops older-only ones", () => {
+    const stream = [
+      snapshot(1, 0, [
+        ["a", 0],
+        ["dead", 9],
+      ]),
+      snapshot(2, 100, [
+        ["a", 10],
+        ["born", 3],
+      ]),
+    ];
+    const states = interpolateat(stream, 50);
+    assert.deepEqual(states.map((entity) => entity.id).sort(), ["a", "born"]);
+    assert.equal(states.find((entity) => entity.id === "born")?.px, 3);
+  });
+
+  it("lerps one entity directly", () => {
+    const out = lerpentity(entityat("a", 0, 1, 0), { ...entityat("a", 10, 2, Math.PI), py: 4 }, 0.25);
+    assert.equal(out.px, 2.5);
+    assert.equal(out.py, 1);
+    assert.ok(Math.abs(out.yaw - Math.PI / 4) < 1e-9);
+  });
+});
+
+describe("prediction and reconciliation", () => {
+  it("advances the entity with the shared movement math", () => {
+    const walked = simulatecmd(entityat("a", 0, 1), { seq: 1, forward: 1, side: 0, yaw: 0, dt: 0.5 });
+    assert.equal(walked.px, CMDSPEED * 0.5);
+    assert.equal(walked.tick, 2);
+    const sideways = simulatecmd(entityat("a", 0, 1), { seq: 2, forward: 0, side: 1, yaw: 0, dt: 1 });
+    assert.equal(sideways.pz, -CMDSPEED);
+    const turned = simulatecmd(entityat("a", 0, 1), { seq: 3, forward: 1, side: 0, yaw: Math.PI / 2, dt: 1 });
+    assert.ok(Math.abs(turned.pz - CMDSPEED) < 1e-9);
+    assert.equal(turned.yaw, Math.PI / 2);
+  });
+
+  it("replays command lists in order", () => {
+    const cmds = [
+      { seq: 1, forward: 1, side: 0, yaw: 0, dt: 1 },
+      { seq: 2, forward: 1, side: 0, yaw: 0, dt: 1 },
+    ];
+    assert.equal(replaycmds(entityat("a", 0, 1), cmds).px, 2 * CMDSPEED);
+    assert.equal(replaycmds(entityat("a", 0, 1), []).px, 0);
+  });
+
+  it("reconciles only above the drift threshold", () => {
+    const server = entityat("a", 3, 5);
+    const pending = [{ seq: 1, forward: 1, side: 0, yaw: 0, dt: 0.5 }];
+    const drifted = reconcile(entityat("a", 10, 7), server, pending, RECONCILETHRESHOLD);
+    assert.ok(drifted.error > RECONCILETHRESHOLD);
+    assert.equal(drifted.replayed.length, 1);
+    assert.equal(drifted.state.px, 3 + CMDSPEED * 0.5);
+    const close = reconcile(entityat("a", 3, 5), server, pending, RECONCILETHRESHOLD);
+    assert.equal(close.replayed.length, 0);
+    assert.equal(close.state.px, 3);
+    assert.equal(needsreconcile(entityat("a", 3.05, 5), server, RECONCILETHRESHOLD), false);
+    assert.equal(needsreconcile(entityat("a", 3.2, 5), server, RECONCILETHRESHOLD), true);
+    assert.ok(Math.abs(positionerror({ ...entityat("a", 3, 5), pz: 4 }, server) - 4) < 1e-9);
+  });
+});
+
+describe("lag compensation rewind", () => {
+  it("keeps the history ordered and capped to the newest frames", () => {
+    let buffer = { frames: [] as Snapshot[], capacity: 2 };
+    for (const tick of [10, 20, 30]) buffer = pushrewind(buffer, snapshot(tick, tick * 10, [["a", tick]]));
+    assert.deepEqual(
+      buffer.frames.map((frame) => frame.tick),
+      [20, 30],
+    );
+    buffer = pushrewind(buffer, snapshot(20, 200, [["a", 20]]));
+    assert.deepEqual(
+      buffer.frames.map((frame) => frame.tick),
+      [20, 30],
+    );
+  });
+
+  it("rewinds to the newest frame at or before the tick", () => {
+    let buffer = { frames: [] as Snapshot[], capacity: 8 };
+    for (const tick of [10, 20, 30]) buffer = pushrewind(buffer, snapshot(tick, tick * 10, [["a", tick]]));
+    assert.equal(rewindattick(buffer, 25)?.tick, 20);
+    assert.equal(rewindattick(buffer, 30)?.tick, 30);
+    assert.equal(rewindattick(buffer, 5), null);
+    assert.equal(entityattick(buffer, 25, "a")?.px, 20);
+    assert.equal(entityattick(buffer, 25, "ghost"), null);
+  });
+});
+
+describe("jitter buffer", () => {
+  it("measures the arrival jitter of the stream", () => {
+    assert.equal(jitterof([0, 20, 45, 70]), 2.5);
+    assert.equal(jitterof([0, 10]), 0);
+    assert.equal(jitterof([5]), 0);
+    assert.equal(jitterof([]), 0);
+  });
+
+  it("orders, dedupes and caps the playout queue", () => {
+    let buffer = makejitterbuffer(2, DEFAULTINTERPDELAY);
+    buffer = pushpacket(buffer, { tick: 2, arrivedat: 20 });
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 10 });
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 11 });
+    assert.deepEqual(
+      buffer.packets.map((packet) => packet.tick),
+      [1, 2],
+    );
+    buffer = pushpacket(buffer, { tick: 3, arrivedat: 30 });
+    assert.deepEqual(
+      buffer.packets.map((packet) => packet.tick),
+      [2, 3],
+    );
+  });
+
+  it("drains only the packets whose playout delay elapsed", () => {
+    let buffer = makejitterbuffer(8, 50);
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 0 });
+    buffer = pushpacket(buffer, { tick: 2, arrivedat: 40 });
+    assert.deepEqual(
+      duepackets(buffer, 60).map((packet) => packet.tick),
+      [1],
+    );
+    assert.deepEqual(
+      duepackets(buffer, 100).map((packet) => packet.tick),
+      [1, 2],
+    );
+    assert.deepEqual(duepackets(buffer, 10), []);
+  });
+});

package/tests/physics.test.ts

@@ -0,0 +1,185 @@
+// # physics.test — honest unit tests for the deterministic physics kernel,
+// runnable with the vitest runner:
+//   pnpm test
+// Every case feeds plain structs and checks the exact replayable output —
+// no fixtures from the DOM, no randomness, no mocks.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  aabb,
+  aabbcenter,
+  add,
+  applydrag,
+  type Body,
+  boxboxhit,
+  closestpoint,
+  createworld,
+  DEFAULTGRAVITY,
+  distance,
+  dot,
+  fixedsteps,
+  length,
+  normalize,
+  type PhysWorld,
+  scale,
+  sphereboxhit,
+  spherespherehit,
+  stepbody,
+  stepprojectile,
+  sweepbox,
+  vec3,
+} from "../physics.ts";
+
+const UNIT = aabb(vec3(0, 0, 0), vec3(1, 1, 1));
+
+/** one free body resting at the origin with standard tuning. */
+function bodyat(x: number, y: number, z: number, velocity = vec3(0, 0, 0)): Body {
+  return { id: "b1", position: vec3(x, y, z), velocity, invmass: 1, restitution: 0.5, friction: 0 };
+}
+
+/** an open arena from the origin to 100 on every axis. */
+function arena(): PhysWorld {
+  return createworld(vec3(0, 0, 0), vec3(100, 100, 100));
+}
+
+describe("vector kernel", () => {
+  it("adds, scales, dots, measures and normalizes without mutating", () => {
+    const v = vec3(3, 0, 4);
+    assert.deepEqual(add(v, vec3(1, 2, 3)), { x: 4, y: 2, z: 7 });
+    assert.deepEqual(scale(v, 2), { x: 6, y: 0, z: 8 });
+    assert.equal(dot(v, vec3(1, 0, 0)), 3);
+    assert.equal(length(v), 5);
+    const unit = normalize(v);
+    assert.ok(Math.abs(unit.x - 0.6) < 1e-9);
+    assert.equal(unit.y, 0);
+    assert.ok(Math.abs(unit.z - 0.8) < 1e-9);
+    assert.equal(length(v), 5);
+  });
+
+  it("keeps normalize total on the zero vector", () => {
+    assert.deepEqual(normalize(vec3(0, 0, 0)), { x: 0, y: 0, z: 0 });
+    assert.equal(distance(vec3(1, 2, 3), vec3(4, 6, 3)), 5);
+  });
+});
+
+describe("shape queries", () => {
+  it("builds boxes, centers them and finds closest points", () => {
+    const box = aabb(vec3(0, 0, 0), vec3(4, 2, 6));
+    assert.deepEqual(aabbcenter(box), { x: 2, y: 1, z: 3 });
+    assert.deepEqual(closestpoint(box, vec3(5, 1, 3)), { x: 4, y: 1, z: 3 });
+    assert.deepEqual(closestpoint(UNIT, vec3(0.5, 2, -1)), { x: 0.5, y: 1, z: 0 });
+  });
+
+  it("answers sphere, sphere-sphere and box-box overlaps", () => {
+    assert.equal(sphereboxhit({ center: vec3(2, 0.5, 0.5), radius: 1.5 }, UNIT), true);
+    assert.equal(sphereboxhit({ center: vec3(2, 0.5, 0.5), radius: 0.5 }, UNIT), false);
+    assert.equal(spherespherehit({ center: vec3(0, 0, 0), radius: 1 }, { center: vec3(2, 0, 0), radius: 1 }), true);
+    assert.equal(spherespherehit({ center: vec3(0, 0, 0), radius: 0.9 }, { center: vec3(2, 0, 0), radius: 1 }), false);
+    assert.equal(boxboxhit(UNIT, aabb(vec3(0.5, 0.5, 0.5), vec3(2, 2, 2))), true);
+    assert.equal(boxboxhit(UNIT, aabb(vec3(2, 2, 2), vec3(3, 3, 3))), false);
+  });
+
+  it("sweeps a box and reports the entry fraction or null", () => {
+    const wall = aabb(vec3(4, 0, 0), vec3(5, 1, 1));
+    assert.equal(sweepbox(UNIT, vec3(4, 0, 0), wall), 0.75);
+    assert.equal(sweepbox(UNIT, vec3(3, 0, 0), wall), 1);
+    assert.equal(sweepbox(UNIT, vec3(4, 0, 0), aabb(vec3(4, 5, 0), vec3(5, 6, 1))), null);
+    assert.equal(sweepbox(UNIT, vec3(0, 0, 0), aabb(vec3(0.2, 0.2, 0.2), vec3(0.8, 0.8, 0.8))), 0);
+    assert.equal(sweepbox(UNIT, vec3(0, 0, 0), aabb(vec3(5, 5, 5), vec3(6, 6, 6))), null);
+  });
+});
+
+describe("integration", () => {
+  it("applies gravity and bounces on the arena floor with restitution", () => {
+    const next = stepbody(
+      bodyat(0, 0, 0, vec3(1, 0, 0)),
+      1,
+      vec3(0, -10, 0),
+      aabb(vec3(-10, 0, -10), vec3(10, 10, 10)),
+    );
+    assert.deepEqual(next.position, { x: 1, y: 0, z: 0 });
+    assert.equal(next.velocity.x, 1);
+    assert.equal(next.velocity.y, 5);
+  });
+
+  it("damps horizontal velocity by friction and respects invmass 0", () => {
+    const grounded = { ...bodyat(0, 0, 0, vec3(2, 0, 0)), friction: 1 };
+    const next = stepbody(grounded, 1, vec3(0, -10, 0), aabb(vec3(-10, 0, -10), vec3(10, 10, 10)));
+    assert.equal(next.velocity.x, 0);
+    const pinned: Body = { ...bodyat(3, 3, 3, vec3(1, 1, 1)), invmass: 0 };
+    const still = stepbody(pinned, 1, vec3(0, -10, 0), aabb(vec3(-10, 0, -10), vec3(10, 10, 10)));
+    assert.deepEqual(still.position, { x: 3, y: 3, z: 3 });
+    assert.deepEqual(still.velocity, { x: 1, y: 1, z: 1 });
+  });
+
+  it("decays velocity through linear drag", () => {
+    assert.deepEqual(applydrag(vec3(10, 0, 0), 0.5, 0.2), { x: 9, y: 0, z: 0 });
+    assert.deepEqual(applydrag(vec3(10, 0, 0), 1, 2), { x: 0, y: 0, z: 0 });
+  });
+});
+
+describe("projectiles", () => {
+  it("flies with gravity and drag and reports no hit in open air", () => {
+    const step = stepprojectile(
+      { id: "p1", position: vec3(0, 50, 50), velocity: vec3(10, 0, 0), gravity: -10, drag: 0 },
+      1,
+      arena(),
+    );
+    assert.deepEqual(step.projectile.position, { x: 10, y: 40, z: 50 });
+    assert.equal(step.hit, null);
+    const dragged = stepprojectile(
+      { id: "p2", position: vec3(0, 50, 50), velocity: vec3(10, 0, 0), gravity: 0, drag: 0.5 },
+      1,
+      arena(),
+    );
+    assert.equal(dragged.projectile.velocity.x, 5);
+  });
+
+  it("stops at the arena bounds as a world hit", () => {
+    const step = stepprojectile(
+      { id: "p3", position: vec3(99, 50, 50), velocity: vec3(10, 0, 0), gravity: -10, drag: 0 },
+      1,
+      arena(),
+    );
+    assert.equal(step.hit?.kind, "world");
+    assert.deepEqual(step.hit?.at, { x: 100, y: 40, z: 50 });
+  });
+
+  it("stops at the first swept body hit and names it", () => {
+    const world = arena();
+    world.bodies.push({ ...bodyat(5, 50, 50), id: "crate" });
+    const step = stepprojectile(
+      { id: "p4", position: vec3(0, 50, 50), velocity: vec3(10, 0, 0), gravity: 0, drag: 0 },
+      1,
+      world,
+    );
+    assert.equal(step.hit?.kind, "body");
+    assert.equal(step.hit?.id, "crate");
+    assert.deepEqual(step.hit?.at, { x: 5, y: 50, z: 50 });
+  });
+});
+
+describe("fixed-step loop", () => {
+  it("converts frame deltas into whole steps plus a carried remainder", () => {
+    const first = fixedsteps(0, 0.05, 0.02);
+    assert.equal(first.steps, 2);
+    assert.ok(Math.abs(first.remainder - 0.01) < 1e-9);
+    const second = fixedsteps(0.01, 0.02, 0.02);
+    assert.equal(second.steps, 1);
+    assert.ok(Math.abs(second.remainder - 0.01) < 1e-9);
+  });
+
+  it("caps catch-up steps so a stall never spirals", () => {
+    const capped = fixedsteps(0, 1, 0.02, 3);
+    assert.equal(capped.steps, 3);
+    assert.ok(Math.abs(capped.remainder - 0.94) < 1e-9);
+  });
+
+  it("bootstraps the empty arena with the default gravity", () => {
+    const world = createworld(vec3(0, 0, 0), vec3(10, 10, 10));
+    assert.deepEqual(world.gravity, DEFAULTGRAVITY);
+    assert.equal(world.bodies.length, 0);
+    assert.equal(world.projectiles.length, 0);
+    assert.equal(dot(DEFAULTGRAVITY, vec3(0, 1, 0)), -19.6);
+  });
+});

package/tests/rankingladder.test.ts

@@ -0,0 +1,162 @@
+// # rankingladder.test — honest unit tests for the elo ladder arithmetic,
+// runnable with the vitest runner:
+//   pnpm test
+// Every k table, ceiling and floor arrives as a parameter — the tests pass
+// their own season config, exactly as a caller would.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  applydelta,
+  expectedscore,
+  kfactor,
+  type LadderOptions,
+  laddererror,
+  projectedrating,
+  rankduel,
+  ratingdelta,
+} from "../rankingladder.ts";
+
+/** the season config the tests play with: 32/24/16 bands like the classic tables. */
+const SEASON: LadderOptions = {
+  ktable: [
+    { minrating: 0, maxrating: 2100, k: 32 },
+    { minrating: 2100, maxrating: 2400, k: 24 },
+    { minrating: 2400, maxrating: Number.POSITIVE_INFINITY, k: 16 },
+  ],
+  maxdelta: 40,
+  floorrating: 100,
+  scale: 400,
+};
+
+describe("ranking ladder expected score", () => {
+  it("answers one half for equal ratings", () => {
+    assert.equal(expectedscore(1500, 1500, SEASON), 0.5);
+  });
+
+  it("answers the classic 0.909 for a 400 point favorite", () => {
+    const expected = expectedscore(1900, 1500, SEASON);
+    assert.ok(Math.abs(expected - 0.909) < 0.001, `expected ~0.909, got ${expected}`);
+    assert.ok(expectedscore(1500, 1900, SEASON) < 0.1);
+  });
+
+  it("mirrors around one half", () => {
+    const up = expectedscore(1700, 1500, SEASON);
+    const down = expectedscore(1500, 1700, SEASON);
+    assert.ok(Math.abs(up + down - 1) < 1e-9);
+  });
+
+  it("refuses non finite ratings", () => {
+    assert.throws(
+      () => expectedscore(Number.NaN, 1500, SEASON),
+      (error: unknown) => {
+        assert.ok(error instanceof laddererror);
+        assert.equal(error.code, "bad-rating");
+        return true;
+      },
+    );
+  });
+});
+
+describe("ranking ladder k factor", () => {
+  it("picks the band the rating falls into", () => {
+    assert.equal(kfactor(1500, SEASON.ktable), 32);
+    assert.equal(kfactor(2200, SEASON.ktable), 24);
+    assert.equal(kfactor(2500, SEASON.ktable), 16);
+    assert.equal(kfactor(2399.9, SEASON.ktable), 24);
+  });
+
+  it("serves a different table when the season passes one", () => {
+    assert.equal(kfactor(1500, [{ minrating: 0, maxrating: Number.POSITIVE_INFINITY, k: 10 }]), 10);
+  });
+
+  it("refuses an empty table, a non positive k and an uncovered rating", () => {
+    assert.throws(
+      () => kfactor(1500, []),
+      (error: unknown) => {
+        assert.ok(error instanceof laddererror);
+        assert.equal(error.code, "bad-ktable");
+        return true;
+      },
+    );
+    assert.throws(() => kfactor(1500, [{ minrating: 0, maxrating: 1000, k: 32 }]), laddererror);
+    assert.throws(() => kfactor(1500, [{ minrating: 0, maxrating: Number.POSITIVE_INFINITY, k: 0 }]), laddererror);
+  });
+});
+
+describe("ranking ladder deltas", () => {
+  it("rewards a win by k * (1 - expected) and penalizes the mirrored loss", () => {
+    const win = ratingdelta(1500, 1500, "win", SEASON);
+    assert.equal(win, 16); // k 32, expected 0.5
+    const loss = ratingdelta(1500, 1500, "loss", SEASON);
+    assert.equal(loss, -16);
+  });
+
+  it("pays less to the favorite and more to the underdog", () => {
+    const favorite = ratingdelta(1900, 1500, "win", SEASON);
+    const underdog = ratingdelta(1500, 1900, "win", SEASON);
+    assert.ok(favorite > 0 && favorite < 4, `favorite should earn little, got ${favorite}`);
+    assert.ok(underdog > 28, `underdog should earn a lot, got ${underdog}`);
+  });
+
+  it("scales with the k table the caller passes", () => {
+    const low = ratingdelta(1500, 1500, "win", {
+      ...SEASON,
+      ktable: [{ minrating: 0, maxrating: Number.POSITIVE_INFINITY, k: 8 }],
+    });
+    assert.equal(low, 4);
+  });
+
+  it("clamps the delta to the season ceiling", () => {
+    const clamped = ratingdelta(1500, 3500, "win", { ...SEASON, maxdelta: 20 });
+    assert.ok(clamped <= 20, `expected the clamp to hold, got ${clamped}`);
+    const floored = ratingdelta(3500, 900, "loss", { ...SEASON, maxdelta: 20 });
+    assert.ok(floored >= -20, `expected the clamp to hold, got ${floored}`);
+  });
+
+  it("grades a draw as half a win against an equal opponent", () => {
+    assert.equal(ratingdelta(1500, 1500, "draw", SEASON), 0);
+    assert.ok(ratingdelta(1500, 1900, "draw", SEASON) > 0);
+  });
+
+  it("refuses an unknown outcome", () => {
+    assert.throws(
+      () => ratingdelta(1500, 1500, "forfeit" as "win", SEASON),
+      (error: unknown) => {
+        assert.ok(error instanceof laddererror);
+        assert.equal(error.code, "bad-outcome");
+        return true;
+      },
+    );
+  });
+});
+
+describe("ranking ladder duels and projections", () => {
+  it("applies the floor when a big loss sinks the rating", () => {
+    assert.equal(applydelta(120, -90, 100), 100);
+    assert.equal(applydelta(1500, -30, 100), 1470);
+  });
+
+  it("rates both sides of a duel with mirrored deltas", () => {
+    const result = rankduel({ id: "vanta.k", rating: 1600 }, { id: "coldsnap", rating: 1400 }, "win", SEASON);
+    assert.ok(result.player.delta > 0 && result.opponent.delta < 0);
+    assert.ok(Math.abs(result.expected - 0.76) < 0.001, `expected ~0.760, got ${result.expected}`);
+    assert.equal(result.player.rating, 1600 + result.player.delta);
+    assert.equal(result.opponent.rating, 1400 + result.opponent.delta);
+  });
+
+  it("compounds a winning streak through the running rating", () => {
+    const opponents = [1500, 1500, 1500, 1500];
+    const after = projectedrating(
+      1500,
+      opponents.map((opponent) => ({ opponent, outcome: "win" as const })),
+      SEASON,
+    );
+    assert.ok(after > 1550, `a streak should compound, got ${after}`);
+    const recovered = projectedrating(
+      after,
+      opponents.map((opponent) => ({ opponent, outcome: "loss" as const })),
+      SEASON,
+    );
+    assert.ok(recovered < after);
+  });
+});