DEV Community: Adrian Turbiński

Build a deterministic network simulator in TypeScript

Adrian Turbiński — Mon, 02 Nov 2026 13:08:53 +0000

Within my collaborative diagram editor in coschema the network simulator was the most useful component. Not due to an effective network simulation but because on failure it would print a seed and replay exactly. The last full run had 1,756,564 messages across 5,000 seeds with 0 failures.

In this tutorial we will implement a small example similar to this in TypeScript. We will create a virtual clock, a seeded random number generator, a link with latency, jitter, loss and duplication and a runner that finds a failing seed and replays it. We assume basic knowledge of TypeScript and Node 24.

The complete project, with tests and configuration, is in the virtual-network-test-harness repository. The page explains the parts that matter, the repository holds every file.

Seeded randomness you can fork

A flaky network test usually has two causes: Math.random and real timers. I replace both. Randomness comes first, because everything else draws from it.

The generator in src/prng.ts is a small 32 bit mixer. It keeps the seed it started with and one integer of state, so the same seed always gives the same sequence.

export class Prng {
  readonly seed: number;
  private state: number;

  constructor(seed: number) {
    this.seed = seed >>> 0;
    this.state = this.seed;
  }

  nextUint32(): number {
    this.state = (this.state + 0x6d2b79f5) >>> 0;
    let mixed = this.state;
    mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
    mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
    return (mixed ^ (mixed >>> 14)) >>> 0;
  }

  chance(probability: number): boolean {
    return this.next() < probability;
  }

  fork(label: string): Prng {
    const mixed = Math.imul(this.seed ^ hashLabel(label), 0x9e3779b1) + 0x85ebca6b;
    return new Prng(mixed >>> 0);
  }
}

next() divides nextUint32() by 2 to the power of 32, which gives a float from zero up to one. hashLabel is a short FNV-1a hash of a string, and the constructor in the file also rejects non integer seeds.

fork is the method I care about. It derives a new generator from the original seed and a label, not from the current state. That means a fork gives the same stream no matter how much the parent has been used. When I later add one more draw on the upstream link, the downstream link keeps dropping exactly the same messages. Without forks, every change to one part of the simulation reshuffles the faults in every other part, and your seeds stop meaning anything.

A clock that only moves when the test says so

Real setTimeout makes tests slow and order dependent. The fix is a clock you advance by hand. src/virtual-clock.ts exports a small Clock interface with now, setTimeout and clearTimeout, and VirtualClock implements it.

The two methods that matter keep a sorted list of timers and pop the due ones in order.

export class VirtualClock implements Clock {
setTimeout(callback: () => void, delayMs: number): number {
  const timer: ScheduledTimer = {
    id: this.nextId,
    time: this.currentTime + delayMs,
    callback,
  };
  this.nextId += 1;
  const position = this.timers.findIndex((existing) => existing.time > timer.time);
  if (position === -1) this.timers.push(timer);
  else this.timers.splice(position, 0, timer);
  return timer.id;
}

advance(durationMs: number): number {
  const target = this.currentTime + durationMs;
  let processed = 0;
  for (let timer = this.takeDue(target); timer !== undefined; timer = this.takeDue(target)) {
    this.currentTime = timer.time;
    timer.callback();
    processed += 1;
  }
  this.currentTime = target;
  return processed;
}
}

Insertion goes before the first timer that is strictly later, so two timers with the same time run in the order they were created. That tie break is what makes runs repeatable. advance sets the clock to each timer's own time before running its callback, so code that reads now() inside a callback sees the moment the timer was due, not the end of the window.

Callbacks may schedule new timers, and if they fall inside the window they run in the same call. The file also has runUntilIdle, which throws VirtualClockOverflowError after a fixed number of events. A retry loop that never stops would otherwise hang your test run, and a clear error is better than a timeout.

A link that drops, delays and duplicates

Now the network itself. SimulatedLink in src/link.ts takes a clock, a generator, a delivery callback and a config with latency, jitter, loss rate and duplicate rate. The file ships three profiles: clean, lossy (60 ms latency, 40 ms jitter, 20 percent loss, 5 percent duplicates) and chaotic.

export class SimulatedLink<T> {
send(message: T): void {
  this.stats.sent += 1;
  if (this.isPartitioned) {
    this.stats.partitioned += 1;
    return;
  }
  if (this.random.chance(this.config.lossRate)) {
    this.stats.lost += 1;
    return;
  }
  this.scheduleArrival(message);
  if (this.random.chance(this.config.duplicateRate)) {
    this.stats.duplicated += 1;
    this.scheduleArrival(message);
  }
}

private scheduleArrival(message: T): void {
  const delay = this.config.latencyMs + this.random.between(0, this.config.jitterMs);
  this.clock.setTimeout(() => {
    this.arrive(message);
  }, delay);
}
}

No reordering is implemented and is intended this way. Every arrival gets its own random delay, so a later message may arrive before an earlier one if the jitter is large enough. Reordering is not an option that can be missed when testing, but rather naturally appears within the model.

The code under test is in src/reliable-sync.ts. A SyncClient numbers each update, keeps it until the server acknowledges it and retries on a timer. A SyncServer buffers out of order frames, applies them in order and acknowledges how many it has. The client takes a Clock, not the global timer, which is the only change the production code needs to be testable. createSyncRig wires both sides through two links and gives each one its own fork, upstream and downstream.

A runner that replays a failing seed

Fixed seeds in unit tests only cover the cases you thought of. I want many seeds, and I want any failure to be something I can paste back in. src/property.ts does that with a case made of a seed and a size, where the size is the number of updates.

export function replayCase(property: Property, testCase: PropertyCase): string | undefined {
  try {
    property(testCase);
    return undefined;
  } catch (error) {
    return error instanceof Error ? error.message : String(error);
  }
}

function caseForRun(baseSeed: number, run: number, maxSize: number): PropertyCase {
  const seed = new Prng(baseSeed).fork(`run:${run}`).seed;
  const size = 1 + new Prng(seed).fork('size').int(maxSize);
  return { seed, size };
}

function smallestFailingSize(property: Property, failing: PropertyCase, message: string) {
  for (let size = 1; size < failing.size; size += 1) {
    const candidateMessage = replayCase(property, { seed: failing.seed, size });
    if (candidateMessage !== undefined) return { size, message: candidateMessage };
  }
  return { size: failing.size, message };
}

Each run derives its seed from the base seed and the run number, so the whole report is reproducible from one number. When a run fails, the shrinker keeps the seed and tries smaller sizes until one still fails. A failure with 3 updates is easier to read than one with 19. formatFailure then prints the line you need: replay with seed=... size=....

The test file test/network.test.ts proves the loop with a property that is meant to fail. The client gets a retry interval so large it never fires, over the lossy profile.

const deliversWithoutRetries: Property = ({ seed, size }) => {
  const { clock, client, server } = syncRigFor(seed, LINK_PROFILES.lossy, 1_000_000_000);
  updatesOf(size).forEach((value) => client.push(value));
  clock.advance(10_000);
  if (server.log.length !== size) {
    throw new Error(`server applied ${server.log.length} of ${size} updates`);
  }
};

it('finds a failing seed when the client never retries and replays it', () => {
  const report = runProperty(deliversWithoutRetries, { runs: 30 });
  const failure = report.failure;
  expect(failure).toBeDefined();
  if (failure === undefined) return;
  const replayed = replayCase(deliversWithoutRetries, { seed: failure.seed, size: failure.size });
  expect(replayed).toBe(failure.message);
});

A broken client is the honest way to test a bug finder. If the runner cannot catch a client with retries switched off, it will not catch a subtle one either. The mirror property, with a normal retry interval over the chaotic profile, must pass for every run.

Run the tests and the project

The package.json has two scripts, test and typecheck, and it needs Node 24 or newer. The repository also has an .nvmrc file that says 24.

npm install
npm run typecheck
npm test

These tests do not require a network, browser or environment variables. They test the clock, link, runner, sync example, generator and do not wait for time to pass during any test, meaning they are fast.

To see the harness on its own, the README shows a short script. It builds a VirtualClock, a Prng with seed 7 and a rig over two lossy links, pushes one update, advances the clock by 5000 and prints rig.server.log. Run it twice and you get the same drops, delays and duplicates. Change the seed and the trace changes.

Just one limitation to state outright. The simulator does not run your logic against an actual network, but against the faults you list. The simulator does not have knowledge of TCP behaviour or browser timers that throttle in background tabs. The biggest issue is that a model you wrote yourself can share your blind spots. This is accurate and I still feel a little uneasy about a green run. The solution is not to skip it, but to add the fault you forgot the moment production shows it to you.

What to try next

Start by breaking the sync example in a new way. Make the server acknowledge before it applies a frame, or stop it ignoring duplicates, and see which seed the runner reports. Then replay that seed with replayCase and step through it. This is the loop that makes the whole setup worth building.

