DEV Community: Adrian Turbiński

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.