After that, a few extensions fit the existing pieces. Toggle setPartitioned in the middle of a property run and check recovery. Add a third link profile that is fine most of the time and terrible for one window. Print formatFailure in your CI log so a red build carries its own replay command.

The full code, including both test files, is in the repository.

This week, pick one retry loop in your own code and move its timer behind a Clock interface. Nothing else has to change yet. Once the timer is injectable, the rest is a matter of afternoons.

Why I built coschema, a collaborative diagram editor

Adrian Turbiński — Fri, 30 Oct 2026 10:38:53 +0000

A collaborative editor is mostly a series of choices for what to do in the case where two people are both correct. The syncing is the part that tends to get the most showiness. The other choices are where the work or failure of the system resides.

Diagram editors are my day job. I work on software that generates single-line diagrams of high-voltage substations, and in real teams several people edit the same diagram at the same time. I wanted to build the hard parts of that myself: maintaining graph validity when two users edit at once, undoing only your own edits, and supporting clean offline editing and merge.

I also wanted an editor that is keyboard operable and announces remote changes to screen readers, because collaborative canvases rarely are. That became coschema, an MIT-licensed editor in Angular on top of Yjs, with live cursors, follow mode and offline editing backed by IndexedDB. This is a case study of the finished project, so I will go through three decisions, the numbers, and what I left out.

My own sync server instead of Hocuspocus

I use Yjs 13 for the document and implemented my own sync server using the y-protocols. For the majority of products a ready-made solution like Hocuspocus would have been the appropriate choice and would have saved me a significant amount of code.

I implemented my own sync server due to a desire to own the wire protocol. A very early issue that arose was the lack of acknowledgement in y-protocols. When a client sends an update there is no way of the client being informed if the server has received it. This creates an issue for an offline capable editor as the user requires assurance over the safety of their previous changes.

I therefore decided to add an acknowledgement to the wire protocol (ADR 0009). The client counts the updates that are not safe yet and the UI can say so honestly. The updates are stored in an append-only log in PostgreSQL with compaction (ADR 0010).

The downside is now that I own the protocol, its bugs and its upgrades. One server process owns a room, and that limit comes straight from the design.

Validity at read time instead of repair writes

A graph can also become invalid due to actions that appear to be innocent. One user adds an edge to a node and another user removes that node. Both actions are valid. The edge will then point to nothing after the merge.

The most obvious solution is for a client to detect the dangling edge and remove it. I opted against this solution because if two clients both repair, each will perform a write and each repair constitutes a concurrent edit that can trigger reactions from other users. This can cause a storm of writes.

Instead the shared document is allowed to remain in an invalid state, and a derived read-only view hides it (ADR 0007). Nothing repairs anything.

import * as Y from 'yjs';

interface EdgeData {
  id: string;
  from: string;
  to: string;
}

export function visibleEdges(
  nodes: Y.Map<unknown>,
  edges: Y.Map<EdgeData>
): EdgeData[] {
  const result: EdgeData[] = [];
  edges.forEach((edge) => {
    if (nodes.has(edge.from) && nodes.has(edge.to)) {
      result.push(edge);
    }
  });
  return result;
}

The case for repair writes is quite narrow. The output must be clean to other consumers, for example, a piece of export code that will consume the raw data. All consumers should then apply the same filter. This does incur a cost. Perhaps the most serious objection is that an invalid shared state smells bad. I argue that this only smells bad if consumed raw. The raw document itself is never rendered.

Per-user undo where a drag is one step

A global undo is a bug in a shared document. I would like to undo my previous step, not a step made after my step.

Each client has an individual undo manager which only stores client-local data (ADR 0008). Undoing my step will not undo a label change made after my step by another user. A drag is implemented as one undo operation and not one undo operation per pointer event.

Its representation in Yjs looks something like this.

import * as Y from 'yjs';

const localOrigin = Symbol('local');

export function createUndo(nodes: Y.Map<Y.Map<number>>) {
  return new Y.UndoManager(nodes, {
    trackedOrigins: new Set([localOrigin]),
  });
}

export function moveNode(
  doc: Y.Doc,
  nodes: Y.Map<Y.Map<number>>,
  id: string,
  x: number,
  y: number
) {
  doc.transact(() => {
    const node = nodes.get(id);
    node?.set('x', x);
    node?.set('y', y);
  }, localOrigin);
}

The catch to this is that undo only makes sense in relation to your own history. If someone deleted the node you moved, your undo has nothing to act on and the editor has to cope with that quietly.

What I measured and what I did not

There is an article for the convergence simulator. The simulator uses the real server logic and the real client with 2 to 8 clients connected over a message-reordering, -duplicating, -delaying and -dropping network and then does byte-for-byte document comparison of every document. It ran 5,000 seeds over 1,756,564 messages with 0 failures. On failure the run prints out a seed which can be used to replay it exactly.

The other figures are from a single laptop and should be considered a floor for my setup rather than a promise.

Edit to remote render, p95: 18 ms against a 200 ms target.
One Node process sustained 3,987 operations per second.
Panning 5,000 nodes at 60 fps at every zoom level. I wrote that benchmark first, and my first renderer failed it.

There's a caveat to the accessibility result. Lighthouse accessibility is 100. The editor is keyboard operable and remote changes are announced to screen readers. However, it has not actually been tested with a real screen reader yet. Automated accessibility scoring only covers part of what a user with assistive technology requires. For now, I consider this claim unproven until that session happens.

I also prefer to express this in the README rather than let a 100 stand in for a test I have not done.

What is not built, and what I would keep

Documented in ADR 0025. I did not implement comments on nodes, resize handles, waypoint dragging, the Quarkus auth service or version snapshots. I also did not implement support for several server instances per room. One process owns a room, so scaling out would require either sticky routing or pub/sub.

None of these changes whether two people converge on a valid diagram, which was the question the project set out to answer. Each one is a feature or a deployment concern I can add later without redoing the core.

The practice I would carry forward is small. Before you build the clever part, decide what the system does when two correct actions collide, and write that decision down. Then open the last collaborative feature you shipped and check who repairs the invalid state, and whether two clients can repair it at once.

The live demo is at coschema.adrianturbinski.pl, where the demo page runs two editors in your browser with latency, jitter and packet loss sliders and an offline switch.

A festival logo as a function of day, stage and tempo

Adrian Turbiński — Thu, 29 Oct 2026 10:38:54 +0000

I published six sample identities on 2026-10-07. The identity I spent the most time debating with myself was the identity that is not a single logo.

Nośna is an example identity and not a client project. Nośna is an imagined three day event featuring new media art and electronic music within a converted spinning mill in Lodz. It is one of the six identities within my portfolio. The name comes from the idea of a carrier, specifically a carrier wave. The identity uses three parameters: day, stage and tempo to determine the identity. The case study for this identity is in Polish here: Nośna case study

This post is aimed at engineers who enjoy creative coding. There are three decisions made in the creation of this identity and each has a cost. I will outline them. Following this I will explain the generator used on the webpage and the pipeline used to generate the output files.

What never moves

My first choice was constant versus generated. What never changes is the wordmark in Syne 800, a carrier line and a small receiver ring. Everything above this is generated using the parameters of day, stage and tempo. These three parameters determine the shape, colour, thread count and number of cycles.

There are four stages: spinning, weaving, dyeing and finishing. These correspond to the four halls, which are named after the mill rooms. The days are Friday, Saturday and Sunday. So we have a tempo parameter and a small closed set. A seed can then be generated.

type Day = 'fri' | 'sat' | 'sun'
type Stage = 'spinning' | 'weaving' | 'dyeing' | 'finishing'

interface MarkInput {
  day: Day
  stage: Stage
  tempo: number
}

function seedOf({ day, stage, tempo }: MarkInput): number {
  const key = `${day}|${stage}|${tempo}`
  let h = 2166136261
  for (let i = 0; i < key.length; i++) {
    h ^= key.charCodeAt(i)
    h = Math.imul(h, 16777619)
  }
  return h >>> 0
}

There is no Math.random anywhere in the mark. The same inputs will always yield the same mark. This allows an organiser to send a colleague the three values and get the exact same file back. A poster and a web banner will never diverge.

In exchange, nobody can press a re-roll button. A generator without a re-roll button just doesn’t feel like a toy. I was fine with this because an identity that surprises its owner isn’t actually an identity.

Why twelve marks still read as one brand

There are 12 versions, 3 days by 4 stages. All use the same thread weight, ring and carrier. The eye picks up the three first, then the difference.

I rejected two designs and will explain both. The first used 4 threads. Four lines give 12 designs that vary only in offset and thread weight within a family. These 12 are presented as a slider in one picture. The second was a moving accent. It was a small part that would change direction for each of the 12 designs. This was too small to carry 12 designs and was invisible on a phone.

There is one situation where extra freedom is warranted. If every artist on the lineup needed their own element, a fixed carrier would be limiting. This would not be an issue for a 3-day event with 4 halls.

My largest concern is that 12 is a tiny output space for a generator. This is accurate. However, the element will be encountered individually, on a ticket, tab or poster. Recognition will be via repetition and not the number of potential outputs.

Below 48 px the element ceases to be a field and becomes a simplified lens. The ring and carrier are on ink, which is what is displayed in the browser tab.

Colour from the day, on bone

I then chose the day colours. These come only from the day. Friday is vermilion, Saturday is teal and Sunday is magenta. I chose light bone as the background as it breaks from the predominantly dark neon used on club flyers.

I then ran contrast ratios for the day colours against the background. Vermilion: 2.84 to 1, Teal: 2.11 to 1 and Magenta: 2.78 to 1. I would not use these as text.

Therefore the day colours are purely decorative. Text uses a darker version of each colour if it passes AA contrast. I re-ran all 25 of the specified contrast ratios using an independent script. The contrast ratios used in the brand book are independent of the tool used in creating the colour scheme.

A dark background would have given the table more impact. Neon on black is also not inappropriate for a screen in a hall. A contrast table can also be used to retrospectively rationalise a colour decision. In this instance however I used it as a constraint. This highlighted that the colours could be used to indicate the day but not text.

The issue with using "only decoration" is that it is a polite term for using ineffectual colours. I propose that the shape carries the identity and the colour simply labels it. If the colour is removed from a mark it should remain identifiable, as it is in this instance.

I lost the most striking screenshots by choosing bone rather than neon and I still regret this.

The generator on the page and its SVG

There's also a generator available on the case study page. It is a Preact island which an organiser can use to set the day, stage and tempo. It downloads an SVG under 10 KB with no text elements.

The small file size is largely due to restraint. Threads are represented as paths with integer coordinates, so no number has a long decimal expansion in the output.

function threads(input: MarkInput, count: number): string[] {
  const next = rng(seedOf(input))
  return Array.from({ length: count }, (_, i) => {
    const y = 10 + i * 12
    const bend = Math.round(next() * 40 - 20)
    return `M0 ${y}C100 ${y + bend} 300 ${y - bend} 400 ${y}`
  })
}

Here, rng is any small seeded generator. The point is that the seed is used once and the order of drawing is fixed. As a result, appending a thread at the end will not reorder the previous ones.

If the file contains no live text, the file will appear identical on a system that has never used the font. The wordmark is outlined at the time the file is sent to the exporter. Both of these rules can be checked during the build.

import { readFileSync, statSync } from 'node:fs'

const file = process.argv[2]
const svg = readFileSync(file, 'utf8')
const bytes = statSync(file).size

if (bytes >= 10 * 1024) {
  throw new Error(`too big: ${bytes} bytes`)
}
if (/<text[\s>]/.test(svg)) {
  throw new Error('text element found')
}

A budget that lives in a sentence in a case study gets broken by the next edit. A budget that fails the build holds.

The pipeline behind the files

The generator itself is visible. There is a studio folder that has its own package.json which is not part of the site build. This is where the animations for all six identities are generated, as well as the logos and PDFs.

The logos are implemented using SVGs with no text elements. Instead, fontkit will lay out the text and convert every glyph into a path. SVGO is then used to optimize the resulting SVG and finally resvg will render the SVG to a transparent PNG without needing a browser.

import { openSync } from 'fontkit'

const font = openSync('Syne-ExtraBold.ttf')
const size = 120
const scale = size / font.unitsPerEm
const run = font.layout('Nośna')

let x = 0
const paths = run.glyphs.map((glyph, i) => {
  const d = glyph.path.scale(scale, -scale).translate(x, size).toSVG()
  x += run.positions[i].xAdvance * scale
  return d
})

Due to the inclusion of a ś in the name I examine all the Polish characters in all the fonts at all weights for each glyph. Even if the font appears to render well I will not use a font which does not include all Polish characters.

I learnt the second tip by looking at PDFs. Chromium PDFs embed variable fonts as Type 3. If a font is pinned to a specific weight with subset-font the font will be CID TrueType and the PDF will be reduced in size. Data URIs are used for pinned instances of the font in the business cards, letterheads and brand book.

The brand book is an HTML page rendered by Playwright. The page size is set to 1920 by 1080 px in CSS which results in a 1440 by 810 pt sized PDF. I check for the 16:9 aspect ratio rather than 1920 pt. Nośna has 28 pages.

Give every input a reason

A generative identity is relatively easy to overdo. A generator tends to expose knobs. Each knob can add to the interest in the demo, so it is easy to expose all the knobs. The problems start when the outputs no longer look like one brand.

In Nośna there are three parameters, each with a defined role. The parameter called day controls the colour, stage controls the shape and tempo controls the rhythm of the threads. Everything else remains constant and it is this constant component that makes the system recognisable.

Open the last generator or theming system you released and list all the parameters. For each parameter describe the change a stranger would notice at a glance.

Any parameter which does not cause an obvious change should be removed.

Why I built gridtwin, the electrical half of a single-line diagram

Adrian Turbiński — Tue, 27 Oct 2026 10:44:50 +0000

A single-line diagram shows connections between objects. However, it does not show what flows between them. This was troubling to me for some time and so I decided to address this issue.

I currently work on software which draws single-line diagrams of high-voltage substations: Angular and diagram rendering in the browser, Java 21 and Quarkus behind it. I decided to create the other side of this to model the electrical implications of these diagrams. I called this project gridtwin. It combines domain knowledge, numerical methods, a 3D front end and a Java back end in one place.

Opening a breaker in either the 3D substation or the single-line diagram will cause an AC power flow to redistribute the load, overload a line and potentially cascade into an outage. These simulations are run on the public IEEE 14-bus and IEEE 30-bus test cases. I will show three decisions I would defend in this case study, and also discuss what I left out.

What a frontend engineer needs from a power flow

A network consists of buses and branches. Each bus has a voltage magnitude and angle. There are loads and generators which consume and produce power. AC power flow uses the power balance at each bus to compute the voltages.

These equations are nonlinear and thus Newton-Raphson is used. Each iteration involves solving a linear system derived from a Jacobian matrix. The Jacobian is sparse as each bus only interacts with its neighbours. There is also a slack bus which absorbs any mismatch that remains and fixes the angle reference.

That is all the theory required for the rest of this post. Overload flags, the cascade and line loading are all computed using the solved voltages.

The solver is thus a function transforming network state into numbers. The UI is a function of those numbers. Each breaker click triggers a new solve. This is only possible because the solve is cheap. For example an IEEE 30 solve from a flat start takes 0.67 ms median compared to a 10 ms target.

Matching MATPOWER down to the convention

I chose MATPOWER 8.1 as the referee. I created 16 base case reference solutions and 4 N-1 reference files by executing MATPOWER inside Docker using GNU Octave. My solver is tested against these solutions. Voltage magnitude tolerance is 1e-6 pu and angle tolerance is 1e-4 degrees. The maximum error across all tested cases is 8.23e-9 pu and 4.06e-7 degrees.

This was not achieved through improved solving algorithms or numerics. Rather, it was achieved through attention to modeling conventions. For example, transformer tap locations, handling of reactive limits (all violating generators converted at once or one at a time), and whether the slack generator is limited all affect results to the third decimal place. A solver may be correct but still differ from the reference due to modeling differences. These differences can only be made explicit through documentation. I documented these in an ADR.

Another discovery came from a property test on random stressed networks. There exists a second, low-voltage root of the power flow equations near 0.4 pu. A warm start may settle on this solution. A solution below 0.5 pu now triggers a second run from a flat start.

function solveSafely(net: Network, warm: Solution): Solution {
  const first = solver.solve(net, warm);
  if (first.minVoltage() < 0.5) {
    return solver.solve(net, Solution.flat(net));
  }
  return first;
}

For the narrow case that would have also allowed a loose tolerance, I only need the code to appear correct. The biggest problem with my code is that 1e-6 pu is too strict for an educational toy. I believe the tolerance serves as a warning. Without it, I would not be able to differentiate between a convention and a bug and the wrong root would still be displayed. This would look like a very bad day for the grid.

By matching against MATPOWER I have verified that I have made the same decisions as MATPOWER. This has no implications for an actual grid.

Islands and a slack per island

A breaker can divide the network into two parts. Prior to the solver seeing the network, the topology processor must deal with the fact that the solver assumes one connected network with one slack.

Islands are created using union-find on branches and closed switching devices connecting nodes. Each energized island is assigned a slack. Islands with no source are de-energized and their load is shed.

function findIslands(count: number, closed: [number, number][]): number[][] {
  const parent = Array.from({ length: count }, (_, i) => i);
  const find = (x: number): number => {
    while (parent[x] !== x) {
      parent[x] = parent[parent[x]];
      x = parent[x];
    }
    return x;
  };
  for (const [a, b] of closed) {
    parent[find(a)] = find(b);
  }
  const groups = new Map<number, number[]>();
  for (let i = 0; i < count; i++) {
    const root = find(i);
    groups.set(root, [...(groups.get(root) ?? []), i]);
  }
  return [...groups.values()];
}

This is a TypeScript sketch, but the implementation is in Java. Load shedding involves a modelling decision, with a visible cost. The load is removed from the balance and the choice of slack generator for an island changes who absorbs the mismatch. Both of these options are documented in an ADR rather than being left as defaults within a loop.

Interlocks also exhibit this pattern. A line with an open breaker may still be fed from its far end. There must therefore be a definition of a live portion of the line. Earthing that line is not allowed.

A fork-join pool for N-1 contingencies

N-1 analysis removes one component from the system and checks if the system remains operative. For the IEEE 30 system 47 outages were generated and each was solved independently using power flow.

To solve the outages I use a fork-join pool. In Java 21 virtual threads are the new default. I was initially going to use virtual threads but they enable cheap waiting rather than computation. Our outage solvers do not wait on anything. When our outage solvers run they completely utilise CPU. Beyond the number of cores present there is no benefit to having more threads than cores. A pool bounded to the number of available cores is the correct choice.

Using 20 threads I observe a median of 8.22 ms to compute 47 outages of the IEEE 30 system, against a target of 500 ms. I have chosen a relatively high target so there is scope for the interactive application where each action can trigger a new analysis.

Virtual threads provide value in the scenario where each outage requires fetching something from a database or some other system. In this case the virtual threads will be blocked on each outage and cheap blocking is valuable in this situation.

A fixed sized pool can be considered old-fashioned. Maybe it can. However it is bounded and is visible in the design rather than hidden in the scheduling code. Under load the pool is also relatively easy to reason about. The value is also from a single machine and is used as a measured value rather than a guarantee.

What I did not build, and where the model stops

I have written down the cuts in ADR 0027. There is no state estimation or fast decoupled power flow. IEEE 30 is solved and tested but there is no substation visible in the UI.

I feel that the sparse Newton-Raphson solve should be well within the computational budget for this system size. A faster approximation would require a second method that would need to agree with the first method. State estimation requires measurements. A twin of a public test system will not have any real measurements to perform state estimation from.

This educational model is built on public test systems. The substation that replaces bus 4 is made up. The cascade is a static reduction. A branch trips the instant it passes 120% of its rating. There is no protection timing. Sessions are stored in memory and the demo resets every hour.

gridtwin is not intended to represent any real power system and none of gridtwin represents any real power system.

Build the half your drawing leaves out

A diagram consists of assertions about a system. If you only produce diagrams, no one will verify those assertions.

Working on the second half of a system has been more useful to my understanding of the diagrams I make in my job than producing the diagrams themselves. I also lost the safety of a diagram that can’t be wrong, and I miss that a little.

Now open the most recent screen you shipped that draws something from a domain and ask yourself what it would take to check it against an independent reference. If you can name that reference, write the first test this week.

Code available at github.com/adiyy2001/gridtwin, MIT. Live demo at gridtwin.adrianturbinski.pl.

A brand that has to work as a 16 px favicon and a sticker

Adrian Turbiński — Tue, 20 Oct 2026 09:38:01 +0000

For a school with no advertising budget, visibility is crucial in a single frame. The smallest frame the school can appear in is 16 px wide.

Klamra is a sample project. The company and school don’t actually exist and no payment was made for this. It is one of six visual identities in my portfolio, each for an invented Polish company. None of it is client work.

My brief to myself: an online coding school for adults changing careers and school leavers in groups of up to 8, two evenings a week over a 4 month course. Every competitor looks the same; navy background with a purple gradient and a smiling person with a laptop. Klamra needs to be recognisable on a sticker on a student’s laptop. That one constraint decided most of what follows.

A style that survives cheap reproduction

I was assigned neobrutalism. I used it as the authentic style for a code school and not as a style to mimic.

There are a few basic rules. There are thick black outlines. Shadows are hard offset with no blur. There are only four flat colors: lemon, pink, mint and sky. The display font is Epilogue 900 and all terminal-like elements are in JetBrains Mono. Klamra is the Polish name for a curly brace so the name is also indicative of the content.

:root {
  --lemon: #ffe45c;
  --pink: #ff6fae;
  --mint: #7ee8b3;
  --sky: #7cc7ff;
  --ink: #111;
}

.card {
  background: var(--mint);
  border: 3px solid var(--ink);
  box-shadow: 6px 6px 0 var(--ink);
}

.card h2 {
  font: 900 2rem/1 'Epilogue', sans-serif;
}

A shadow without softness is more important than it appears. A soft shadow is a gradient. Gradients are the first to perish in small objects: icons, one colour shirts or stickers. A hard shadow is simply another graphic form.

Now for the exception to this. If your product lives only on screens at large sizes then soft depth is acceptable. The argument against neobrutalism though is that it is a fashion which will date. Probably. However a school with no budget requires a mark that anybody with a printer can reproduce. Outlines plus offset shapes do that.

The text can follow the same tenet. Say what happens, when and for how much. Show the work of a given week rather than promising a dream job. Even the kerning is important. Kl and ra are pulled tighter whilst am and mr are opened a little in order to ensure that a very heavy word maintains an even colour.

Two logo directions that died at 24 px

I created three icons and dropped two. Both were at 24 px in real size and not scaled up.

One was a K made from braces. This is the cleverer idea and I still like it a little. At 24 px the arms merge into a plain K. It reads as a letter, not as code, so the one thing it was supposed to say is gone.

The second was a terminal window with a cursor. It looks like every school that has a console behind it and is also too wide for a favicon. A wide rectangle in a square slot shrinks until the detail is gone.

The only part of this worth keeping was the cursor. It moved inside the braces.

The icon that was selected features two thick braces with a pink cursor block between them. All is contained in a yellow frame with a hard shadow. The same drawing works as a sticker, a T-shirt print and a site icon. It also works because the cursor gives the braces a reason to be there. Braces by themselves are punctuation. Braces with a cursor are an editor waiting for you to type.

From 24 px down to 16 px

The full mark with frame and shadow holds up from 24 px. Below that it does not, and I stopped pretending that scaling would fix it.

The 16 px favicon is actually a separate drawing. The braces become thicker and the cursor becomes smaller. Thicker strokes survive being snapped to a 16 px grid, and a smaller cursor leaves room between them, so the gap isn’t filled in.

The cost is that there are now two versions of the same logo and they need to remain recognisably the same. I keep that honest by comparing them side by side at real size rather than by checking that the paths match.

The rule I took from it: a small size is its own design problem. If your favicon is a scaled down export of the full logo then nobody has ever looked at it.

Stickers you can move with the arrow keys

The case study page has a laptop lid with draggable stickers and a shuffle button. It is the idea of the brand made interactive: this is what Klamra looks like on your laptop.

I used pointer events to implement drag and the stickers themselves can be keyboard accessed allowing focus and movement using arrow keys. A drag-only toy would leave those without mice excluded and would also be strange to feature in an accessibility conscious portfolio.

Both input paths call one function, so they cannot drift apart.

const arrows: Record<string, [number, number]> = {
  ArrowLeft: [-8, 0],
  ArrowRight: [8, 0],
  ArrowUp: [0, -8],
  ArrowDown: [0, 8],
};

function place(sticker: HTMLElement, x: number, y: number) {
  sticker.dataset.x = String(x);
  sticker.dataset.y = String(y);
  sticker.style.transform = `translate(${x}px, ${y}px)`;
}

function enableMove(sticker: HTMLElement) {
  sticker.tabIndex = 0;
  sticker.addEventListener('keydown', (event) => {
    const delta = arrows[event.key];
    if (!delta) return;
    event.preventDefault();
    place(
      sticker,
      Number(sticker.dataset.x ?? 0) + delta[0],
      Number(sticker.dataset.y ?? 0) + delta[1]
    );
  });
}

The pointer handler uses the current position of the pointer, rather than a delta, in place(). The focus outline appears to be a part of the visual style rather than a browser default fighting it, since it is thick and black like everything else.

What ships in the folder

Mood boards are not allowed for clients. All identities in the project have a visual reference material (files).

Klamra has files as well.

Logo files are SVG. All characters are converted to paths. Therefore there is no text in the logo files and they do not require any specific installed fonts. There are PNGs at 512, 1024 and 2048 px; favicon, PDF and a logo system in six variants. Color values are shown in HEX, RGB, OKLCH and an approximate CMYK. A WCAG contrast table was generated using a script. All Polish characters are checked in all weights of the fonts used. The fonts are OFL.

The following items were created as well: 12 icons on a 24 px grid, pattern, business card (85 x 55 mm), PDF with 3 mm bleed, letterhead on A4, social media items and an email HTML signature. There is also an animated logo with a duration of 2 to 4 seconds. The animation is exported to WebM and MP4 at 1080 x 1080. A brand book in 16:9 is 27 to 29 pages and is in PDF. There is also a ZIP file that contains all the mentioned items.

All visual elements are created using canvas, CSS, SVG and code. There are no icon libraries or stock photos used. There is a studio folder containing the build scripts. This folder has its own package.json. The build does not get included in the site build. In the build process there is a variable font that is embedded as Type 3 in a Chromium PDF. For the PDFs the font is pinned to one weight and is then embedded as a smaller CID TrueType font.

The case study can be found at adrianturbinski.pl/wzornik/identyfikacja/klamra. The site is in Polish.

Limits, and what I would check first

The client doesn’t exist. No one has asked me to make the logo larger. No one has objected to the pink. No one has briefed me.

There has been no user testing. I think the logo is recognisable in one frame because it survives 24 px and 16 px. This speaks to legibility however and not memory. No one has put the logo on a laptop and one week later asked what the logo is. The stickers on the page have been checked for keyboard use but not with actual users. A search for conflicts on the brand name has been done but this is no proof of a clean name and not a legal clearance.

I would like to reiterate however the process I use across all projects. Test the smallest size first and then draw the rest. With the 24 px test two out of three of the directions were eliminated in minutes. If this had been discovered after the brand book had been laid out it would have been much more expensive.

This week view your own favicon at its actual size in a browser tab (not zoomed). If you cannot tell what it is then the full logo is not finished.

Why I built flagtide, one flag answer in Java and TypeScript

Adrian Turbiński — Tue, 13 Oct 2026 09:39:55 +0000

I use feature flags as part of my daily stack. I've used them for gradual rollouts and fast rollback. But I've never been completely satisfied with the way I knew they were working.

I had two questions. How do you manage to change a flag state and have it reach thousands of open browsers in well under a second? And how do you know that Java on the server and TypeScript in the browser give the same answer for the same flag?

My solution to both of these is flagtide. flagtide is a self-hosted feature flag service. It uses a Quarkus back end on PostgreSQL to push flag changes via WebSockets and an Angular SDK to evaluate the flags locally. This post is about the finished project, not a how to. I'll show you the motivations, three design decisions made and the trade-offs involved, the measured result and things that were left out intentionally.

Why a feature flag service at all

There are many feature flag products. This is not intended as a replacement for those.

I primarily use Angular, but I also build Java and Quarkus back ends. Thus I find myself on both sides of the line where a flag is decided. A flag service is one of the few small systems that touch both sides and have real rules: targeting, percentage rollouts, versions, ordering of changes.

I also wanted one compact project that would demonstrate hexagonal architecture and domain-driven design on a real domain, not a CRUD toy. The domain core has no framework in it. Both the in-memory adapter and the PostgreSQL adapter run the same eight contract tests, so a port means something. The ArchUnit rules are shown to fail on a planted violation, because a rule that has never failed is a rule I do not trust (ADR 0005, ADR 0014).

This gave me the frame. The interesting parts are the three decisions below.

One written spec, two engines, 616 vectors

The most severe kind of risk with flag services is quiet disagreement. A percentage rollout hashes the context key and maps it to a bucket. If the server and the browser differ in one detail, the same user lands in a different variant depending on who evaluated.

The details that bite are boring ones. A Java int wraps as a signed 32-bit integer whereas a JavaScript number is a double until you force it back using Math.imul or | 0. When hashing a string the same UTF-8 bytes must be present on both sides. However, JavaScript strings are UTF-16. Semver comparison needs one ordering rule, written down once.

This means that the algorithm itself is a written spec and both engines are my own code, one in Java and one in TypeScript. I did not wrap a library on one side and hope. Both engines run 616 shared vectors in CI. The expected hashes come from an independent Python oracle, so neither engine can vouch for itself.

The trade-off is real. Having two engines of my own means twice the code to maintain. Every new rule must also land in the spec, in both languages and in the vectors. I accept that because otherwise there would be a server-side evaluation call for each flag and that kills the point of evaluating locally in the browser.

PostgreSQL NOTIFY as a pointer, not a broker

We need coordination between multiple servers on the ordering of change and each server then needs to publish out to its connected sockets. The typical solution is some form of message broker. I've seen that in RabbitMQ in my work and for this situation it was over-complicated rather than required.

We already have the data in PostgreSQL and we have LISTEN and NOTIFY. The issue is that NOTIFY is ordered but not durable and only supports 8,000 bytes per payload. If a listener drops at the wrong time then it will miss some notifications.

Thus the notification carries nothing important. It is only a pointer to a change which is recorded in a versioned change log. Each server then consumes the change log after the version they have already seen.

CREATE TABLE flag_change (
  version bigserial PRIMARY KEY,
  flag_key text NOT NULL,
  body jsonb NOT NULL
);

SELECT pg_notify('flag_changes', 'wake up');

SELECT version, flag_key, body
FROM flag_change
WHERE version > $1
ORDER BY version;

This is the shape, not the real schema. A missed notification incurs a delay, not a missed change. The next read always picks everything up from the last seen version. A reconnect on every listener causes a resync for the same reason.

The test kills the listener backend and verifies that the next change still arrives (ADR 0008). This is why I have faith in this design. The cost is one read per notification per instance. I judged this cheap next to running a broker.

Serialize once, close the slow socket

Fan-out is the solution to the sub-second question. A change needs to make it to thousands of sockets across an instance.

The first rule is that changes are serialized per instance and all sockets receive the same string. Serializing per client is relatively easy to implement, but the CPU cost scales with the number of clients.

The second rule is less comfortable. If a connection has 256 frames pending on it the connection is closed (ADR 0017). One stuck client (for example, a laptop going to sleep with the tab still open) should not block all other clients. I prefer to drop one connection rather than introduce latency to all others.

interface Peer {
  send(frame: string): void;
  pending(): number;
  close(): void;
}

function broadcast(peers: Iterable<Peer>, change: object): void {
  const frame = JSON.stringify(change);
  for (const peer of peers) {
    if (peer.pending() >= 256) {
      peer.close();
      continue;
    }
    peer.send(frame);
  }
}

Our actual server is written in Java. This document is meant to be a translation into TypeScript of the idea. The largest issue with this design is that closing a socket seems rather abrupt. It does, but a client that can't keep pace is already stale and the SDK provides an accurate status for this (connecting, live, stale or offline). WebSocket pings are invisible to browsers so instead we implement a heartbeat from the server and compare timestamp values rather than number of timer ticks to account for throttling in background tabs (ADR 0010).

What the benchmark said

Target p95 propagation from commit to client: 300 ms

Test ran with 5,000 WebSocket clients across 2 instances, 30 changes and 150,000 frames. Measured p50 propagation at 38 ms, p95 at 77 ms and p99 at 90 ms. Percentage rollout evaluates in 0.412 µs on average in Node compared to a target of 5 µs.

This was run on a single laptop using WSL2. Both clients and servers were on the same machine. This is a useful smoke test but is not a capacity claim. I would not use these results to size a production cluster. Firefox and Safari were not tested.

What I care about though is the margin. By having a target specified prior to the test it creates a comparison rather than a story I told afterwards.

What I left out and what comes next

Four things are not built, on purpose, and ADR 0021 explains why: flag prerequisites, scheduled changes, an Oracle adapter and an SSE fallback. Each is real work, and none is needed to answer the two questions the project started with.

One limit is a shortcut I do not want anyone to copy. The admin keys reach the browser in a runtime config.json. That is fine for a public demo where anyone may edit the flags, and wrong for a real deployment.

The Oracle adapter is next. The contract tests already say what it has to do, which is the best argument I know for writing them first.

If you build something like this, write the spec before the second implementation, and let a third party compute the expected values. The project is MIT licensed, with 22 ADRs. The live demo is at flagtide.adrianturbinski.pl, admin and demo shop side by side, and the data goes back to the seed every hour. The SDK is on npm as @flagtide/core and @flagtide/angular.

Two implementations agree only when a third one has checked them.

Build sticky percentage rollouts with MurmurHash3 in TypeScript

Adrian Turbiński — Fri, 09 Oct 2026 12:06:39 +0000

A percentage rollout sounds trivial until two runtimes disagree about a single user. In a self-hosted feature flag project of mine the rollouts hash the context key, a difference in signed arithmetic or UTF-8 handling sends the same person to a different variant on the server than in the browser. This tutorial builds the TypeScript half of that idea, a small flag evaluator with sticky bucketing per user yet precisely enough specified for another runtime to reproduce it.

You will implement MurmurHash3 using 32 bit integer arithmetic, turn a bucket into a variant using integer weights, evaluate rules in a fixed order and test the result two ways. Shared JSON conformance vectors pin the behaviour for any language. A seeded property test shows that widening a rollout never removes a user who was already in.

You need Node 24, npm and basic TypeScript. There is no server or build step, just pure functions and Vitest 3. The complete project including every test and vector files is at https://github.com/adiyy2001/sticky-rollout-evaluator

Decide what a bucket is before writing code

The whole design hangs on one pure function: text in, bucket out. Rules, variants and the property test all depend upon the same text yielding the same bucket each runtime.

The rules fit in a list:

The input is the string flagKey.salt.userKey.
The hash is MurmurHash3 (x86, 32 bit, seed 0) of the UTF-8 bytes of that string, read as an unsigned number.
The bucket is that number modulo 100000.

The weights of a rollout are deliberately not part of the input. If they were, changing a percentage would reshuffle everybody, and users would flip back and forth while you widen a rollout.

The objection I hear most is that I should call a hash library and move on. That works inside one language. Across two, a library answers only half of the question, because the spec still has to say how a string becomes bytes, which seed to use and how a hash becomes a bucket. So I treat the algorithm as a written spec and the code as one implementation of it.

The bucket calculation lives in src/bucket.ts. It builds the input string and takes the modulo.

import { hashText } from "./murmur3.ts";

export const BUCKET_SPACE = 100_000;

export function bucketInput(flagKey: string, salt: string, contextKey: string): string {
  return `${flagKey}.${salt}.${contextKey}`;
}

export function bucketOfText(text: string): number {
  return hashText(text) % BUCKET_SPACE;
}

export function bucket(flagKey: string, salt: string, contextKey: string): number {
  return bucketOfText(bucketInput(flagKey, salt, contextKey));
}

The flag key and the salt are in the input so two flags never sort users the same way. Changing a flag's salt is the deliberate way to reshuffle everyone.

The modulo is only safe because hashText returns an unsigned number. A signed hash would give negative buckets, and a runtime with different integer types would disagree on the sign.

Implement MurmurHash3 with 32 bit integer arithmetic

JavaScript has no 32 bit integer type so the hash has to be coaxed out of doubles. Two things go wrong if you do it naively: multiplication and sign.

The file is src/murmur3.ts. I start with the constants and three helpers.

const C1 = 0xcc9e2d51;
const C2 = 0x1b873593;

function rotateLeft(value: number, bits: number): number {
  return ((value << bits) | (value >>> (32 - bits))) >>> 0;
}

function mixBlock(block: number): number {
  const scaled = Math.imul(block, C1);
  return Math.imul(rotateLeft(scaled, 15), C2);
}

function finalMix(input: number): number {
  let hash = input;
  hash ^= hash >>> 16;
  hash = Math.imul(hash, 0x85ebca6b);
  hash ^= hash >>> 13;
  hash = Math.imul(hash, 0xc2b2ae35);
  hash ^= hash >>> 16;
  return hash;
}

Math.imul multiplies as 32 bit integers and keeps the low bits. A plain * produces a product a double cannot hold exactly, so the low bits are silently wrong and the hash is wrong with them. A Java int wraps on overflow by itself, which is why a port to Java looks simpler and still has to match.

The bitwise operators in JavaScript return signed 32 bit values. The >>> 0 after the rotation reinterprets the result as unsigned, so nothing downstream sees a negative number by accident.

The main function reads the input in blocks of four bytes, little endian, and handles the one to three leftover bytes as a tail.

export function murmur3(data: Uint8Array, seed = 0): number {
  const blockEnd = data.length - (data.length % 4);
  let hash = seed | 0;
  for (let index = 0; index < blockEnd; index += 4) {
    const block =
      data[index] |
      (data[index + 1] << 8) |
      (data[index + 2] << 16) |
      (data[index + 3] << 24);
    hash ^= mixBlock(block);
    hash = rotateLeft(hash, 13);
    hash = (Math.imul(hash, 5) + 0xe6546b64) | 0;
  }
  const remaining = data.length - blockEnd;
  if (remaining > 0) {
    let tail = 0;
    for (let offset = remaining - 1; offset >= 0; offset--) {
      tail = (tail << 8) | data[blockEnd + offset];
    }
    hash ^= mixBlock(tail);
  }
  return finalMix(hash ^ data.length) >>> 0;
}

The function takes bytes, not a string, on purpose. The hash stays free of any text decisions, and those decisions live in one small place.

The tail is built from the last byte backwards, which puts the first leftover byte in the lowest position, the same layout the full blocks use. The final >>> 0 makes the result unsigned.

Turning a string into bytes is where runtimes quietly diverge.

const textEncoder = new TextEncoder();

export function encodeUtf8(text: string): Uint8Array {
  return textEncoder.encode(text);
}

export function hashText(text: string, seed = 0): number {
  return murmur3(encodeUtf8(text), seed);
}

TextEncoder always produces UTF-8, and it encodes a lone surrogate as U+FFFD. So a user key ending in \ud800 buckets exactly like one ending in the replacement character, and the hashing tests pin that. Some runtimes substitute a question mark instead, which is the kind of difference the spec has to rule out.

There is also no Unicode normalization and no case folding. User and user are different people, and so are a composed and a decomposed é.

Pick the variant from cumulative weights

A bucket is a whole number from zero up to one below the bucket space. A rollout is a list of variants with integer weights in thousandths of a percent, so they always sum to 100000.

Integers matter here, with floating point percentages two runtimes could round the same boundary differently placing one bucket on opposite sides of it.

Selection lives in src/rollout.ts. It walks the entries and serves the first variant whose cumulative weight exceeds the bucket.

export function pickVariant(entries: readonly RolloutEntry[], bucket: number): string {
  let cumulative = 0;
  for (const entry of entries) {
    cumulative += entry.weight;
    if (cumulative > bucket) {
      return entry.variant;
    }
  }
  throw new InvalidFlagError(`rollout weights do not cover bucket ${bucket}`);
}

The comparison is strict, a bucket equal to the cumulative weight is already out of that variant, while the last bucket below it is still in. A test checks both sides of that boundary.

The throw at the end only fires for a flag whose weights do not sum to the total. A separate validator rejects such flags before they ship, this is therefore a guard and not a normal code path.

Most rollouts are a single percentage so a helper builds that two-entry list.

export const TOTAL_WEIGHT = 100_000;

const WEIGHT_UNITS_PER_PERCENT = 1_000;

export function percentageRollout(onVariant: string, offVariant: string, percent: number): Serve {
  const onWeight = Math.round(percent * WEIGHT_UNITS_PER_PERCENT);
  if (!Number.isFinite(percent) || onWeight < 0 || onWeight > TOTAL_WEIGHT) {
    throw new RangeError(`percent must be between 0 and 100, got ${percent}`);
  }
  return {
    rollout: [
      { variant: onVariant, weight: onWeight },
      { variant: offVariant, weight: TOTAL_WEIGHT - onWeight },
    ],
  };
}

The enabled variant comes first, so it owns the low end of the bucket space, from zero up to its weight. Raising the percentage moves one boundary to the right, and every bucket that was left of it stays left of it.

The off weight is computed as the remainder and never rounded on its own. That keeps the sum at the total for any input, including 0.001 percent.

Evaluate rules in a fixed order

In src/evaluator.ts the order of decisions becomes part of the spec. The kill switch comes first, then a disabled flag, then the rules in order and finally the fallthrough.

A rule only matches with all of its conditions matching, the first such rule wins. Any attribute missing or of a type the operator cannot use will never match, even with negate. People get this last point wrong, hence the vectors of its own.

function serve(
  flag: Flag,
  target: Serve,
  context: Context,
  reason: Reason,
  ruleIndex: number | null,
  ruleId: string | null,
): EvaluationResult {
  if ("variant" in target) {
    return resultFor(flag, target.variant, reason, ruleIndex, ruleId, null);
  }
  const bucketValue = bucket(flag.key, flag.salt, context.key);
  const variantKey = pickVariant(target.rollout, bucketValue);
  return resultFor(flag, variantKey, reason, ruleIndex, ruleId, bucketValue);
}

export function evaluate(flag: Flag, context: Context): EvaluationResult {
  if (flag.killSwitch) {
    return resultFor(flag, flag.offVariant, "KILL_SWITCH", null, null, null);
  }
  if (!flag.enabled) {
    return resultFor(flag, flag.offVariant, "OFF", null, null, null);
  }
  const attributes = context.attributes ?? {};
  const ruleIndex = flag.rules.findIndex((rule) =>
    rule.conditions.every((condition) => matchesCondition(condition, attributes)),
  );
  if (ruleIndex >= 0) {
    const rule = flag.rules[ruleIndex];
    return serve(flag, rule.serve, context, "RULE_MATCH", ruleIndex, rule.id);
  }
  return serve(flag, flag.fallthrough, context, "FALLTHROUGH", null, null);
}

The bucket is computed from context.key and nothing else. Attributes pick the rule but never touch the hash, so a user does not change bucket when their plan or age changes. That is what makes the rollout sticky.

The bucket is also computed lazily. A rule that serves a fixed variant never hashes anything, and the result reports null for the bucket. That detail turns out to be useful in the vectors.

resultFor looks the variant up and throws an InvalidFlagError if it does not exist. A flag that serves a variant it never declared should fail loudly, not hand back undefined to a caller who will treat it as falsy.

Write the expected results by hand

Unit tests in one language only prove that the language agrees with itself. A second implementation needs something it can run without reading my TypeScript, so the repository ships two JSON files in spec/vectors.

hashing.json holds MurmurHash3 reference values for a range of inputs and seeds, and the buckets derived from them. For example, the input abc with seed 0 hashes to b3dd93fa, which is bucket 43002. A port that gets that wrong has a problem in the hash or the modulo, and the file says which.

spec/vectors/evaluations.json holds complete flags and the results they must produce. I wrote the expected values by hand from the rules instead of running the evaluator and saving its output. A vector captured from the code under test only proves the code equals itself.

Here is a trimmed slice, the negation flag and two of its cases.

{
  "flags": {
    "negation": {
      "key": "negation",
      "enabled": true,
      "killSwitch": false,
      "salt": "1a2b3c",
      "variants": [{ "key": "on", "value": true }, { "key": "off", "value": false }],
      "offVariant": "off",
      "rules": [{ "id": "outside-poland", "conditions": [{ "attribute": "country", "operator": "in", "values": ["PL"], "negate": true }], "serve": { "variant": "on" } }],
      "fallthrough": { "variant": "off" }
    }
  },
  "cases": [
    { "name": "negation with a missing attribute does not match", "flag": "negation", "context": { "key": "u18", "attributes": {} }, "expected": { "variantKey": "off", "value": false, "reason": "FALLTHROUGH", "ruleIndex": null, "ruleId": null, "bucketed": false } },
    { "name": "negation matches another country", "flag": "negation", "context": { "key": "u19", "attributes": { "country": "DE" } }, "expected": { "variantKey": "on", "value": true, "reason": "RULE_MATCH", "ruleIndex": 0, "ruleId": "outside-poland", "bucketed": false } }
  ]
}

The expected block uses bucketed, a boolean, instead of the bucket number. The hashing vectors already pin bucket numbers, and the boolean checks the other thing a port can get wrong: hashing when it should not, or skipping the hash when it should.

The file covers lists, text that looks like a number, an inclusive age bound, a kill switch that beats matching rules and an empty context key. A test requires at least 25 cases and unique names, and it validates every flag in the file.

The runner is a function in test/support.ts called differences. It evaluates one case, compares six fields and returns a list of readable mismatch messages. A runner that cannot fail is worthless, so a test corrupts a vector on purpose and expects the mismatch to be reported.

Test that widening never removes a user

Vectors pin exact answers for a few users. They say nothing about the property that makes rollouts safe: going from 10 percent to 50 percent only ever adds people.

That statement covers all users and all pairs of percentages, so it gets a property test. It lives in test/rollout.property.test.ts and starts with three small helpers.

function rolloutFlag(percent: number, salt = "9f2c41"): Flag {
  return {
    key: "checkout",
    enabled: true,
    killSwitch: false,
    salt,
    variants: [
      { key: "on", value: true },
      { key: "off", value: false },
    ],
    offVariant: "off",
    rules: [],
    fallthrough: percentageRollout("on", "off", percent),
  };
}

function membership(flag: Flag, keys: string[]): boolean[] {
  return keys.map((key) => evaluate(flag, { key }).variantKey === "on");
}

function keepsEveryone(narrow: boolean[], wide: boolean[]): boolean {
  return narrow.every((wasIn, index) => !wasIn || wide[index]);
}

keepsEveryone is a logical implication: for every user, being in the narrow rollout implies being in the wide one. Writing it as !wasIn || wide[index] keeps the intent visible, and it allows new users to appear.

The test goes through the real evaluate, not through the bucket function. If someone later makes the evaluator depend on anything else, such as the percentage or the time, the property breaks.

it("never removes a user along a ladder of percentages", () => {
  const keys = userKeys(5000, 1);
  const ladder = [0, 1, 5, 10, 25, 50, 75, 99.999, 100];
  let previous = membership(rolloutFlag(ladder[0]), keys);
  for (const percent of ladder.slice(1)) {
    const current = membership(rolloutFlag(percent), keys);
    expect(keepsEveryone(previous, current)).toBe(true);
    expect(current.filter(Boolean).length).toBeGreaterThanOrEqual(previous.filter(Boolean).length);
    previous = current;
  }
});

The ladder includes the awkward ends: zero, a tiny step and 99.999, one thousandth of a percent from full. A second test draws random pairs of percentages and checks the smaller against the larger.

All the randomness is seeded. userKeys and createRandom in test/support.ts are deterministic, so every run checks the same users and a failure reproduces on the next run instead of vanishing.

Two more groups sit next to it. One shows that repeated calls give identical results and that adding attributes does not change a rollout result when no rule uses them. The other checks that about a quarter of users land in a 25 percent rollout, and that changing the salt moves roughly half of users at 50 percent. The distribution bounds are loose on purpose, since they guard against a broken hash and not against statistical noise.

Run the tests

The project has one script, and it runs everything: the hash vectors, the evaluation vectors, the unit tests and the property tests.

npm install
npm test

npm test runs vitest run once and exits. The project expects Node 24, and a .nvmrc file pins it for people who use a version manager.

There is nothing else to start. The evaluator is a set of pure functions that the tests import directly, so the test run is also the whole demonstration.

To see the safety net work, open spec/vectors/hashing.json, change one hash value by a character and run the tests again. The failure names the input and the seed. Change an expected variant in evaluations.json and the failure names the case and the field.

You will want the same from a second implementation. It reads the same two files and has to reproduce every line, and the first mismatch tells you whether the hash, the UTF-8 step, the modulo or the rule logic is at fault.

What to try next

The most useful next step is a second runtime. Write the evaluator in Java, Go or Python, load both vector files and make every vector pass. Watch the three places this tutorial flagged: multiplication that wraps at 32 bits, unsigned reads and how lone surrogates become bytes.

Then grow the vectors where a port is most likely to fail. Add user keys with emoji, with composed and decomposed accents and with an empty string, and add the hash and bucket for each. The cheapest bug to prevent is the one you wrote a vector for.

You could also extend the property test to rollouts with three variants. The widening property is easiest to state with a single moving boundary, so work out what you want to guarantee before you write the test.

The full code, including the validator, the condition operators and the remaining tests, is in the repository: https://github.com/adiyy2001/sticky-rollout-evaluator

A rollout that two runtimes compute differently is a bug nobody notices until a user complains. Write the spec down, then make the code prove it.

How I test that collaborative edits converge

Adrian Turbiński — Tue, 06 Oct 2026 06:07:51 +0000

A unit test cannot establish convergence, convergence is about every possible ordering of messages. You only ever write the orderings you thought of.

In coschema, my side project, a real-time collaborative diagram editor in Angular, I test it with a deterministic simulator. It runs the real server logic and the real client over a hostile network, heals the network and compares every document byte for byte.

Randomized runs are evidence, not formal proof, hence the word “test” and not “prove”. The evidence is still strong though and one design decision made it possible: the shared document is allowed to be an invalid graph.

What the simulator runs

The simulator does not mock the sync layer. Instead it wires up the real server logic and real client code in a single process with 2 to 8 clients and puts a fake network in the middle.

The network treats messages differently, it can delay them, reorder them, duplicate or drop them altogether. It can also cut a client off entirely and bring it back later.

Everything random comes from one seeded generator. There is no wall clock or real socket. Given the same seed the same run occurs again, step for step.

The network itself is small. This is a sketch of the idea not the repository code:

class FlakyNetwork {
  private queue: Packet[] = [];
  private now = 0;

  constructor(private rng: Rng, private faults: Faults) {}

  send(packet: Packet): void {
    if (this.rng.chance(this.faults.drop)) return;
    const copies = this.rng.chance(this.faults.duplicate) ? 2 : 1;
    for (let i = 0; i < copies; i++) {
      const at = this.now + this.rng.int(this.faults.maxDelay);
      this.queue.push({ ...packet, at });
    }
  }

  tick(): Packet[] {
    this.now++;
    const due = this.queue.filter((p) => p.at <= this.now);
    this.queue = this.queue.filter((p) => p.at > this.now);
    return due.sort((a, b) => a.at - b.at);
  }
}

Reordering needs no special feature. Two packets get different random delays, so the later one can arrive first.

Heal, then compare bytes

A random run has two phases. First the clients make edits while the network misbehaves: moving nodes, editing labels, connecting edges, deleting nodes, going offline and coming back.

Then the faults stop. Cut-off clients reconnect, the network runs until nothing is in flight, and every document is encoded and compared.

function runScenario(seed: number): void {
  const rng = createRng(seed);
  const server = new RealServer();
  const net = new FlakyNetwork(rng, chaosFaults);
  const clients = Array.from(
    { length: rng.between(2, 8) },
    () => new RealClient(server, net)
  );

  for (const step of randomSteps(rng, clients)) step();

  net.heal();
  clients.forEach((c) => c.reconnect());
  net.drain();

  const reference = server.encodeState();
  for (const client of clients) {
    if (!bytesEqual(client.encodeState(), reference)) {
      throw new Error(`diverged, seed ${seed}`);
    }
  }
}

I compare bytes on purpose. Comparing the rendered diagram can hide a difference that only shows up later, when the next edit touches the part that was already different. The encoded state leaves nothing to interpret.

A failing run prints its seed, and that seed replays exactly. A divergence that would otherwise arrive as a flaky bug report from a customer becomes a command I can run in a debugger.

Why the invalid graph made this possible

A diagram graph can become invalid without anyone doing anything wrong. One person connects an edge to a node while another person deletes that node. Both operations are legal on their own machines but merged results in an edge pointing at nothing.

The obvious fix is to repair it, whoever encounters the dangling edge should delete it. I decided against that in ADR 0007. The shared document is allowed to be in this invalid state while a derived read-only view hides it.

function visibleEdges(doc: DiagramDoc): Edge[] {
  return doc.edges.filter(
    (edge) => doc.nodes.has(edge.from) && doc.nodes.has(edge.to)
  );
}

No client repairs anything. Merging stays a pure merge, so the simulator only has to answer one question: did every replica receive the same set of updates and merge them to the same state?

The y-protocols layer underneath is built for exactly that. My code adds no writes upon it that depend upon what a client happened to see.

What repair would have cost the test

Suppose every client also repaired dangling edges as it saw them. Now a merge triggers an edit, and that edit gets broadcast.

Two clients see the same dangling edge at the same moment and both delete it. Or one repairs it while a third client still offline reconnects an edge to a new node with the same role. The state after healing clearly depends upon who did what repair, and in what order.

That is a repair storm, and one that hurts production as well as the test. Such a run would not go quiet following healing, there would be ongoing traffic from repairs. There would be no clean moment for the byte comparison to happen, and failure is likewise hard to pin on network or repair logic.

With validity decided at read time there’s nothing to pin. If the documents end up differing after healing it’s because the transport or merge operation was wrong. That’s a short list of suspects.

The same idea surfaces within the undo design. Each client features its own undo manager limited to local changes, a drag is one undo step. Undoing my move does not likewise revert some later label edit performed by another client, because the undo stack never reaches into remote history (ADR 0008).

What ordinary unit tests miss

I still write unit tests for each piece, the derived view, the undo steps, the encoding. They are fast and they point at the exact line.

A unit test encodes the author's story of what happens. Client A sends, client B receives, B sends back. I wrote that story so I wrote the code to survive it.

The simulator tells stories I would not write. An update comes twice and the second copy follows a later edit. A client gets cut off mid-batch. A dropped message only gets repaired when a different client reconnects.

It also tests the seams. The bugs I expect in a sync system live between server and client, what one side assumes about the other. Both are the real code so the assumptions get tested against each other not against a mock I wrote to agree with me.

The limit is coverage. A simulator finds the bugs its fault model can express, and a seed that passes says nothing about seeds I did not run. If the fault model misses a kind of failure, the simulator remains silent. So finding a new kind of failure in the wild means the first job is teaching the network to produce it.

The repository is at https://github.com/adiyy2001/coschema if you want to read the real version of any of this. The decision is written up in ADR 0012.

Make convergence a property of the merge

To test convergence, first make it a property of the merge and nothing else. Every reactive write a client makes after a merge is one more thing your test has to explain.

Then build the test around a seed. Use one generator, no wall clock, the real code on both sides, a hostile network, a heal step and a byte comparison at the end. Print the seed when it fails.

Allowing the invalid state in the document looked like a concession when I made the decision. It turned out to be what made the whole system checkable.

Review capacity is the new delivery bottleneck

Adrian Turbiński — Sun, 04 Oct 2026 15:40:43 +0000

Typing code is nearly free these days. Understanding code is not, and that’s where delivery gets stuck.

I use Claude Code daily for refactors and reviews and test generation. It’s good at producing diffs. It does not produce a human who understands the diff well enough to put their name on it.

I think review capacity, not generation speed, now determines how fast a team ships. Tech leads should plan for this the same as they would for build capacity.

Typing speed was never the job

Nobody ever shipped faster because they typed faster. The slow parts of delivery were always reading, deciding, checking and agreeing.

AI tools eliminated a step that was already cheap but made expensive steps more frequent. More diffs per day arrive but each still needs somebody to read them.

Two sets of numbers keep bringing me back to this.

The numbers do not add up to faster delivery

METR ran a randomized controlled trial with experienced open-source developers working on their own repositories. They were 19% slower with AI, and they believed AI had made them 20% faster.

The gap between those two figures is what interests me. If the people doing the work cannot feel the slowdown, a team will not notice it either until the dashboards show it.

The team-level data points the same way. Teams with high AI adoption merge 98% more PRs, review time goes up 91%, and DORA delivery metrics stay flat.

Individual output rises and code quality falls, while organizational delivery does not move. Work piles up in front of the reviewers, and reviewers are the one resource AI did not multiply.

Why generated code is expensive to review

When a colleague writes a change I can infer a lot from who wrote it: what they usually get right, where they cut corners and which parts of the system they understand.

Generated code presents none of that, it’s fluent and consistently formatted so it looks equally trustworthy everywhere including where it’s wrong.

The author is in a weaker position too, if it came from a prompt they may not have a model of why each line exists in the code. The reviewer is then the first person who has to build that model, and that is the slow part.

My first rule on the team is thus that the author must be able to explain every line within a PR. If they can’t then the PR is not ready for a reviewer.

The objection that AI can review it too

The strongest objection is that this problem is temporary, the model writes the code and a model can review it, removing the bottleneck.

I do use AI for review, it helps. You find mechanical issues or things like inconsistent naming or missing error handling or edge cases before humans spend time on them.

That does not remove the bottleneck. The reviewer itself comes from the same family of models as the generator so they share many of the same blind spots, the agreement is weaker evidence than it looks.

The other reason is accountability, someone on the team has to own the change in production and understand it. A model’s approval does not give a human that understanding.

So the AI review is a filter that makes less of what the human has to read, but the human still reads it.

Spend human review where judgment is needed

If review time is the scarce resource, it should go only where judgment is needed. Everything a machine can check should be checked before a person opens the PR.

name: pr-gate
on:
  pull_request:
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test

This is boring on purpose, a reviewer should never be the one to discover a failing type check.

The architecture helps here too. The backend of the grid application I lead at my current employer follows a hexagonal layout. Changes to the domain core get slow and careful review while changes to adapters like REST mappings or persistence queries get a lighter pass against the port they implement.

This gives reviewers a map of where to spend attention, without boundaries every generated diff demands the same level of suspicion everywhere.

Review the spec before the implementation

The cheapest review happens before the code exists. When I ask an agent to change behavior, I want the expected behavior pinned in a test that a human wrote or at least read closely.

import { describe, expect, it } from '@jest/globals';
import { nextStep, defaultPolicy } from './retry-policy';

describe('nextStep', () => {
  it('retries while attempts remain', () => {
    const attempt = defaultPolicy.maxAttempts - 1;
    expect(nextStep(defaultPolicy, attempt)).toBe('retry');
  });

  it('dead-letters once attempts are exhausted', () => {
    const attempt = defaultPolicy.maxAttempts;
    expect(nextStep(defaultPolicy, attempt)).toBe('dead-letter');
  });
});

I care about this sort of rule within RabbitMQ integrations, the retry and dead-letter behavior decides if a long calculation survives a bad night.

Reading two small tests is far cheaper than inferring the same rule from a large diff. If the tests are right and green the reviewer can skim the implementation for structure rather than re-deriving intent.

PRs stay small and I ask for generated refactors to be split by concern. A large diff including a rename, behavior change and new test file is the most expensive thing you can give a reviewer.

Put review hours in the plan

Most teams budget for building, review happens in the gaps. This worked when writing was the slow step. It breaks when diffs come faster than people can read them.

On a team of five, review is a shared pool of attention, and it’s finite. I plan around this explicitly.

I limit how many PRs one person can have open at once, generation can’t outpace reading. I count reviewing as real work when discussing sprint capacity. I ask what a feature costs to review, not just to produce.

I watch delivery not output. More merged PRs means little if the metrics describing getting value to users remain unchanged.

Generation is cheap now. Understanding is what you still pay for.