This is not a chatbot over a database.
This is not Text-to-SQL dressed up as AI.

This is a hierarchical multi-agent system that actually understands how business questions turn into data queries and then into insights.

What really stood out to me was the engineering discipline.

They did not use an LLM for everything.

• An auto-encoder handles intent detection in 0.009 seconds instead of 1.6 seconds.

• A fine-tuned BERT model handles routing in 0.3 seconds instead of ~2 seconds.

Only after this fast triage does the LLM come in for reasoning and narrative insight generation.

Small models for speed.
LLM for thinking.

That pattern alone is worth studying.

They also avoid naive Text-to-SQL. Instead, they use augmented querying with business context, APIs, and plan-and-execute workflows. The system breaks a question into steps, fetches the right data, and produces explanations that humans can actually act on.

In their evaluation, 90th percentile latency is under ~13 seconds with ~89% relevance and correctness judged by humans.

That is interactive. That is usable. That is very close to real.

The most important idea here is this:

You don’t explore dashboards anymore.

You ask questions to a system that already understands your schema, your metrics, your seasonality, and your business vocabulary.

And it tells you what happened and why.

This does not replace BI teams or data engineers.

It amplifies them.

It turns data infrastructure into a thinking layer for the business.

If you are building analytics platforms, GenAI agents, or data products, this paper is worth your time.

The future of analytics is not more charts.

It is conversational understanding over structured data.

References

In Part 7, we tackled summation error with Kahan compensation. Now we zoom in on a different precision trap: the moment you round a value to fewer digits.

Rounding is one of those “small” problems that quietly eats your lunch, your audit trail, and your sleep.

Most teams pick a rounding mode the way people pick a Netflix show: whatever was already playing.

In Java, that default story often becomes:

“We’ll use HALF_UP. That’s normal rounding. Done.”

And then you ship a pricing engine, a statement generator, a ledger, a tax calculator, or an amortization schedule…

…and then you discover that rounding is policy, not maths. Fine. It’s maths. But it’s maths with consequences.

This post is about choosing rounding modes intentionally, and why HALF_UP is not the universal solvent people think it is.

Quick Reference: Rounding Mode Cheat Sheet

Key rules:

• Avoid rounding double when policy matters: use BigDecimal from strings → The Classic Trap
• Decide when to round, not just how → Rounding Timing
• For money, use scaled integers internally → Money Pattern

The real problem: ties (the 5s)

Most rounding drama is not about 2.341 vs 2.34. It’s about ties: values exactly halfway between representable steps.

At 2 decimal places, these are the spicy ones:

• 1.005
• 2.675
• 10.125

It’s a tie only when the first discarded digit is 5 and all following discarded digits are 0, for the scale you’re rounding to (e.g., 1.005 or 1.00500... when rounding to 2 decimals).

A value like 1.0051 is not a tie - it’s closer to 1.01.

If you always push ties upward, you introduce a systematic bias. Sometimes that bias is desired. Often it’s not. Sometimes it’s illegal. Sometimes it’s fine but your reconciliation team will develop a new religion and curse your name in it.

Java’s rounding toolbox

Here is what Java offers. The real work is choosing a policy that matches your domain contract. Java gives you java.math.RoundingMode:

• HALF_UP - round to nearest; if exactly halfway, round away from zero (1.5 -> 2, -1.5 -> -2)
• HALF_DOWN - round to nearest; if exactly halfway, round toward zero (1.5 -> 1, -1.5 -> -1)
• HALF_EVEN - round to nearest; if exactly halfway, round to the result whose last kept digit is even (banker’s rounding, also called round-half-to-even)
• UP - always away from zero
• DOWN - always toward zero (truncate)
• CEILING - toward positive infinity (-1.231 -> -1.23, 1.231 -> 1.24 at 2dp)
• FLOOR - toward negative infinity (-1.231 -> -1.24, 1.231 -> 1.23 at 2dp)
• UNNECESSARY - throw if rounding would be required (my favorite “make bugs loud” mode)

Also remember: setScale(...) without a rounding mode throws if rounding is required.

new BigDecimal("1.234").setScale(2); // throws ArithmeticException

And the most important practical rule:

If you care about exact decimal policy, avoid rounding a double. Round a BigDecimal created from a string (or exact integer scale).

The classic trap: new BigDecimal(double)

import java.math.BigDecimal;
import java.math.RoundingMode;

public class RoundingTrap {
  public static void main(String[] args) {
    BigDecimal a = new BigDecimal(1.005);               // from double
    BigDecimal b = new BigDecimal("1.005");             // from string

    System.out.println(a.setScale(2, RoundingMode.HALF_UP)); // 1.00
    System.out.println(b.setScale(2, RoundingMode.HALF_UP)); // 1.01
  }
}

What you expect: both become 1.01

What often happens: the first becomes 1.00 because 1.005 as a binary floating value is actually a hair under 1.005.

If you’re in finance and you see “1.005 rounds to 1.00”, that’s not “Java being weird”. That’s you feeding approximate binary into exact decimal rounding and being surprised it behaves like… approximation.

What about BigDecimal.valueOf()?

There’s a middle ground that readers constantly trip over: BigDecimal.valueOf(double).

BigDecimal a = new BigDecimal(1.005);        // Dangerous: uses exact binary representation
BigDecimal b = BigDecimal.valueOf(1.005);    // Safer: uses Double.toString() internally
BigDecimal c = new BigDecimal("1.005");      // Safest: exact decimal from string

BigDecimal.valueOf(double) often behaves like the string constructor because it uses Double.toString() internally, which gives you the shortest decimal representation that round-trips correctly.

The rule of thumb:

• Use new BigDecimal("...") for literals and external decimal inputs
• Use BigDecimal.valueOf(double) only when you already have a double and need the best possible decimal view of it (still risky after computations, but better than new BigDecimal(double))
• Never use new BigDecimal(double) unless you explicitly want the exact binary-to-decimal conversion

One caution: if the double came from arithmetic, the value you’re “viewing” may already be far from the decimal you think you had. valueOf is not a magical cleansing ritual.

Why HALF_UP can be the wrong default

HALF_UP is intuitive. It matches what humans do with pencil maths. But for repeated operations, it can create drift because ties always go one way.

IEEE 754 connection: IEEE 754’s default rounding mode is “round to nearest, ties to even” - essentially HALF_EVEN. Java double results are specified to behave as if rounded that way for each operation. The irony is that when you switch to BigDecimal for precision, many developers then pick HALF_UP, introducing the very bias that IEEE 754 was designed to avoid.

Bias demo: HALF_UP vs HALF_EVEN

Let’s imagine you have many values that land exactly on ties at 2 decimals (it happens more than people think, especially after division and intermediate scaling).

Here’s the “policy difference” in one glance:

• HALF_UP: 1.005 -> 1.01, 1.015 -> 1.02, 1.025 -> 1.03 … always nudging up
• HALF_EVEN: 1.005 -> 1.00, 1.015 -> 1.02, 1.025 -> 1.02 … nudging toward even to cancel bias over time

Notice how HALF_EVEN alternates which side ‘wins’ on ties; HALF_UP always pushes the same direction. This is why banking and accounting systems often prefer HALF_EVEN: it reduces systematic rounding bias across large aggregates.

The bias in action

import java.math.BigDecimal;
import java.math.RoundingMode;

public class BiasDemonstration {
  public static void main(String[] args) {
    String[] ties = {"1.005", "1.015", "1.025", "1.035", "1.045",
                     "1.055", "1.065", "1.075", "1.085", "1.095"};
    
    BigDecimal sumHalfUp = BigDecimal.ZERO;
    BigDecimal sumHalfEven = BigDecimal.ZERO;
    BigDecimal trueSum = BigDecimal.ZERO;
    
    System.out.println("Value   -> HALF_UP / HALF_EVEN");
    for (String tie : ties) {
      BigDecimal bd = new BigDecimal(tie);
      BigDecimal roundedUp = bd.setScale(2, RoundingMode.HALF_UP);
      BigDecimal roundedEven = bd.setScale(2, RoundingMode.HALF_EVEN);
      
      System.out.println(tie + " -> " + roundedUp + " / " + roundedEven);
      
      sumHalfUp = sumHalfUp.add(roundedUp);
      sumHalfEven = sumHalfEven.add(roundedEven);
      trueSum = trueSum.add(bd);
    }
    
    System.out.println();
    System.out.println("HALF_UP sum:   " + sumHalfUp);
    System.out.println("HALF_EVEN sum: " + sumHalfEven);
    System.out.println("True sum:      " + trueSum.setScale(2));
  }
}

Output:

Value   -> HALF_UP / HALF_EVEN
1.005 -> 1.01 / 1.00
1.015 -> 1.02 / 1.02
1.025 -> 1.03 / 1.02
1.035 -> 1.04 / 1.04
1.045 -> 1.05 / 1.04
1.055 -> 1.06 / 1.06
1.065 -> 1.07 / 1.06
1.075 -> 1.08 / 1.08
1.085 -> 1.09 / 1.08
1.095 -> 1.10 / 1.10

HALF_UP sum:   10.55
HALF_EVEN sum: 10.50
True sum:      10.50

Ten values. A nickel of drift. Scale that to millions of transactions.

The “pennies from heaven” problem

If you process millions of transactions where ties are common, HALF_UP can consistently favor one party. That might mean your company “wins” fractions of a cent more often than it “loses”. That sounds fun until regulators, auditors, or customers notice.

So the question isn’t “which is mathematically correct?” The question is:

Which rounding policy matches the domain contract?

Rounding is not only mode. It’s also when.

Two designs:

1. Round at every step (easy, often wrong)
2. Keep high precision internally, round only at boundaries (harder, usually right)

Example: line items and invoices

Consider:

• Price per item has 4 decimal precision
• Currency is 2 decimals
• Taxes computed on totals, not per line (common)

If you round too early, the invoice total can differ from the expected ledger total.

Policy choices matter:

• Round each line item then sum
• Sum unrounded lines then round once
• Compute tax per line then sum tax
• Compute tax on total then round tax once

All are “reasonable”. Only one matches your business rules. Pick explicitly. Document it. Test it.

A practical Java pattern: Money as scaled integer

For currency, the simplest correct representation is usually:

• store money as long minor units (cents)
• do arithmetic in integers
• only convert for display

This avoids a lot of BigDecimal overhead and removes the “oops I rounded twice” class of bugs.

Simple Money type (cents)

import java.math.BigDecimal;
import java.math.RoundingMode;

public final class Money {
  private final long cents;

  private Money(long cents) { this.cents = cents; }

  public static Money ofDollars(String amount) {
    // Parse exact decimal dollars, then scale to cents.
    // This version rounds permissively; see ofDollarsStrict for validation.
    BigDecimal bd = new BigDecimal(amount).setScale(2, RoundingMode.HALF_EVEN);
    return new Money(bd.movePointRight(2).longValueExact());
  }

  /**
   * Strict version: reject inputs that aren't exactly 2 decimals.
   * @throws ArithmeticException if rounding would be required
   */
  public static Money ofDollarsStrict(String amount) {
    BigDecimal bd = new BigDecimal(amount).setScale(2, RoundingMode.UNNECESSARY);
    return new Money(bd.movePointRight(2).longValueExact());
  }

  public Money plus(Money other) {
    return new Money(Math.addExact(this.cents, other.cents));
  }

  /**
   * Multiply by a factor with explicit rounding policy.
   * Notice we round only at the boundary where we return to cents.
   * In production, consider taking a BigDecimal factor to avoid parsing repeatedly.
   */
  public Money times(String factor, RoundingMode mode) {
    BigDecimal bd = BigDecimal.valueOf(cents)
        .movePointLeft(2)
        .multiply(new BigDecimal(factor))
        .setScale(2, mode);
    return new Money(bd.movePointRight(2).longValueExact());
  }

  public BigDecimal toBigDecimal() {
    return BigDecimal.valueOf(cents).movePointLeft(2);
  }

  @Override
  public String toString() { return toBigDecimal().toPlainString(); }
}

Note the vibe:

• parse from string
• scale explicitly
• rounding mode is a parameter for “policy points”
• internal storage is integer cents

A design choice worth calling out: The ofDollars method silently rounds inputs like “10.129” to “10.13”. Sometimes that’s desired for display money. For payments and ledgers, ofDollarsStrict is often safer - it rejects inputs that aren’t already at 2 decimals, forcing upstream validation.

For multi-currency systems, you’d add a Currency field and ensure you never mix currencies in arithmetic. But the core pattern stays the same: integers internally, rounding only at boundaries.

Quick guide: what each rounding mode is “for”

This is not law. This is a field guide.

Use HALF_EVEN when…

You are aggregating lots of rounded values and want less bias. Accounting ledgers, interest accrual across many accounts, large-scale reporting.

Use HALF_UP when…

The domain explicitly expects “schoolbook rounding”. Retail display prices, some tax jurisdictions, human-facing calculations where policy says “.5 rounds up”.

Use DOWN when…

Truncation is explicitly required. Some fee calculations or conservative estimates where you must not exceed a cap.

Use CEILING or FLOOR when…

The direction matters with sign:

• CEILING is “toward positive infinity” (-1.231 -> -1.23, 1.231 -> 1.24 at 2dp)
• FLOOR is “toward negative infinity” (-1.231 -> -1.24, 1.231 -> 1.23 at 2dp)

These are great for constraints, limits, and compliance rules.

Use UNNECESSARY when…

You want your program to scream the instant it encounters a value you didn’t expect to need rounding. This is amazing in intermediate validation and testing.

BigDecimal subtotal = new BigDecimal("12.34");
BigDecimal rate = new BigDecimal("0.075");
BigDecimal tax = subtotal.multiply(rate);

// Fail fast if tax isn't exactly representable at 2 decimals as required by policy
tax = tax.setScale(2, RoundingMode.UNNECESSARY);

That exception is not a nuisance. It’s a spotlight on an assumption you forgot you made.

The moral of the story

HALF_UP is not evil. It’s just not universal.

Rounding modes are not “implementation details”. They are product decisions with maths clothing on.

Pick them like you pick authorization rules: explicitly, testably, and with a paper trail.

TL;DR

• Ties (first discarded digit is 5, rest are zeros) are where rounding policy matters most.
• HALF_UP is intuitive but can introduce bias at scale.
• HALF_EVEN often reduces bias for aggregates.
• Avoid rounding double values when policy matters. Use BigDecimal created from strings or scaled integers.
• Prefer BigDecimal.valueOf(double) over new BigDecimal(double) when you must start from a double - but remember it’s not a cleansing ritual.
• Decide when you round, not just how you round.
• Prefer rounding once at boundaries, not repeatedly in the middle.
• Use UNNECESSARY to catch “we assumed this would be exact” bugs early.

In Part 6, we learned to defend against NaN by validating at boundaries. Now we tackle a different kind of quiet failure: when your sum is correct at every step but still wrong at the end.

Your sum is lying.

Not maliciously. Not even dramatically. Just politely.

Floating point is like a tidy accountant with limited paper. Every addition gets written down with a fixed number of significant digits, rounded neatly, and the scraps are swept off the desk.

Most of the time the scraps do not matter.

Until they do.

This post is the full story of Kahan summation: a small trick with a big impact. It does not make floating point exact. It does stop your totals from quietly losing meaningful contributions when you add lots of numbers.

The crime scene: the innocent-looking loop

Classic numerical analysis textbooks (here in Fortran, the lingua franca of 1960s numerics) love this tiny loop because it looks harmless and then betrays you.

S = 0.0
DO 4 I = 1, N
  YI = ...
4 S = S + YI

That last line is the whole drama: S = S + YI.

People then drop a line like this:

Rounding or truncation in the addition can contribute to a loss of almost $\log_{10}(N)$ significant decimal digits in S.

That $\log_{10}(N)$ sounds like wizardry.

It is not.

It is just fixed precision colliding with a growing running total.

Why you can lose about log10(N) digits

Assume base-10 floating point with p significant decimal digits. (IEEE 754 is base 2, but the intuition transfers cleanly.)

Assume the YI values are roughly the same size and mostly the same sign, so the sum grows instead of canceling. Let a typical magnitude be |Y|.

After N terms, the true sum is roughly:

Now the key floating point constraint: a p digit floating number around magnitude |S| cannot represent arbitrarily tiny changes. Near S, the spacing between representable values is about:

Think of $\Delta S$ as the width of the grid lines at the altitude where S lives.

When you do S = S + YI, the result is rounded back to p digits. Any increment much smaller than $\Delta S$ can vanish.

At the end, |S| \approx N|Y|, so the grid spacing near the final sum is:

Compare the grid spacing to the size of a typical addend:

That ratio is the punchline.

Multiplying by N shifts magnitudes by $\log_{10}(N)$ decimal digits. So as the running sum grows by a factor of N, the rounding grid spacing grows by the same factor. Relative to the scale of the things you are adding, you effectively lose about $\log_{10}(N)$ digits.

Another way to say it:

A concrete gut punch

Suppose you have about p = 7 significant decimal digits (single-ish precision). Sum N = 10^6 numbers of size about 1.

$\log_{10}(10^6) = 6$

So you can be left with roughly:

$7 - 6 = 1$ meaningful decimal digit at the scale of 1

By the time S reaches around one million, the grid spacing near S is roughly:

$10^6 \cdot 10^{-7} = 10^{-1} = 0.1$

So adding 0.01 can literally do nothing. It gets rounded away.

This is the core problem: not rounding once, but rounding a million times while the running total keeps inflating.

A quick demo: sums that look reasonable and are still wrong

Here is a classic cancellation trap:

double x = 1e16;
double naive = (x + 1.0) + 1.0 - x;   // commonly prints 0.0
System.out.println(naive);

The two + 1.0 additions happen while the running value is around 1e16. At that scale, 1.0 can be smaller than the spacing between representable doubles, so it falls through the cracks.

If your system does analytics, pricing, telemetry, risk, recommendations, ranking, or anything where N gets large, this is not a cute corner case. It is the default failure mode hiding inside an innocent reduction.

Kahan summation: sweeping the crumbs back into the pile

Kahan summation is compensated summation.

It keeps two numbers:

• sum: the running total
• c: a compensation term that tracks what rounding threw away last time

The mental model:

sum is the big obvious pile.

c is the tiny IOU note: the bits that tried to join the party and got turned away at the door.

The algorithm

Given a new addend x:

1. Adjust the addend by what we lost previously
2. Add it
3. Update the compensation by estimating what got lost this time

y = x - c
t = sum + y
c = (t - sum) - y
sum = t

That is the entire trick.

It does not change the floating point rules. It changes your strategy so the rules hurt you less.

Java implementation: a small accumulator with big consequences

The accumulator type

public final class KahanAccumulator {
  private double sum;
  private double c; // compensation for lost low-order bits

  public void add(double x) {
    double y = x - c;
    double t = sum + y;
    c = (t - sum) - y;
    sum = t;
  }

  public void combine(KahanAccumulator other) {
    // Merge another partial sum into this one.
    // This improves accuracy, but the result is still order-dependent.
    this.add(other.sum);
    this.add(other.c);
  }

  public double value() {
    return sum;
  }
}

A note worth stating clearly:

Kahan improves accuracy a lot, but floating point addition is still not associative, so parallel reductions can still differ run to run because order differs. Kahan makes the wobble smaller, not impossible.

Using it with Streams

Option A: DoubleStream.collect (best for primitive streams)

DoubleStream has its own collect overload that avoids boxing.

import java.util.stream.DoubleStream;

public final class Kahan {

  private Kahan() {}

  public static double sum(DoubleStream stream) {
    KahanAccumulator acc = stream.collect(
        KahanAccumulator::new,
        KahanAccumulator::add,
        KahanAccumulator::combine
    );
    return acc.value();
  }
}

Usage:

double s1 = Kahan.sum(DoubleStream.of(0.1, 0.2, 0.3));
double s2 = Kahan.sum(myDoubleStream.parallel()); // allowed, order still not fixed

Option B: a Collector (nice ergonomics for boxed streams)

This is convenient when you already have a Stream<Double>.

import java.util.stream.Collector;

public final class KahanCollectors {

  private KahanCollectors() {}

  public static Collector<Double, KahanAccumulator, Double> kahanSummingDouble() {
    return Collector.of(
        KahanAccumulator::new,
        (acc, x) -> acc.add(x),
        (a, b) -> { a.combine(b); return a; },
        KahanAccumulator::value
    );
  }
}

Usage:

double s = myStreamOfDoubles.collect(KahanCollectors.kahanSummingDouble());

Correctness: what to test, and what not to promise

What you should promise

• Better accuracy than naive summation for large N and wide dynamic ranges
• Explicit behavior you control and can review in code

What you should not promise

• Bit for bit deterministic results in parallel streams
• Exactness for money or decimal accounting

JUnit test idea: compare against a higher-precision reference

BigDecimal is not a perfect oracle for binary floating point, but it is a very useful reference when you want to see whether one summation strategy is drifting more than another.

import static org.junit.jupiter.api.Assertions.*;
import java.math.BigDecimal;
import java.util.Random;
import java.util.stream.DoubleStream;
import org.junit.jupiter.api.Test;

public class KahanAccumulatorTest {

  @Test
  void kahan_is_usually_better_than_naive_on_wide_range_data() {
    Random r = new Random(0);

    double[] xs = DoubleStream.generate(() -> {
      double sign = r.nextBoolean() ? 1.0 : -1.0;
      double mag = Math.pow(10.0, r.nextInt(20) - 10); // 1e-10 .. 1e9
      return sign * mag * r.nextDouble();
    }).limit(200_000).toArray();

    double naive = 0.0;
    KahanAccumulator kahan = new KahanAccumulator();
    BigDecimal ref = BigDecimal.ZERO;

    for (double x : xs) {
      naive += x;
      kahan.add(x);
      ref = ref.add(BigDecimal.valueOf(x));
    }

    // Reference converted back to double so we compare at double resolution.
    double reference = ref.doubleValue();

    double errNaive = Math.abs(naive - reference);
    double errKahan = Math.abs(kahan.value() - reference);

    // In rare adversarial sequences Kahan can be slightly worse, but typically it's much better.
    assertTrue(errKahan <= errNaive * 2.0,
        String.format("Kahan error (%.2e) vs naive (%.2e)", errKahan, errNaive));
  }
}

Performance: what it costs

Naive sum does one add per element.

Kahan does a few extra operations per element. That is a small constant factor. In many analytics pipelines the accuracy gain is worth far more than the extra CPU.

If you want to measure overhead, use JMH and compare:

• naive loop
• DoubleStream.sum()
• Kahan loop
• Kahan via DoubleStream.collect

When NOT to use Kahan

• Financial calculations: use BigDecimal for money. Period. Kahan does not give you decimal semantics.
• Tiny datasets: if N is small, the overhead is rarely worth it.
• Hard real time, tight latency budgets: profile first.

Variants worth mentioning: Neumaier and pairwise summation

Kahan is great. It is not the only move.

Neumaier summation is a small tweak that can behave better when the next addend is larger than the running sum.

// Neumaier variant
public final class NeumaierAccumulator {
  private double sum;
  private double c;

  public void add(double x) {
    double t = sum + x;
    if (Math.abs(sum) >= Math.abs(x)) {
      c += (sum - t) + x;
    } else {
      c += (x - t) + sum;
    }
    sum = t;
  }

  public double value() {
    return sum + c;
  }
}

Pairwise summation (tree reduction) reduces error growth by summing numbers of similar magnitude together. Some stream implementations may do something like this internally, but the key benefit of writing your own is that you make the behavior explicit and reviewable.

When to use what

Use BigDecimal when you need decimal semantics and you mean it.

Use naive summation when N is small, magnitudes are similar, and you truly do not care.

Use Kahan (or Neumaier) when:

• N is large (thousands to millions of values)
• values span many orders of magnitude
• small contributions matter
• you want better accuracy without dragging BigDecimal everywhere

A note on BigDecimal vs Kahan (so we don’t mix the tools)

BigDecimal and Kahan solve different problems. BigDecimal is about decimal semantics (money, accounting, “pennies must add up,” explicit rounding rules). Kahan is about double accumulation error (metrics, measurements, statistics, ML features, telemetry) when double is the right representation but naive summation bleeds low-order bits.

• If your requirements mention cents, statements, taxes, interest, regulatory accuracy, or mandated rounding policies → use BigDecimal (and decide scale + rounding mode explicitly).
• If your requirements mention large aggregates, mixed magnitudes, order sensitivity, or “why did parallel give a different total?” → keep double, but upgrade the summation (Kahan/Neumaier/pairwise) and be explicit about ordering if determinism matters.

Also, BigDecimal only stays “decimal-correct” if you construct it correctly (prefer parsing from decimal text, or BigDecimal.valueOf(double) over new BigDecimal(double)).

Closing

Floating point is not broken. It is finite.

The tragedy is not that rounding happens.

The tragedy is when rounding happens quietly and repeatedly and nobody is keeping score.

Kahan summation is you keeping score.

A small second variable, standing in the corner with a clipboard, refusing to let the crumbs vanish without a fight.

References

• W. Kahan, “Pracniques: Further remarks on reducing truncation errors,” Communications of the ACM, 8(1), Jan. 1965. DOI (ACM Digital Library): https://dl.acm.org/doi/10.1145/363707.363723

Open PDF (hosted copy): https://convexoptimization.com/TOOLS/Kahan.pdf

Metadata entry (Semantic Scholar): https://www.semanticscholar.org/paper/Pracniques%3A-further-remarks-on-reducing-truncation-Kahan/672a99813f52aed720d3508d6be7db461328b064

• Prof Kahan’s Assorted Notes, https://people.eecs.berkeley.edu/~wkahan/

• N. J. Higham, “The Accuracy of Floating Point Summation”, SIAM Journal on Scientific Computing (1993). https://doi.org/10.1137/0914050

• DoubleStream.sum(): https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/stream/DoubleStream.html#sum()

• DoubleSummaryStatistics: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/DoubleSummaryStatistics.html

But a shortcut is not the same thing as the truth.

This post started the way many modern thoughts begin: with a social media thread.

I saw a post about “student drivers” which soon turned into a generalization about an entire people. Someone responded by generalizing Indians in one long breath, without the courtesy of a comma, a semicolon, or a full stop.

The irony wasn’t subtle. The emotional whiplash wasn’t either.

This isn’t only about Indians. Or Americans. Or any one group. It’s about a habit of mind we’ve normalized: reducing millions of people into a neat sentence and calling it “an observation.”

The world is too large for our brains

Human brains are pattern machines. We find faces in clouds. We infer intent from a raised eyebrow. We build models of reality because raw reality is too big to hold.

That instinct isn’t evil. It’s survival.

The problem begins when we confuse the model for the world.

A stereotype is what happens when you take a small sample, add emotion, toss in a few viral anecdotes, and then export it as a universal law.

It feels efficient. It feels satisfying. It feels like closure.

It’s also how we end up misreading entire peoples.

“Indians are…” is a sentence that breaks under its own weight

India isn’t a monolith. It’s a continent-sized civilization, with many languages, many histories, many moral philosophies, many economic realities, and many ways of being human.

So when someone says “Indians are X,” what they’re often saying is something closer to:

“I met some Indians.”
“I saw a few videos.”
“I had one bad experience.”
“I read a thread that made me feel righteous.”

And then the brain does its favorite magic trick: it turns an anecdote into an identity.

That’s not insight. That’s laziness with confidence.

The equal and opposite mistake

Here’s the twist: the antidote to “Indians are…” is not “Americans are…”

The United States is the third-largest country in the world by population. It contains multitudes: regions that feel like different planets, communities built from different migrations, value systems that clash, and identities that don’t fit into clean boxes.

So yes, broad generalizations about Americans are unfair.

But this is exactly how conversations collapse into noise: people respond to one stereotype by throwing another stereotype back like a dodgeball.

The result isn’t justice. It’s just more laziness, moving faster.

The “small loud group” problem

A common defense goes like this:

“I’m not generalizing everyone. I’m talking about a certain kind of person.”

Sometimes that’s true. Social media amplifies extremes. Outrage is algorithmic fuel. The loudest voices get the mic even when they represent very little.

But adult conversation requires adult precision.

There’s a big difference between:

1. “Some people are doing this harmful thing.”
2. “This group is like this.”

The first is a claim about behavior. It can be debated, measured, challenged, and refined.

The second is a claim about identity. It essentializes. It turns a behavior into a blood type.

That’s the line. That’s the whole game.

Why stereotypes feel so good

Stereotypes offer three things the internet loves:

Certainty: “I understand what’s going on.”
Speed: “I don’t need to do the work.”
Permission: “Now I can judge.”

Real understanding is slower. It requires friction. It requires the irritating humility of saying, “I might be wrong,” and then gathering better evidence like a grown-up scientist.

This is what philosophers call epistemic humility¹. It is the recognition that our knowledge is always incomplete, our samples always limited, our certainty always provisional.

It’s the opposite of what social media rewards.

That’s harder than typing a hot take.

A better way to speak

If you want to criticize a pattern without flattening people into cardboard cutouts, here are healthier defaults:

• Speak about specific behaviors, not identities.
• Use “some” and “in my experience” like seatbelts.
• Separate “what I saw” from “what is true.”
• Ask whether your sample is representative or just memorable.
• When you feel righteous, pause. Righteousness is not a fact-checker.

If your goal is to be understood, precision is kindness.

Immigrants live inside the blur

Immigrants often occupy a strange space. You learn to love the country you live in while also carrying the ache of being misread. You become bilingual not just in language, but in assumptions.

Sometimes you’re treated as an ambassador for a billion people.
Sometimes you’re treated as an exception: “You’re not like the others.”
Sometimes you’re reduced to a meme.

And through it all, you still show up. You contribute. You build. You teach. You try to belong without having to dissolve.

So when someone stereotypes a group, it isn’t “just words.”
It’s a tiny social verdict that sticks.

The point

Even saying “everyone stereotypes” would be unfair (which is, awkwardly, the entire point of this post).

After that thread, I also received kind messages from people in my local community offering support and apologizing “on behalf of” others. The intent was generous, and I appreciated it.

But even there, I felt the shadow of the same mistake: the idea that there is a “them” to speak for.

There shouldn’t be.

We don’t defeat stereotypes by pretending differences don’t exist. We defeat stereotypes by being honest about complexity.

By trading lazy certainty for careful clarity.
By resisting the cheap thrill of the sweeping sentence.
By remembering that every “they” is made of millions of “someone.”

The world is weird and diverse and stubbornly detailed.

That’s not a problem to solve.
That’s the whole miracle.

References and Notes

NaN is not a bug. It is a receipt.

A little slip of paper IEEE 754 hands you after your math did something undefined, and instead of crashing the universe, the CPU says, “Not a number, friend,” and keeps walking.

That is noble. That is also how NaN quietly sneaks into your systems, wears your log files as a cape, and turns your dashboards into modern art.

This post is about defending against NaN without turning your codebase into a forest of anxious if (isNaN) tripwires.

The shape of the beast

So what exactly is this receipt for?

NaN stands for “Not a Number.” Expand it once, then treat it like a proper noun: NaN.

You get NaN from operations that have no real number answer, such as: 1. 0.0 / 0.0
2. Math.sqrt(-1.0)
3. Math.log(-1.0)
4. Any operation that already contains NaN, because NaN is contagious in the best and worst ways

Java follows IEEE 754 here. The JVM will not throw an exception for most floating point invalid operations. It will produce NaN (or Infinity), and your program continues with a tiny invisible crack in reality.

Here is the first mind-bending property:

NaN is not equal to anything, including itself.

double x = Double.NaN;

System.out.println(x == x);              // false
System.out.println(Double.isNaN(x));     // true
System.out.println(x < 0);              // false
System.out.println(x > 0);              // false
System.out.println(x == 0);             // false

So NaN does not behave like a “value” in the usual sense. It behaves like a signal masquerading as a value.

That disguise is the whole problem.

Defensive programming hell: “Checkpoint Syndrome”

The naive reaction is understandable:

You discover NaN in production.
You add checks.
You discover it again.
You add more checks.
Eventually every function looks like airport security staffed by anxious squirrels.

You get code like:

double price = computePrice(input);
if (Double.isNaN(price) || Double.isInfinite(price)) {
    // shrug, return 0?
}

This is Checkpoint Syndrome because:
1. It spreads everywhere.
2. It hides the real cause. The first invalid operation is upstream.
3. It forces you to decide “what now” in a dozen places, inconsistently.
4. It often converts “unknown” into “zero,” which is how financial bugs are born.

The antidote is not “more checks.” The antidote is better geometry - put the checks where they matter, once, with intent.

The core principle: validate at the edges, compute in the middle

Most NaN outbreaks begin at boundaries:
1. Parsing and deserialization (CSV, JSON, user input, partner payloads)
2. Sensor-style data (telemetry, percentages, rates)
3. Divide by something that might be zero or missing
4. “This should never happen” conversions (and then it happens)

Your best defense is to establish a simple contract:

Inside the computation core, all doubles are finite unless explicitly documented otherwise.

The computation core is the part of your system that should be blissfully boring: the pure math functions, the algorithms, the business logic that assumes validated inputs. The place where you want to reason about correctness without also doing border control.

That means you concentrate NaN handling in a few choke points.

Pattern 1: “Finite by default” as a guardrail

Create a tiny helper that asserts finiteness.

static double requireFinite(double x, String name) {
    if (!Double.isFinite(x)) {
        throw new IllegalArgumentException(name + " must be finite, got " + x);
    }
    return x;
}

Why Double.isFinite() is your single weapon: It returns true only when x is neither NaN nor Infinity - exactly what “finite by default” means. You don’t need two checks (isNaN and isInfinite). You need one: “is this a normal, usable number?”

Use it at public boundaries and layer transitions, not inside every private method.

public double monthlyPayment(double principal, double annualRate, int months) {
    requireFinite(principal, "principal");
    requireFinite(annualRate, "annualRate");
    if (months <= 0) throw new IllegalArgumentException("months must be positive");

    double r = annualRate / 12.0;

    // Standard annuity formula:
    //   P = L * [r(1+r)^n] / [(1+r)^n - 1]
    // Rewritten with a negative exponent:
    //   P = L * r / (1 - (1+r)^(-n))
    // Same math, often friendlier numerically for large n.
    return principal * r / (1.0 - Math.pow(1.0 + r, -months));
}

This gives you three wins:
1. The failure is loud and early.
2. The computation stays clean.
3. The exception points to a real contract violation, not a mysterious downstream symptom.

Pattern 2: Separate “invalid” from “zero” with a result type

Sometimes you cannot throw. Sometimes your caller needs to continue, but also needs to know the answer is invalid.

So represent that truth explicitly.

In Java, you can use a sealed interface to create a true disjunctive type (see my post on disjunctive types for the full story):

sealed interface CalcResult permits CalcResult.Valid, CalcResult.Invalid {
    
    record Valid(double value) implements CalcResult {
        public Valid {
            // Enforce finite values in Valid variant
            if (!Double.isFinite(value)) {
                throw new IllegalArgumentException("Valid result must be finite");
            }
        }
    }
    
    record Invalid(String reason) implements CalcResult {}
    
    // Convenience factory methods
    static Valid ok(double value) {
        return new Valid(value);
    }
    
    static Invalid failed(String reason) {
        return new Invalid(reason);
    }
}

Now NaN is no longer a stealth signal. Invalid states are impossible to construct incorrectly, and the compiler enforces exhaustive handling.

CalcResult safeDivide(double a, double b) {
    if (!Double.isFinite(a) || !Double.isFinite(b)) {
        return CalcResult.failed("non-finite input");
    }
    if (b == 0.0) {
        return CalcResult.failed("division by zero");
    }
    return CalcResult.ok(a / b);
}

// Pattern matching is exhaustive - compiler forces you to handle both cases
CalcResult result = safeDivide(10.0, 2.0);
switch (result) {
    case CalcResult.Valid(double v) -> 
        System.out.println("Result: " + v);
    case CalcResult.Invalid(String reason) -> 
        System.err.println("Failed: " + reason);
    // No default needed - this is exhaustive
}

The point is not the exact type. The point is the discipline: invalid is a first-class outcome, and the type system prevents you from accidentally treating it as valid.

Pattern 3: Domain types that make NaN impossible

Many doubles in business systems are not “real numbers in the wild.” They are money, rates, counts, durations, percentages.

Those are not great candidates for raw double.

A few examples:
1. Money: store cents as long, or use BigDecimal where precision matters
2. Counts: long or int
3. Percentages: maybe basis points as int (one basis point = 0.01%, so 550 bps = 5.50%)
4. Durations: java.time.Duration

When you tighten types, you reduce the surface area where NaN can even appear. That is the most reliable NaN defense there is: make the invalid state unrepresentable.

NaN cannot enter a long. It can only stand outside and glare.

Pattern 4: Decide where Infinity is acceptable

Part 5 covered Infinity and signed zero. Here is the practical angle.

Infinity can be a legitimate signal in some domains:
1. “Unlimited” limit
2. “Unbounded” score
3. A mathematical asymptote that you intentionally model

But if your domain does not explicitly accept Infinity, treat it exactly like NaN - reject both at the boundary with Double.isFinite(). This is why requireFinite uses that single check: it enforces “no NaN, no Infinity” in one line.

If you do need to distinguish between NaN and Infinity (rare), check them separately. But for most code, “not finite” is the only distinction that matters.

The bug pattern is when Infinity is tolerated accidentally and later multiplied into a massive number that looks plausible, which is how nonsense becomes confident nonsense.

Pattern 5: Centralize sanitization, but do not lie

Sometimes you must “sanitize” bad inputs, especially with messy external data. The key is: do it once, do it centrally, and record what you did.

A dangerous sanitization is this:

double safe = Double.isFinite(x) ? x : 0.0;

That turns “unknown” into “zero,” and zero is not neutral in most systems.

A safer pattern is to either:
1. Drop the datapoint (for aggregates), and count it
2. Mark the result invalid
3. Fall back to a documented default that has real meaning, and log it

Example for aggregation:

double averageFinite(double[] xs) {
    double sum = 0.0;
    int n = 0;

    for (double x : xs) {
        if (Double.isFinite(x)) {
            sum += x;
            n++;
        }
    }

    // Honest answer: no valid data means undefined result.
    if (n == 0) return Double.NaN;

    return sum / n;
}

Notice the honesty: if nothing valid exists, we do not pretend.

Third-party libraries: when NaN arrives by mail

Sometimes NaN isn’t born in your code. It is delivered.

The most common culprit is calling math functions that can legitimately return NaN for part of their domain, and forgetting that you just crossed into “inputs must be validated” territory again.

Check immediately after the call, while you still have context.

double result = Math.sqrt(userInput);

// JDK math functions and third-party libs can return NaN.
// Validate the output right away, at the point of crossing.
requireFinite(result, "sqrt result");

This pattern generalizes: any time you call out to code you don’t control (libraries, services, models, partner feeds), treat the return value as a new boundary.

Finding the first NaN, not the last one

A common tragedy is you only detect NaN at the end, in a report, after ten transformations. At that point NaN is the smoke, not the fire.

Two practical tricks:

Add “tripwire assertions” in debug builds

In places where NaN should never exist, assert it in tests and in non-production modes.

static void assertFinite(double x, String name) {
    if (!Double.isFinite(x)) {
        throw new AssertionError(name + " became non-finite: " + x);
    }
}

Call it after major computation steps in critical algorithms, especially ones that are numerically sensitive.

Log with context once, not everywhere

If you need observability, centralize it. For example, in an input adapter:

double parseRate(String raw) {
    double x = Double.parseDouble(raw);
    if (!Double.isFinite(x)) {
        // log raw payload id, customer id, partner id, etc.
        throw new IllegalArgumentException("rate must be finite");
    }
    return x;
}

This is where you actually still have context: the original data and the identity of the source.

Downstream, you mostly have regret.

A small NaN hygiene checklist

1.	Use Double.isFinite at boundaries where values enter your system or cross layers
2.	Keep computation code clean; assume finite inputs inside the core
3.	Do not convert invalid to zero unless the domain definition says it is correct
4.	Prefer domain types over raw doubles when the value is not truly "a real number"
5.	When you must degrade gracefully, return an explicit invalid result, not a silent sentinel
6.	Instrument the boundary where you reject or drop invalids, so you can find the upstream cause

NaN is not evil. It is your system trying to stay alive after stepping on a rake.

Your job is not to sprinkle rakes with warning stickers. Your job is to stop leaving rakes in the hallway.

1) Consolidated assets into one place

Previously the site had both public/ and assets/, which caused confusion and occasional broken paths. I merged everything into assets/ and updated all references.

What changed

• CSS, JS, and favicon files moved from public/ to assets/.
• All templates now link to /assets/....
• The web manifest and webcmd page were updated to the new paths.

Why it helps readers

• Fewer path mismatches means fewer broken resources.
• Simpler structure makes maintenance faster, which reduces future regressions.

2) Modernized the favicon setup

I added an SVG favicon and kept the ICO fallback for broad support.

What changed

• assets/favicon.svg is now the primary favicon.
• assets/favicon.ico remains as a fallback.
• The <link rel="icon"> tags were updated accordingly.

Why it helps readers

• SVG is crisp at any size; it looks sharper on modern devices.
• ICO fallback preserves compatibility on older browsers.

3) Webcmd got a real upgrade

/webcmd/ is still the command-line page – but it now matches the rest of the site and behaves more predictably.

What changed

• Webcmd now uses the default layout and site theme.
• The command UI is more readable and consistent with the Nord palette.
• Help output is semantic (lists + headings), easier to scan, and displayed in two columns on desktop.
• The find command now appears in the Searches section (where it belongs).
• Navigation commands (ph, p, pi, pr) now use relative URLs so they stay on localhost when you are testing.

Why it helps readers

• The page is easier to read and use, especially on mobile.
• Commands work the same in dev and production.
• The help panel is much more legible.

4) Accessibility pass (WCAG-oriented)

I did a focused accessibility sweep across the main site templates (excluding jsgames/) with WCAG 2.1 AA as the target.

What changed

• Added a Skip to content link and a proper <main> landmark.
• Sidebar toggle now updates aria-expanded and is keyboard-operable.
• The search overlay now traps focus and restores focus on close.
• “Annotate me” is now a real <button> (not a clickable <span>).
• Improved focus styles and general keyboard flow.

Why it helps readers

• Keyboard users can reach content faster.
• Screen reader navigation is clearer and more predictable.
• Dialog behavior is now much closer to expected modal behavior.

5) Reduced Disqus noise on non-post pages

Disqus counts were being loaded everywhere. Now they only load on posts that explicitly allow comments.

Why it helps readers

• Less third-party JS on pages that do not need it.
• Cleaner performance and fewer surprise widgets.

6) New documentation

To keep this sustainable, I wrote a few new internal docs:

• docs/webcmd.md explains how the command engine works and how to add new commands.
• docs/accessibility.md captures accessibility conventions and checks.
• The README was updated to link to both.

In short

This was a maintenance sweep – but the impact is tangible: the site is more consistent, easier to navigate, more accessible, and easier to extend.

If you notice anything off, ping me. Otherwise, I will keep iterating on the small stuff that makes reading feel smooth.

The quote was lifted from an Economic Times editorial titled “The PM gets it right” (Feb 15, 2011). Its diagnosis was simple and brutal: we modernised inputs, not marketing. We built an “inefficient chain” between farmer and consumer, so when retail prices spike, the farmer often sees none of the upside.

Fifteen years later, I want to rewrite that post with a real spine. Same thesis, sharper tools, newer facts, and one stubborn protagonist.

A tomato.

A tomato leaves the farm

Picture this as an illustrative journey, not a specific news report.

A farmer harvests tomatoes at dawn. By afternoon, the tomatoes have become a logistics problem wearing a red costume.

They need sorting and grading. They need crates that do not crush. They need shade. They need pre-cooling. They need transport that does not turn every bump into bruising. They need a buyer whose “price” does not change like mood.

If any link in that chain is weak, the farmer does the only rational thing available under pressure.

Sell fast. Sell cheap. Move on.

Later the same week, the city consumer complains about expensive tomatoes. The farmer hears that complaint like a rumour from another planet.

That gap is the black box.

Back in 2011, I quoted this line (still painfully accurate): the linkage between the farmer and the consumer is inefficient, wasteful, and subject to manipulation, so shortages trigger hoarding and price spikes at the consumer end without sending those higher prices back to the farmer. When price signals do not reach the farm, incentives die.

So what changed between 2011 and 2026?

Enough to matter. Not enough to relax.

2011 said “fix marketing.” 2026 says “fix time.”

Tomatoes are not merely bought and sold. They are raced.

A post-harvest system is basically a machine for buying time. Cold chain buys time. Warehousing buys time. Credit buys time. Transparent markets buy time by reducing predatory uncertainty.

India’s big story since 2011 is that we started building and financing “time.”

Change 1: We started paying for the boring parts

The Agriculture Infrastructure Fund (AIF) is a government financing facility launched in 2020–21 to support post-harvest and farm-gate infrastructure through interest subvention and credit guarantee support.

As of June 30, 2025, the Press Information Bureau (PIB) reported ₹66,310 crore sanctioned under AIF for 1,13,419 projects, mobilising ₹1,07,502 crore of investment, including 2,454 cold storage projects.

This is not a philosophical change. It is a cash-flow change. And supply chains love cash-flow.

Change 2: Cold chain scaled, and policy got more specific

The Ministry of Food Processing Industries (MoFPI) runs the Integrated Cold Chain and Value Addition Infrastructure (ICCVAI) scheme under the Pradhan Mantri Kisan Sampada Yojana (PMKSY).

As of June 2025, 395 integrated cold chain projects had been approved since 2008, with 291 operational, creating preservation capacity of 25.52 lakh metric tonnes (LMT) per year and processing capacity of 114.66 LMT per year.

MoFPI also notes a key policy shift in June 2022: support for fruit and vegetable cold chain projects under that scheme component was discontinued and the sector was shifted to Operation Greens.

In plain terms: the government stopped pretending every crop has the same bottlenecks.

For our tomato, this matters. Not because cold chain is glamorous, but because it turns “sell today or lose everything” into “sell when the price is sane.”

Change 3: Markets became more digital, and more visible

The electronic National Agriculture Market (e-NAM) integrates regulated wholesale markets (mandis) into an online trading platform.

PIB reported that 1,522 mandis were integrated as of June 30, 2025, with 1,79,41,613 farmers and 4,518 Farmer Producer Organisations (FPOs) registered, and total traded value of ₹4,39,941 crore recorded on the platform.

If 2011 was about “price signals,” e-NAM is one attempt to strengthen the signal.

But an honest note: a stronger signal does not automatically fix the physical chain. A dashboard cannot refrigerate a tomato.

Change 4: Farmer collectivisation moved from slogan to infrastructure

A Farmer Producer Organisation (FPO) is a farmer collective that can aggregate produce, negotiate, and invest in shared capabilities.

The “Formation and Promotion of 10,000 FPOs” scheme hit the 10,000 milestone by Feb 2025, according to PIB. The same release describes equity grants and credit guarantee cover supporting thousands of FPOs.

This is quietly revolutionary. A single farmer is forced to accept the chain. A collective can start owning pieces of it.

A tomato handled by an FPO can be graded, packed, stored, and sold with leverage. The same tomato, different fate.

Change 5: Storage plus credit got sharper

In 2011, the farmer’s big enemy was forced timing. In 2026, the fight is increasingly about making “waiting” financially possible.

The Warehousing Development and Regulatory Authority (WDRA) oversees warehousing regulation and electronic warehouse receipt systems. A Parliamentary Standing Committee report notes the growth of pledge finance against electronic Negotiable Warehouse Receipts (eNWRs).

The same report notes the launch on 04-03-2024 of e-Kisan Upaj Nidhi, a digital gateway developed by WDRA in association with NABARD (National Bank for Agriculture and Rural Development) and a task force in SBI (State Bank of India), to connect eNWR with onboarded banks.

This is the most direct antidote to the 2011 problem. If you can store and borrow, you are not forced to sell at the worst possible moment.

The uncomfortable part: loss is still huge

Even with better financing, more cold chain, more digital markets, and stronger farmer collectives, the scale of loss remains enormous.

A 2024 policy brief by the Indian Council for Research on International Economic Relations (ICRIER) cites a NABARD Consultancy Services (NABCONS) 2020–2022 study estimating food loss in India at about ₹1.53 trillion (USD 18.5 billion) annually due to post-harvest losses (PHL). The brief also argues that reducing PHL is often more cost-effective than producing more and losing more.

So yes, we built scaffolding. But we are still leaking value at industrial scale.

So what is the 2026 thesis, using the tomato as proof?

The 2011 editorial said policy must recognise marketing’s role in boosting farm production. I agree, but I want to update the framing.

India’s post-harvest problem is a systems problem where incentives and physics collaborate to bully the weakest player.

Tomatoes punish delay. Markets punish small scale. Credit punishes the poor. Information punishes the disconnected.

Since 2011, India has improved the tools that buy time and improve bargaining power: financing (AIF), cold chain (ICCVAI under PMKSY), digital trading (e-NAM), collectivisation (FPOs), and storage-linked credit (WDRA eNWR and e-Kisan Upaj Nidhi).

Now the real question is not “do we have schemes?”

It is “does our tomato still get forced into the panic-sale path?”

If the answer is yes, the black box still wins.

If the answer becomes no, then the farmer finally gets what the consumer already has.

Choice.

References (links)

1. Original 2011 post on SystemHalted:
   https://systemhalted.in/2011/04/26/whats-wrong-with-our-post-harvest-agricultural-supply-chain/

2. Quoted editorial (2011, original link from my post):
   https://economictimes.indiatimes.com/opinion/et-editorial/the-pm-gets-it-right/articleshow/7499198.cms

3. PIB note on Agriculture Infrastructure Fund (AIF) status (as of 30 June 2025):
   https://www.pib.gov.in/PressNoteDetails.aspx?ModuleId=3&NoteId=154999

4. PIB release on e-NAM registrations and traded value (as of 30 June 2025):
   https://www.pib.gov.in/PressReleasePage.aspx?PRID=2151361

5. PIB release on the 10,000 Farmer Producer Organisations (FPOs) milestone (Feb 28, 2025):
   https://pib.gov.in/PressReleasePage.aspx?PRID=2106913

6. Integrated Cold Chain and Value Addition Infrastructure (ICCVAI) status note (PDF; includes June 2025 stats):
   https://static.pib.gov.in/WriteReadData/specificdocs/documents/2025/oct/doc20251029679501.pdf

7. Parliamentary Standing Committee report (PDF; mentions eNWR pledge finance and e-Kisan Upaj Nidhi launch):
   https://sansad.in/getFile/lsscommittee/Consumer%20Affairs%2C%20Food%20and%20Public%20Distribution/18_Consumer_Affairs_Food_and_Public_Distribution_2.pdf?source=loksabhadocs

8. ICRIER Policy Brief 20 (PDF) summarising the NABCONS 2020–2022 loss estimate:
   https://icrier.org/pdf/Policy_Brief_20.pdf

9. WDRA page describing e-Kisan Upaj Nidhi:
   https://wdra.gov.in/web/wdra/e-kisan-upaj-nidhi

Notes

Abbreviations introduced in this post

• AIF: Agriculture Infrastructure Fund
• PIB: Press Information Bureau
• MoFPI: Ministry of Food Processing Industries
• PMKSY: Pradhan Mantri Kisan Sampada Yojana
• ICCVAI: Integrated Cold Chain and Value Addition Infrastructure
• LMT: lakh metric tonnes
• e-NAM: electronic National Agriculture Market
• Mandi: regulated wholesale agricultural market
• FPO: Farmer Producer Organisation
• WDRA: Warehousing Development and Regulatory Authority
• eNWR: electronic Negotiable Warehouse Receipt
• NABARD: National Bank for Agriculture and Rural Development
• SBI: State Bank of India
• NABCONS: NABARD Consultancy Services
• ICRIER: Indian Council for Research on International Economic Relations
• PHL: post-harvest losses

About the tomato story

The tomato journey section is a simplified narrative device to make the supply chain concrete. It is not a claim about one specific farmer or one specific price spike.

The calendar flipped, the confetti fell, and somewhere a server kept running without caring about our rituals. Respect. Uptime is the real stoicism.

I like New Year because it is the one socially acceptable time to refactor your life in public. No tickets. No sprint planning. Just a quiet reboot and a little audacity.

The year as a compiler

A year is a ruthless compiler. It does not care about intent. It only cares about what actually ran.

You can mean well for months and still ship nothing but good feelings. You can also ship one small thing a week and look back stunned at the pile of proof you accidentally created.

So my 2026 goal is not grandiosity. It is evidence.

Not a dramatic reinvention. A steady sequence of small, honest commits.

What I am optimizing for

I do not want a year that looks impressive from a distance and feels hollow up close.

I want a year that feels calm in the body, clear in the mind, and useful in the world.

A year where my work is sturdy, my learning is intentional, my writing is alive, and my attention is not donated to infinite scroll like a confused philanthropist.

A year with fewer open loops and more finished sentences.

Building, without worshipping the build

As engineers we have a strange tendency to worship motion. Activity feels like virtue. Busy is a costume that passes as importance.

This year I want more stillness around the work. Less frantic switching. More deep time. More time spent on the part where the idea becomes real.

Because real is the only feature that users can actually use.

And yes, that includes the user who is reading this right now and thinking, I should probably finally do the thing. Please do the thing. Your future self is already grateful and slightly smug.

A tiny promise to myself

I will protect my attention like it is production data.

I will read on purpose. I will learn with a map. I will write even when the mood is missing, because craft is what remains after motivation leaves the room.

I will treat health like a prerequisite, not a nice to have.

I will be ambitious, but not brittle.

I will aim for progress that survives a bad day.

I will finally bring Consumption Backlog in Action. What the heck! I will even create an iOS app for it.

The cosmic perspective, because the universe insists

Somewhere above us, photons that left their stars before humans invented arithmetic are still arriving like late emails. The sky is always delivering messages from the past.

That thought makes my problems feel smaller, and my responsibilities feel cleaner.

If the universe can be that old and still be that bright, surely I can be tired and still be kind. Surely I can be uncertain and still begin.

Closing tab

If you are reading this, I hope 2026 brings you three things.

Something to learn that changes how you see the world.

Someone to love who makes the days lighter.

Something to build that makes you proud, quietly, when nobody is watching.

Happy New Year.

Now go ship something small.

My core claim is simple: engineers who set up a task with clear instructions, a thin prototype, and hard guardrails tend to have a better experience with AI-assisted coding, and they tend to keep their good faith in the tools. Engineers who don’t, often walk away with confusion, rewrites, and a lingering sense that the agent is “untrustworthy.” And that’s why the same tool creates opposite stories, depending on who’s holding it.

This post is my framework, Discipline First: a trust pipeline for AI-assisted coding. It’s a small kit you can use immediately: an Agent Brief that makes intent hard to misread, guardrails that make failures visible early, and a one-week experiment that turns belief into evidence.

The axis that matters

The agent isn’t the methodology. Your engineering habits are.

I’m going to be deliberately boring about definitions, because the labels are less important than the axis. Whether you call it vibe coding, agentic coding, or AI-assisted coding, the same split shows up: disciplined delivery versus undisciplined delivery. The tools can draft code, refactor code, even propose architectures, but they can’t rescue a vague task from its own vagueness.

Discipline is what turns “the agent wrote something” into “the system changed, and we can explain why, prove it works, and undo it safely if it doesn’t.”

Four engineers walk into the same tool

And once you see it that way, four kinds of engineers show up around AI-assisted coding.

The Skeptic is driven by quality, security, and maintainability. They are not anti tool. They are pro standards. They will try these tools in a sandbox, or allow them under strict review, and they trust what they can validate through time-tested discipline: tests, contracts, architecture checks, and clean interfaces. Their posture is “prove it,” and their lingering doubt is usually about authorship. They suspect only human engineers can reliably meet that bar.

The Dismisser opts out early. Sometimes that’s reflexive, sometimes it’s reasoned: they’ve seen bad suggestions, security risks, legal uncertainty, vendor lock-in, or unreviewable diffs and they decided the trade is not worth it. Their posture is still “already decided,” but the why matters. You don’t convert a Dismisser by arguing about models or demos. You convert them by giving them control of the bar: let them define the quality gates, then run a small, measured experiment in their own codebase that either meets the bar or fails honestly.

The Viber loves speed. They ship fast, accept large diffs, and skip the guardrails that make code testable and observable. Their posture is “speed is truth.” To be fair, that posture has a place: spikes, prototypes, throwaway demos, learning a new stack. The problem is when the same vibe crosses the border into production. That’s where “it seems to work” quietly becomes regressions, mystery failures, and eroded trust. The point of Discipline First is not to shame exploration. It’s to prevent avoidable damage when the stakes are real.

The Disciplined Builder loves AI-assisted coding and still engineers hard. Small tasks, small diffs, acceptance criteria, tests, verification loops, rules files, and a security mindset. They do not care whether the code was written by a human or an agent. They care that it is explainable, reviewable, testable, and observable. Their posture is simple: trust is built.

The only difference between the Skeptic and the Builder is what they believe about that last mile. The Skeptic thinks only humans can deliver it consistently. The Builder has learned how to make the agent earn it.

Discipline First is XP with a faster pair

Discipline First is not a new religion. It is Extreme Programming adapted to a world where your pair can write code at absurd speed. Extreme Programming starts with Values, because Values guide Principles, and Principles are what make Practices hold up under pressure.

The Values are Communication, Simplicity, Feedback, Courage, and Respect.

Communication becomes explicit intent: the Agent Brief and rules files are how you communicate without mind reading. Simplicity becomes a principle you enforce: assume simplicity, slice work into small tasks, keep diffs small, keep releases small. Feedback becomes rapid and objective: failing tests and continuous integration tell the truth early. Courage becomes disciplined restraint: stop the agent when it starts guessing, delete generated code when it bloats, and ship in increments so reality can correct you fast. Respect becomes engineering for humans: keep standards non negotiable, make changes transparent, and leave behind code that future people can understand, test, observe, and safely change.

From those Values and Principles, the Practices follow naturally: pair programming with the agent as the pair and the human as the driver, test driven development as the spec the agent must satisfy, continuous integration as the always on referee, and small releases as the safest way to turn speed into reliability.

The Discipline First kit

1) The Agent Brief

Think of the Agent Brief as a PRD that’s small enough to fit in your head, but sharp enough that the agent can’t “creatively interpret” it.

1. Goal
2. Non-goals
3. Constraints
4. Interfaces
5. Acceptance criteria
6. Risks
7. Test plan
8. Observability
9. Dependencies
10. Recovery and blast radius

Here’s a concrete example (for one service):

Goal: Add rate limiting to POST /payments to reduce abuse and protect downstream dependencies.
Non-goals: No UI changes. No new auth scheme. No changes to other endpoints.
Constraints: Must not change the public API contract. Must keep p95 latency impact under 5%.
Interfaces: POST /payments only; configuration via env var PAYMENTS_RATE_LIMIT_RPS.
Acceptance criteria: Requests above limit return 429 with standard error body; limits are per-customer; logs include rate-limit decision.
Risks: False positives blocking legit traffic; misconfigured limits; uneven behavior across instances.
Test plan: Add functional tests for 200, 429, and boundary conditions; include concurrency test; all tests deterministic in CI.
Observability: Emit metric payments.rate_limited.count; structured log rate_limit_decision with customer id hash; dashboard alert on spikes.
Dependencies: Redis (or in-memory) limiter library already approved; no new infrastructure.
Recovery and blast radius: Feature flag the limiter; default off; rollback is flag flip; document emergency disable procedure.

Then three hard rules.

1. Do not change public APIs unless explicitly permitted.
2. Prefer the smallest diff that can satisfy the brief.
3. Stop and ask when uncertain.

2) Guardrails

Not vibes. Guardrails.

Unit tests and functional tests. Contract checks. Architecture checks. Code review. Small tasks. CI as referee.

If an agent can ship code faster than a human, your only sane response is to make the truth show up faster than the code. We have already seen public “trust cliff” moments when autonomy meets weak guardrails.¹²

Small diffs are not about being precious. They are about control. A small change is easier to review, easier to reason about, easier to test, and easier to roll back. Agents tend to expand scope unless you constrain them, so “small diffs” is both a safety boundary and a way to keep context from exploding.

3) Durable instructions

Modern agentic tooling is quietly reinventing the same old idea: durable project instructions.

Rules files in agentic IDEs make behavior persistent across prompts.³
Repo-level instruction files like AGENTS.md make “how to behave here” predictable.⁴⁵
For conventions that should survive editors and IDEs, EditorConfig gives you portable, version controlled style rules.⁶⁷⁸

Practical rule of thumb:

Use EditorConfig for formatting and style that must survive editors and IDEs.
Use Rules files for tool-specific behavior. What to include in context, how to respond, what not to touch.
Use AGENTS.md for repo-wide agent behavior. Setup commands, test commands, conventions, safety boundaries.

If you only do one thing, do AGENTS.md plus your Agent Brief template. That creates a stable baseline even when prompts change.

A one-week experiment (tests only)

Pick one service. Pick one real user workflow in that service. Then write missing functional tests until the behavior is pinned down.

You will know it’s working when:

The tests fail for the wrong behavior and pass for the right behavior.
They run repeatedly without flakes.
They do not depend on environment quirks or real external systems.
CI stays green and the suite stays fast enough to run often.
Any production code change made only for testability is small and justified.
A human reviewer can read the tests as a spec and agree they capture real behavior.

Measure the boring things: how many rewrites the agent needed, how many times you had to restate intent, how large the diffs got, how much review effort it took, and how quickly you got to “tests green.”

When Discipline First is overkill (and when it breaks)

Discipline First is the safest on ramp for production work. It is not mandatory ceremony for everything.

It is overkill for throwaway prototypes, exploratory spikes, and one-off scripts where the cost of failure is low and the code has no future. In those contexts, “vibes first” can be a valid way to learn quickly.

Discipline First breaks down in predictable ways:

The Brief rots. Intent changes but the kit does not.
Tests become performative. They pass but don’t pin behavior.
Guardrails turn into friction without signal. Slow, flaky, or mis-scoped checks.
The agent is allowed to widen scope. Diffs balloon, review becomes theater.

The fix is the same as always: tighten the slice, keep the checks honest, and scale the process to the risk.

Why measure at all

Because productivity gains are not guaranteed.

One of the clearest public data points so far is a randomized controlled trial from METR (published July 2025) studying experienced open source developers working in codebases they already knew. When AI tools were allowed, developers expected big speedups and later felt faster, but measured completion time was slower on average in that setting.⁹¹⁰¹¹

That result does not mean “AI slows everyone down.” Tools and workflows change fast, task types vary wildly, and many teams report real gains. It means your intuition is not an instrument. Discipline First is not “trust the agent.” It’s “instrument the work.”

Close the loop for each persona

For the Skeptic: run one Discipline First experiment on tests only in a sandboxed branch.

For the Dismisser: pick one internal task, define your own quality gates, and let the experiment decide.

For the Viber: no big diffs, and every change must come with a failing test first.¹²

For the Builder: make discipline the default - publish the Agent Brief template, standardize rules files, and optimize the workflow so the safest path is the easiest path.

Sources and Footnotes

Floating point math is fast, useful, and occasionally haunted. Not philosophically, literally haunted, as in values that aren’t equal to themselves.

NaN != NaN evaluates to true

IEEE 754 formalizes that haunting by defining special values that let computations continue while still signaling trouble. They look like broken math until you realize they’re doing damage control.

Why Special Values Exist in Floating Point

In Part 1 of this series¹, we saw how floating-point numbers work: they use a fixed number of bits to represent the sign, exponent, and significand (mantissa). This representation has limits:

• Largest representable number: Around 1.8 × 10^308 for doubles (Double.MAX_VALUE)
• Smallest positive normalized number: Around 2.2 × 10^-308 (Double.MIN_NORMAL)
• Smallest positive nonzero number: Around 4.9 × 10^-324 (Double.MIN_VALUE)
• Precision: Limited by machine epsilon (about 2.22 × 10^-16 near 1.0, i.e., Math.ulp(1.0) = the gap between 1.0 and the next larger representable double)

But what happens when you compute something that exceeds these limits?

double huge = 1e308;
double overflow = huge * 10;            // Exceeds max value
double gradual = Double.MIN_NORMAL / 2; // Becomes subnormal (gradual underflow)
double underflow = Double.MIN_VALUE / 2; // Falls below min value → +0.0
double undefined = 0.0 / 0.0;           // Mathematically meaningless

IEEE 754 could have made these operations:

1. Throw exceptions (slow, interrupts computation)
2. Wrap around to negative values (confusing, hides errors)
3. Return arbitrary garbage (dangerous)

Instead, it reserves special bit patterns in the exponent field to represent infinity and NaN. These aren’t normal numbers; they are sentinel values that signal “something unusual happened, but computation can continue.”

The Bit Pattern Trick

A double uses 11 bits for the exponent. IEEE 754 reserves special patterns for edge cases:

This means you can check for special values with simple bit operations - no exceptions, no branching overhead in critical inner loops. In Java you normally just use Double.isNaN(x) and Double.isInfinite(x), which are implemented efficiently under the hood.

The Problem: What Should Math Return When It Breaks?

Now that we understand why special values exist (to handle edge cases without crashing), let’s see when they appear.

Consider calculating the average price change across a portfolio:

double totalChange = 0.0;
int validStocks = 0;

for (Stock stock : portfolio) {
    double change = stock.getCurrentPrice() - stock.getPreviousPrice();
    if (isValidChange(change)) {
        totalChange += change;
        validStocks++;
    }
}

double avgChange = totalChange / validStocks; // What if validStocks is 0?

If no stocks had valid data, you’re dividing 0.0 / 0. Should your program:

• Crash immediately?
• Return 0.0 and pretend the average is zero (which is a lie)?
• Return something that screams “this value is meaningless”?

IEEE 754 chose option three. It invented special values so errors can propagate visibly instead of silently corrupting results downstream.

IEEE 754 Special Values

IEEE 754 defines a few “not-a-normal-number” values so computations can keep going in a principled way instead of crashing or silently inventing garbage.

1. Signed Zero: ±0.0

Before we dive into infinity, there’s a subtle detail: IEEE 754 has both +0.0 and -0.0. They both print as 0.0 and compare as equal, but they behave differently in division:

double posZero = 0.0;
double negZero = -0.0;

System.out.println(posZero == negZero);  // true
System.out.println(1.0 / posZero);       // Infinity
System.out.println(1.0 / negZero);       // -Infinity

Signed zero exists so that 1.0 / (tiny positive number → 0) gives +∞ while 1.0 / (tiny negative number → 0) gives −∞. It preserves the direction you approached zero from, which matters for continuity and limit-style reasoning (aka Calculus).

2. Infinity: +∞ and −∞

Infinity appears when a finite result cannot be represented, or when you divide a nonzero number by zero.

double posInf = 1.0 / 0.0;   // +Infinity
double negInf = -1.0 / 0.0;  // -Infinity

System.out.println(posInf);                  // Infinity
System.out.println(negInf);                  // -Infinity
System.out.println(Double.isInfinite(posInf)); // true

Infinity participates in ordering as you’d expect:

• +∞ is greater than every finite number
• −∞ is smaller than every finite number

Arithmetic is mostly “limit-like”:

• finite + (+∞) = +∞
• positive × (+∞) = +∞
• negative × (+∞) = −∞

But some combinations are undefined and produce NaN:

• (+∞) + (−∞) = NaN
• (+∞) × 0.0 = NaN
• (+∞) / (+∞) = NaN

3. NaN: Not a Number

NaN means “this result is undefined,” like 0.0 / 0.0 or √(−1). Once NaN enters a computation, it spreads into any operation involving NaN to produce a NaN:

double nan = 0.0 / 0.0;

System.out.println(nan);           // NaN
System.out.println(nan + 5);       // NaN
System.out.println(nan * 2);       // NaN
System.out.println(Math.sqrt(nan)); // NaN

This “contagious” behavior is intentional. If a value is undefined, any result built on it should also be undefined.

The Weird Rule: NaN ≠ NaN

The key rule that feels like a logic prank but is actually a safety feature:

NaN is not equal to anything, including itself.

double nan = Double.NaN;

System.out.println(nan == nan);        // false (!)
System.out.println(nan != nan);        // true
System.out.println(nan < 5.0);         // false
System.out.println(nan >= 5.0);        // false
System.out.println(Double.isNaN(nan)); // true (correct way)

Why? Because NaN means “undefined result,” and you can’t meaningfully compare undefined values. NaN is unordered by design. There can be many NaN bit patterns (IEEE 754 supports “signaling” and “quiet” NaNs with different payloads), but Java generally treats them as “some NaN” unless you inspect raw bits with Double.doubleToRawLongBits().

Think of it like asking whether two error messages are “the same error.” Even if both say “Error,” you don’t know if they represent the same underlying problem. The comparison itself is meaningless.

Never check for NaN with ==. Use Double.isNaN(x) instead.

NaN and Sorting: Two Different Worlds

This is where things get interesting. Java has two ways to compare doubles, and they behave differently with NaN:

IEEE 754 comparisons (==, <, <=, etc.):

• Any comparison with NaN returns false
• These are what you use in if statements

Java’s total order (Double.compare(), Double.compareTo())²:

• NaN is considered greater than all other values, including +∞
• All NaNs are considered equal
• This is what Arrays.sort() and Arrays.binarySearch() use

double[] values = {3.0, Double.NaN, 1.0, 2.0};
Arrays.sort(values);
System.out.println(Arrays.toString(values)); 
// [1.0, 2.0, 3.0, NaN] -- guaranteed by Java spec

// IEEE comparison says "not sorted":
System.out.println(values[2] <= values[3]); // false (3.0 <= NaN is false)

// Total order says "sorted":
System.out.println(Double.compare(values[2], values[3]) <= 0); // true

The gotcha: If you validate sortedness using <=, you’ll get false negatives when NaN is present. If you need to check ordering, use Double.compare(a, b) <= 0 instead.

IEEE comparisons answer “is this mathematically ordered?” while Java’s total order answers “can we put these in a consistent sequence for sorting?” The Arrays Javadoc basically says exactly that: < is not a total order for doubles, so sorting uses the total order from Double.compareTo.

The good news: Arrays.sort() and Arrays.binarySearch() work correctly with NaN because they use the total order internally. The NaN will consistently end up at the end of the array.

Quick Reference: Comparison Table

Practical Takeaways

1. Never check NaN with ==. Use Double.isNaN(x).
2. Log early for special values when debugging “impossible” totals:

   if (Double.isNaN(result)) {
       log.error("NaN detected at step X");
   }
   if (Double.isInfinite(result)) {
       log.error("Infinity detected at step X");
   }
   

1. Use the right comparison for the job: == for value equality, Double.compare() for ordering.
2. Understand the contagion: Once NaN enters your calculations, it spreads. Trace backward to find the division by zero or invalid operation that spawned it.

The Philosophical Bit

NaN isn’t a bug. It is math raising its hand and saying, politely but firmly:

“I can’t promise anything from here.”

When your balance sheet shows NaN, don’t curse floating point. Ask what division by zero or invalid square root you missed three steps ago. The special values aren’t betraying you; they’re the only honest answer to questions that have no answer.

In the next post, we’ll look at how to actually handle these special cases in production code without littering your logic with endless isNaN() checks.

References and Notes

In my post on associativity and reduce¹, we saw something that feels like a prank. In Example 5, adding 1.0 to 1e16 did not change the value at all.

double x = 1e16;
System.out.println(x + 1.0 == x); // true

That is not Java being cheeky. That is IEEE-754 being literal. A double does not live on a continuous number line. It lives on a grid.

This post answers one question:

How fine is the grid?

Machine epsilon and the first rung above 1.0

One common definition of machine epsilon (ε) is:

The smallest ε > 0 such that 1.0 + ε ≠ 1.0 for double.

This is “the gap from 1.0 to the next representable double above it”.

Note: Some references use ε to mean 2⁻⁵³, which is half this gap and represents the maximum relative rounding error for a correctly rounded operation. In this post, ε means the “next representable number above 1.0” definition, which is 2⁻⁵².

Finding ε in Java

Here is a loop that finds that smallest nudge.

public class MachineEpsilon {
  public static void main(String[] args) {
    double eps = 1.0;

    while (1.0 + (eps / 2.0) != 1.0) {
      eps /= 2.0;
    }

    System.out.println("epsilon = " + eps);
  }
}

Typical output on an IEEE-754 JVM:

epsilon = 2.220446049250313E-16

That value is exactly 2⁻⁵². Since powers of two are exactly representable in binary floating point, there is no approximation error in storing this value. The decimal string 2.220446049250313E-16 is just how Java renders that exact binary value for display, rounded to about 15 decimal digits.²

One quick trap: Double.MIN_VALUE is not machine epsilon. Double.MIN_VALUE is the smallest positive double near zero (about 5×10⁻³²⁴). Machine epsilon is about spacing near 1.0.

The ladder model

Picture a ladder laid across the number line.

Near 1.0, the rungs are extremely close together. As the numbers get bigger, the rungs spread out.

Machine epsilon tells you the rung spacing near 1.0. But what you usually want is the spacing near whatever value you are actually using.

That spacing is called ULP, short for Unit in the Last Place.

Java gives it to you with Math.ulp(x).

How spacing grows with magnitude

Let’s sample the grid at a few scales.

public class UlpSpacing {
  public static void main(String[] args) {
    double[] xs = {1.0, 10.0, 1e8, 1e16};

    for (double x : xs) {
      System.out.printf("x=%-8s  ulp(x)=%s%n", x, Math.ulp(x));
    }
  }
}

Typical output:

x=1.0      ulp(x)=2.220446049250313E-16
x=10.0     ulp(x)=1.7763568394002505E-15
x=1.0E8    ulp(x)=1.4901161193847656E-8
x=1.0E16   ulp(x)=2.0

That last line is the whole “Example 5” mystery solved:

Around 1e16, the grid spacing is 2.0.

So 1e16 + 1.0 lands between rungs and rounds back to 1e16. But 1e16 + 2.0 is exactly one rung up.

double big = 1e16;
System.out.println(big + 1.0 == big); // true
System.out.println(big + 2.0 == big); // false

Powers of two: where spacing jumps

ULP does not grow smoothly. It jumps at powers of two.

Right below 2ᵏ, spacing is one value. At 2ᵏ, spacing doubles.

That is why comparisons that seem symmetric can behave oddly if two values straddle a power-of-two boundary. If you’re comparing values near different powers of two, their ULPs can differ by a factor of 2.

Near zero: subnormals exist and they are weird

For very small magnitudes below Double.MIN_NORMAL (approximately 2.225×10⁻³⁰⁸), double switches to subnormal (also called denormal) representation.

What changes in subnormal land:

Normal doubles have an implicit leading 1. in the mantissa:

• value = (1.fraction) × 2^exponent
• This gives you full precision

Subnormals drop that leading 1.:

• value = (0.fraction) × 2^(minExponent)
• You lose precision gradually as you approach zero

Why they exist:

Without subnormals, there would be a hard cliff from tiny normal numbers straight to 0.0. Subnormals provide gradual underflow - a ramp instead of a cliff.

Key differences:

• Spacing becomes constant at approximately 5×10⁻³²⁴ (the value of Double.MIN_VALUE) rather than scaling with magnitude
• Arithmetic can be slower on some CPUs
• Relative precision is much worse (you may have only a few significant bits left)

Everything in the range (0, Double.MIN_NORMAL) is subnormal. That’s the range from about 4.9×10⁻³²⁴ up to about 2.225×10⁻³⁰⁸.

Most business code never goes near subnormals. Numerical code sometimes does. It is worth knowing that floating-point has an emergency mode near zero that trades precision for continuity.

Why tiny increments vanish when numbers get big

When your running total grows large enough, the local rung spacing can become bigger than the increments you are adding.

So “add a million tiny things to a huge sum” eventually turns into “add nothing, repeatedly,” because the tiny things fall between rungs and get rounded away.

That is not philosophical. It is mechanical.

Why equality checks on doubles are dicey

Sometimes two values that “should be different” land on the same rung. Sometimes two values that “should be equal” get rounded at different times and land on adjacent rungs.

So == is only safe when you mean exact equality:

• Comparing to exact literals: 0.0, 1.0, -1.0
• Checking for special values: infinities, or Double.isNaN(x)
• Comparing sentinel values or results from identical deterministic operations
• Loop counters stored as doubles (though you should use integers instead)

When you need “close enough,” you need a rule that matches your domain.

A common practical pattern is absolute tolerance near zero plus relative tolerance for scale.

public final class DoubleCompare {
  private DoubleCompare() {} // prevent instantiation

  /**
   * Check if two doubles are nearly equal using absolute and relative tolerance.
   * 
   * @param a first value
   * @param b second value
   * @param absTol absolute tolerance (try 1e-9 for many applications)
   * @param relTol relative tolerance (try 1e-9 for many applications)
   * @return true if values are within tolerance
   */
  public static boolean nearlyEqual(double a, double b, double absTol, double relTol) {
    if (Double.isNaN(a) || Double.isNaN(b)) return false;
    if (a == b) return true; // handles infinities and exact matches

    double diff = Math.abs(a - b);
    if (diff <= absTol) return true;

    double maxAbs = Math.max(Math.abs(a), Math.abs(b));
    return diff <= relTol * maxAbs;
  }
}

Choosing tolerance values:

• absTol should match the minimum meaningful difference in your domain. For scientific data measured to 3 decimal places, maybe 1e-3. For pixel coordinates, maybe 0.5.
• relTol is typically something like 1e-9 (about 9 decimal digits of agreement) for general use, or 1e-6 if you’re being more lenient.
• These comparisons are slower than ==. If you’re comparing millions of values in performance-critical code, measure the cost.

This is not the only strategy, but it is harder to misuse than an “ULPs everywhere” helper.

Why parallel reductions can drift

Parallel reductions regroup operations. Floating-point addition is not associative, so regrouping changes when rounding happens.

Here is the smallest “this is why” example.

double a = 1e16;

double left  = (a + 1.0) + 1.0;   // first +1 vanishes, then second +1 vanishes
double right = a + (1.0 + 1.0);   // (1.0 + 1.0) becomes 2.0, which moves one ULP

System.out.println(left == right); // false
System.out.println(left);          // 1.0E16
System.out.println(right);         // 1.0000000000000002E16

Same values, different grouping, different result. That is the reason parallel sums can drift when the data has large magnitudes or mixed scales.

The takeaway

A double gives you roughly the same number of significant bits everywhere (about 15-16 decimal digits), not the same absolute resolution everywhere.³

Machine epsilon tells you the first rung above 1.0.

Math.ulp(x) tells you the rung spacing where you are standing.

And that is why, at 1e16, adding 1.0 is like whispering into a hurricane.

References

In my earlier post on IEEE 754 doubles I showed how a tiny Java example could break your intuition about numbers. The JVM was not being sloppy. It was faithfully following the floating point rules. The surprise came from my mental model, not from the hardware.

BigDecimal is Java’s answer to a different problem: what if I actually need decimal correctness, not fast binary approximation? It is the type you reach for when cents matter, reconciliation matters, or auditors matter.

It is less magical than it looks.

TL;DR: Use new BigDecimal("0.1") for decimal values in your code. Only use BigDecimal.valueOf(double) when you’re already stuck with a double from external sources.

Quick Reference

Before we dive in, here’s what you need to remember:

  
// ✓ Correct ways to create BigDecimal for money  
new BigDecimal("0.1");                   // String literal  
new BigDecimal("123.45");                // String literal  
BigDecimal.valueOf(10).movePointLeft(1); // 10 × 10^-1 = 1.0  

// ✗ Wrong for hardcoded decimal values  
new BigDecimal(0.1);        // Exposes the binary approximation as decimal

Doubles speak binary, your domain speaks decimal

double is brilliant for physics, graphics, simulations, and anything where small error is acceptable. It is terrible at representing human money. The root cause is simple. Doubles are binary fractions. Money is decimal.

0.1 rupee or dollar has no exact representation in binary floating point. When you write:

double x = 0.1;
System.out.println(x);              // prints 0.1 (canonical string)
System.out.printf("%.20f%n", x);    // 0.10000000000000000555...

you are already off by a tiny amount, even though the default printout shows 0.1. Most of the time you are happy to ignore that tiny tail (technically binary approximation). But then you sum millions of rows, or reorder operations, or start comparing for equality, and the tail starts wagging the dog.

BigDecimal cuts across this by working in base 10.

BigDecimal’s mental model

Conceptually, a BigDecimal is two things glued together:

1. An integer representing all the digits, without any decimal point.
2. A scale that says where the decimal point lives.

Formally:

value = unscaledValue × 10^(-scale)

So:

BigDecimal amount = new BigDecimal("123.45");

internally becomes:

• unscaledValue = 12345
• scale = 2
• logical value = 12345 × 10^-2 = 123.45

Because the unscaled integer is exact, decimal values like 0.1, 0.01, 1234567890.12 are also exact. There is no “closest representable value” the way there is with double. You only lose information when you explicitly ask BigDecimal to round (via MathContext or setScale).

How the JDK actually stores it

That is the spec view. Under the hood in OpenJDK, the class looks roughly like this:

public class BigDecimal extends Number
        implements Comparable<BigDecimal> {

    // Compact form when it fits in a long
    private transient long intCompact;

    // Full form when it doesn't
    private BigInteger intVal;

    // Digits after the decimal point
    private int scale;

    // Cached number of significant digits
    private transient int precision;

    // Marker for "no compact long, use intVal instead"
    static final long INFLATED = Long.MIN_VALUE;
}

So BigDecimal actually has two representations for the unscaled value:

• Compact mode: if the unscaled integer fits in a 64-bit long, it lives in intCompact and intVal is null. This is the fast path for “small enough” numbers.
• Inflated mode: if it does not fit, intCompact is set to INFLATED and the digits live in intVal as a BigInteger.

This optimization means small monetary amounts stay fast, while supporting arbitrarily large values when needed.

Your 123.45 example fits happily in compact form:

• intCompact = 12345L
• intVal = null
• scale = 2

Never construct BigDecimal from a double

A classic foot-gun looks like this:

BigDecimal a = new BigDecimal(0.1);
BigDecimal b = new BigDecimal("0.1");

System.out.println(a); // 0.1000000000000000055511151231257827021181583404541015625
System.out.println(b); // 0.1

The first line takes the binary double for 0.1 and converts it directly into an exact decimal. The double is already an approximation, so you get the full fraction printed out.

The second line parses the string "0.1" as a decimal value. There is no binary detour, so you get exactly one tenth.

You have not “fixed” the double by wrapping it in a BigDecimal. You have just made its approximation painfully visible.

What about BigDecimal.valueOf() and canonical strings?

This is where people get confused:

BigDecimal a = new BigDecimal(0.1);
BigDecimal b = BigDecimal.valueOf(0.1);

System.out.println(a);
// 0.1000000000000000055511151231257827021181583404541015625

System.out.println(b);
// 0.1

Same literal 0.1, two different worlds.

The difference is that valueOf goes through the canonical decimal string of the double.

Route 1: new BigDecimal(0.1)

This constructor works directly from the binary bits of the double:

• The double for 0.1 is not exactly one tenth.
• It is some messy binary fraction very close to 0.1.
• new BigDecimal(double) asks: “What is the exact decimal value of this binary fraction?”

So you see the full binary approximation:

0.1000000000000000055511151231257827021181583404541015625

Ugly, but honest.

Route 2: BigDecimal.valueOf(0.1) and canonical decimal strings

valueOf takes a different path:

public static BigDecimal valueOf(double val) {
    return new BigDecimal(Double.toString(val));
}

The key piece here is Double.toString(val). That method does not dump all the internal bits. Instead, it produces the canonical decimal string for that double:

The shortest decimal string that, if you parse it back with Double.parseDouble, gives you exactly the same double bits.

In code, it guarantees:

double x = ...;
String s = Double.toString(x);
double y = Double.parseDouble(s);

assert Double.doubleToLongBits(x) == Double.doubleToLongBits(y);

For the double that represents 0.1, that canonical string happens to be:

Double.toString(0.1); // "0.1"

So the pipeline for BigDecimal.valueOf(0.1) is:

1. Start from the binary double for 0.1.
2. Turn it into its canonical decimal string "0.1" – a decimal string with just enough digits to round back to the same double (i.e., to distinguish it from adjacent doubles).
3. Feed that string into new BigDecimal("0.1").

Result: an exact decimal 0.1, not the giant tail.

So you can summarise it like this:

• new BigDecimal(0.1) = “give me the exact decimal value of this weird binary fraction”.
• BigDecimal.valueOf(0.1) = “give me the exact decimal value of the canonical string \"0.1\" for this double”.

The rounding error happened earlier, when you chose a double to represent 0.1 at all. valueOf doesn’t fix that choice, but it gives you a clean, canonical decimal view of that double instead of the raw fraction.

When to use valueOf()

valueOf is useful, and often preferred, in three situations:

// Fine for integers
BigDecimal cents = BigDecimal.valueOf(12345); // 12345

// When you're stuck with a double from legacy code
double legacyPrice = thirdPartyApi.getPrice();   // You can't control this
BigDecimal price = BigDecimal.valueOf(legacyPrice)
    .setScale(2, RoundingMode.HALF_UP);          // Accept the loss, make it explicit

// When building decimal values programmatically from integers
BigDecimal tenth = BigDecimal.valueOf(1).movePointLeft(1);  // Start from exact integer 1

But for hardcoded monetary values in your own code, skip doubles entirely and use string literals:

BigDecimal price = new BigDecimal("0.10");

The real rule is about where the value originates:

• If the value is born in your domain as a decimal (prices, rates, balances), create it from a decimal representation (String, long + scale).
• If the value is already stuck in a double, use BigDecimal.valueOf(double) and treat that conversion as a boundary where precision may already have been lost.

BigDecimal will not magically repair a bad choice of primitive type.

Quick comparison

Exact sums, predictable cents

Here’s a comparison showing why BigDecimal matters for financial code:

// With doubles - unpredictable
List<Double> doubleAmounts = List.of(
    10000000000000000.00,
    1.00, 1.00, 1.00, 1.00
);
double doubleSum = doubleAmounts.stream()
    .mapToDouble(Double::doubleValue).sum();
System.out.println(doubleSum); // 1.0000000000000004E16

The result is mathematically correct (10^16 + 4), but the representation shows how rounding noise creeps in when you mix huge and small magnitudes in binary floating point. At this scale, many consecutive integers are not exactly representable as double, so tiny adjustments end up living in the low bits and surfacing as …0004E16.

Now compare with BigDecimal:

// With BigDecimal - exact
List<BigDecimal> amounts = List.of(
    new BigDecimal("10000000000000000.00"),
    new BigDecimal("1.00"),
    new BigDecimal("1.00"),
    new BigDecimal("1.00"),
    new BigDecimal("1.00")
);
BigDecimal sum = amounts.stream()
    .reduce(BigDecimal.ZERO, BigDecimal::add);
System.out.println(sum); // 10000000000000004.00

No matter how you reorder the BigDecimal list, you will get the same 10000000000000004.00. There is no hidden rounding based on magnitude, because the arithmetic is done on the unscaled integers.

You pay for this determinism. BigDecimal operations are typically 10-100× slower than double, depending on the values involved. But when you reconcile two systems and everything lines up to the last cent, you know where the extra CPU cycles went.

Scale, rounding, and the joy of being explicit

With doubles, rounding is automatic and mostly invisible. With BigDecimal, rounding is very much your problem.

Imagine you need to divide 1 rupee into 3 equal parts:

BigDecimal one = new BigDecimal("1.00");
BigDecimal three = new BigDecimal("3.00");

BigDecimal each = one.divide(three); // Kaboom: ArithmeticException

The exception is deliberate. 1 / 3 in decimal form is 0.3333… forever. BigDecimal refuses to guess how many digits you want. You must say how you want the result rounded.

There are two approaches, and knowing when to use which matters.

MathContext: For intermediate calculations

Use MathContext when you need to control significant digits during computation:

// Calculate pi as 22/7 with 10 significant digits
MathContext mc = new MathContext(10, RoundingMode.HALF_UP);
BigDecimal pi = new BigDecimal("22").divide(
    new BigDecimal("7"), 
    mc
);
System.out.println(pi); // 3.142857143

setScale: For final results

Use setScale when you need to control decimal places for presentation or storage:

// Round a calculated price to 2 decimal places for currency
BigDecimal rawPrice = new BigDecimal("12.3456");
BigDecimal price = rawPrice.setScale(2, RoundingMode.HALF_UP);
System.out.println(price); // 12.35

The pattern that works

For currency, a clean approach is:

1. Decide how many decimal places your business uses (usually 2 for most currencies)
2. Store all monetary values with that scale
3. When you need intermediate higher precision, use a MathContext locally
4. Bring the value back to your standard scale at the boundaries

BigDecimal rate = new BigDecimal("0.0525"); // 5.25% interest rate
BigDecimal principal = new BigDecimal("1000.00");

// Higher precision for calculation
MathContext mc = new MathContext(10, RoundingMode.HALF_UP);
BigDecimal interest = principal.multiply(rate, mc);

// Round to cents for storage
interest = interest.setScale(2, RoundingMode.HALF_UP);
System.out.println(interest); // 52.50

Equals is not the same as compareTo

There is a subtle trap buried in BigDecimal’s API:

BigDecimal x = new BigDecimal("1.0");
BigDecimal y = new BigDecimal("1.00");

System.out.println(x.equals(y));    // false
System.out.println(x.compareTo(y)); // 0

equals cares about both value and scale. The unscaled integer is 10 vs 100, scale is 1 vs 2, so the objects are not “equal”.

compareTo cares only about numeric value. From that point of view they are both exactly one, so the comparison says zero.

If you put BigDecimal keys into a HashMap or HashSet, you are using equals. If you put them in a TreeMap or TreeSet, you are using compareTo. That difference has bitten enough people that the Javadoc has an explicit warning¹.

What to do about it

For financial applications, you typically want value-based comparison:

// Use compareTo for all business logic
if (price.compareTo(threshold) > 0) {
    applyDiscount();
}

// Or normalize scale before storing in collections
BigDecimal normalized = value.setScale(2, RoundingMode.UNNECESSARY);
priceSet.add(normalized);

Common mistakes

Beyond the double constructor trap, watch out for these.

Using == for comparison

// Wrong
if (price == threshold) { ... }

// Right
if (price.compareTo(threshold) == 0) { ... }

Forgetting rounding mode

// Throws ArithmeticException
BigDecimal result = amount.divide(three);

// Specify your intent
BigDecimal result = amount.divide(three, 2, RoundingMode.HALF_UP);

Mixing scales carelessly

BigDecimal a = new BigDecimal("1.0");   // scale 1
BigDecimal b = new BigDecimal("2.00");  // scale 2
BigDecimal sum = a.add(b);              // scale 2 (max of the two)

// Result may have unexpected scale; normalize when it matters
// Note: UNNECESSARY throws ArithmeticException if rounding would be needed
sum = sum.setScale(2, RoundingMode.UNNECESSARY);

When should you actually use BigDecimal?

BigDecimal is not a “better double”. It is a different tool.

Reach for BigDecimal when:

• You are working with money, interest rates, exchange rates, or anything that must reconcile to the cent or paise
• You are implementing rules that are written in decimal terms by humans and regulators, not in binary terms by hardware engineers
• You care more about correctness and determinism than raw speed

Stay with doubles when:

• You are doing heavy numeric computing, simulations, statistics, graphics, or ML workloads where small rounding error is acceptable and performance dominates
• You are counting in powers of two, not powers of ten
• The measurements themselves are imprecise (sensor readings, physical measurements)

You can always convert between the two worlds at clearly defined boundaries.

Closing thought

BigDecimal is not slow magic. It is a disciplined refusal to lie about decimals.

Doubles take a binary view of the universe and do their best to approximate your decimal stories. BigDecimal takes your decimal stories literally and forces you to be explicit about where information is lost.

Neither is the “right” choice in isolation. The trick is to know which world you are in.

References

The Security Council was designed in a specific world. The year was 1945. The problem statement was simple and terrifying: prevent another world war. The veto was not invented as a moral idea. It was a stability mechanism. If the strongest powers of that era were expected to participate in a system, they needed assurance that the system would not be used against what they consider existential interests. You may dislike that logic, but you cannot pretend it is irrational. It is the kind of logic that keeps institutions alive.

Still, a system can be historically justified and yet feel increasingly mismatched to the world it is supposed to manage. When that mismatch grows, two things happen.

First, decisions start looking less legitimate to those who are asked to accept them.

Second, countries start routing around the institution when it feels slow, unpredictable, or politically costly.

Both outcomes are bad. Legitimacy without power becomes poetry. Power without legitimacy becomes noise. The world needs less noise.

So the best way to talk about Security Council reform is not as a fight between “the powerful” and “the rest.” The best way is to ask a practical question.

How do we keep the Council authoritative enough that major powers remain invested in it, while making it representative enough that the wider world respects it?

That question matters because reform that ignores incentives will not produce a better Security Council. It will produce an ignored Security Council. And an ignored Security Council is not a victory for democracy. It is a victory for chaos.

So my goal here is not to write a fantasy about “abolishing the veto.” Charter change is hard, and the Charter is designed to be hard to change. The goal is more modest and more practical.

Make obstruction more accountable, more legible, and harder to perform casually, without pretending we can enforce good faith.

I will do three things for each proposal.

1. Describe what happens today.
2. Define a concrete additional process.
3. Explain why it helps, including where it can still fail.

1. Make veto use more accountable, not weaker

What happens today

A substantive Council decision needs at least nine affirmative votes and no negative vote from any permanent member. One negative vote by a permanent member blocks the draft. That is the veto. (UN Charter, Article 27)¹

After the veto, accountability is mostly reputational.

Yes, the veto is public. Voting records exist. Explanations may be offered in the chamber. But the content is unstructured and often optimized for politics, not clarity.

Since 2022, there is also a formal spotlight mechanism. When a veto is cast, the General Assembly President must convene a debate within ten working days. The Assembly “invites” the Council to submit a special report on the veto at least 72 hours before the debate. (UNGA resolution 76/262)² The important word there is “invites.” It raises political cost, but it does not force precision, and it does not force participation. Analysts have noted that the resolution does not impose obligations on the vetoing state to even show up.³

What I propose

A veto should trigger a short, mandatory, structured “Veto Brief” filed as an official UN document within 48 hours.

Not an essay. A template with hard edges.

The brief must include:

1. Pinpoint objection
   Identify exactly which operative paragraphs are unacceptable.

2. Factual predicates
   List the key factual claims the veto relies on, written as testable statements.

3. Principle being invoked
   Cite Charter articles if needed, but state the real test in plain language. The Charter citation supports the argument. It cannot replace the argument.

4. Acceptable path to “yes”
   Provide at least one concrete amendment or alternative text that would remove the need for a veto.

5. Review trigger
   If the veto is conditional, state the conditions and a review date for reconsideration.

Then, within seven days, the Council schedules a short “Veto Consequences” session. Ten minutes for the vetoing member to present the brief, then a time-boxed round of questions from elected members. No moral theatre required. Just structured daylight.

Finally, add one small but sharp piece of enforcement that costs almost nothing.

If the vetoing member does not file the brief, that non-submission is recorded in the Council’s official meeting record, and it is flagged in the General Assembly debate convened under 76/262.² The veto remains valid, but the refusal becomes part of the permanent archive and part of the public debate.

To prevent a perfunctory brief that merely checks boxes, the Council President should record whether the brief is responsive to the template (i.e., it contains a concrete “path to yes” and specific factual predicates, not generic slogans). A non-responsive brief is treated like a non-submission for the purposes of the General Assembly debate, where the adequacy of the brief becomes a formal topic–members can explicitly challenge missing predicates, evasive language, or the absence of any acceptable alternative.²

Why it helps, and where it can fail

The honest criticism is correct: “What if powerful states don’t care?”

Some don’t. History is not shy about that.

But accountability is not only about changing minds. It is also about changing the friction profile of a behavior.

This mechanism raises the cost of vetoing in three ways that do not require new UN spending.

1. It shifts effort onto the actor choosing the veto.
   The UN does not hire a new bureaucracy. The vetoing mission uses its existing staff to produce a short document.

2. It removes the fog that makes performative vetoes easy.
   If you must state what you would accept, you cannot veto and disappear into slogans.

3. It makes patterns visible over time.
   A veto is a single moment. A trail of structured briefs becomes a story.

A concrete example shows the dysfunction today.

On Syria, vetoes have been repeatedly used to block action on drafts concerning the conflict and humanitarian mechanisms. Security Council Report notes that since 2011, Russia cast 19 vetoes, with 14 on Syria, and that eight of nine Chinese vetoes in that period were on Syria.⁴ The UN’s own research guide lists vetoed Syria-related drafts across multiple years.⁵

A structured veto brief would not magically unlock consensus, but it would force two things that are often missing.

First, explicit alternative text, on the record, each time.

Second, explicit factual predicates, which can be challenged publicly in the General Assembly debate already mandated after a veto.²

Failure mode still exists. A determined vetoing member can absorb reputational costs. But even then, the system gains something it currently lacks: a clear, testable record of what was blocked and what compromise was refused.

That clarity matters to history, to diplomacy, and to any future negotiation.

2. Build a norm of restraint for mass atrocities, and make the norm operational

What happens today

There is no binding rule preventing veto use in situations involving genocide, crimes against humanity, or war crimes.

There are voluntary initiatives.

The ACT Code of Conduct asks states to support timely and decisive action to prevent or end mass atrocity crimes, and calls on Council members not to vote against credible action aimed at stopping them.⁶ There is also the France–Mexico initiative calling for voluntary restraint on veto use in mass atrocity situations.⁷

These matter. But voluntary norms have a familiar weakness: they work best when they are not needed.

What I propose

Convert “restraint” from a moral appeal into a repeatable procedure.

Create a “Mass Atrocity Track” for draft resolutions explicitly aimed at preventing or halting atrocity crimes.

If a draft is placed on this track, then any veto triggers two additional obligations inside the veto brief.

1. Civilian impact claim
   A short statement explaining why the vetoing member believes the draft would worsen civilian protection outcomes, or violate a principle in a way that outweighs the harm of inaction.

2. Alternative protection path
   A concrete alternative proposal that still targets civilian protection, even if it changes the means.

Then impose one simple process requirement.

Within 14 days of a veto on the atrocity track, the Council must vote on at least one alternative draft addressing the same civilian protection objective, even if it is imperfect.

This is not “forcing agreement.” It is forcing effort.

Why it helps, and what happens if the veto still blocks action

The nightmare scenario is real.

What if this process exists and a veto still blocks action during an active genocide?

Then the Council’s impotence becomes more transparent.

That sounds grim, but transparency is not nothing. Opacity is how paralysis becomes normal.

The additional value here is that the mandated General Assembly debate after a veto (76/262) becomes better informed. Instead of debating fog, the wider membership debates a structured record that includes what alternative protection pathways were offered or not offered.²

And yes, powerful states can still ignore the norm. But a norm tied to a forced iteration loop changes behavior at the margin, and “at the margin” is often where real lives are saved.

3. Expand membership with a specific shape, and admit the trade offs

What happens today

The Council has 15 members: five permanent, ten elected for two-year terms. (UN Charter, Article 23)⁸

Those ten elected seats are distributed by regional groups: three for Africa, two for Asia Pacific, two for Latin America and the Caribbean, two for Western Europe and Others, and one for Eastern Europe.⁹

Two problems follow from this design.

First, two years is short. Many elected members become effective only when their term is ending.

Second, representation is frozen in a world that has changed.

What I propose

A concrete model that sits between “keep it at 15 forever” and “blow it up to 25 plus overnight” is this.

Expand from 15 to 21 members by adding six longer-term renewable seats, without adding new vetoes.

1. Keep the current 10 two-year elected seats and their existing regional distribution.⁹
2. Add six renewable seats with four-year terms, eligible for immediate re-election once.
   Four years is long enough to build genuine file expertise and relationships; short enough that renewal still means something.
3. Allocate those six seats by region as follows: 2 Africa
   2 Asia Pacific
   1 Latin America and the Caribbean
   1 split rotation between Eastern Europe and Small Island Developing States

This is not the only possible distribution. The point is to stop hand waving and put a shape on the table.

It also aligns with the core complaint that the current Council has no permanent representation for Africa or Latin America, a point repeatedly raised in reform debates.¹⁰

Who defines the criteria, and why would anyone accept them?

Criteria should be defined by the General Assembly through the ongoing intergovernmental negotiations process, not by the permanent members alone. The politics are difficult, but the venue is clear.¹¹

A Charter amendment is still required for composition change, and Charter amendments require ratification including by all permanent members. (UN Charter, Article 108)¹²

That is the hard wall. No serious reform should pretend it is not there.

So the real strategy is phased.

Phase 1 is working-methods reform that does not require Charter amendment. Veto briefs, structured hearings, iteration loops.

Phase 2 is composition reform, which requires a broader bargain.

Trade off: larger councils can be slower

This is a real risk. Larger groups can move slower, and more seats can add friction.

The mitigation is to keep the extra seats longer-term and renewable. Continuity reduces the constant onboarding churn that already slows the Council today.

Another mitigation is procedural discipline: time-limited negotiations, published draft histories, and structured “what would unlock agreement” fields, so debate does not become infinite.

And it is worth noting a counterweight to the “bigger means slower” argument: the Council already runs at high tempo. In 2024 it held 305 formal meetings (a record), which suggests there is procedural capacity for a modest increase in membership without fundamentally changing the Council’s operating rhythm.¹³

4. Replace “permanent forever” with “long term renewable,” as a direction the system can actually walk

What happens today

Permanence is embedded in the Charter. Removing it is not politically realistic in the near term.¹²

But “near term realism” is not the same as “long term surrender.”

What I propose

Treat renewable legitimacy as a parallel prestige track.

Build up the longer-term renewable seats described above. Make them consequential. Make them hard to win and easy to lose if a state does not sustain contribution and responsibility.

Over time, those seats become the institution’s living legitimacy mechanism.

There is precedent for this kind of design in regional security bodies. The African Union Peace and Security Council has 15 members, with five elected for three-year terms and ten for two-year terms, and it has no permanent members and no veto. It uses rotation and re-election to balance continuity with legitimacy.¹⁴

The AU PSC is not the UN, and global politics are nastier than regional politics. But the institutional idea is useful: continuity without permanence, and influence that must be renewed.

Why it helps, even if the old structure remains

Because it creates a pathway where legitimacy is something you keep earning, not something you inherit.

Even if permanence stays, renewable seats can gradually shift the Council’s center of gravity toward responsibility-based legitimacy.

5. Stakeholder buy in, and how to build a coalition that does not require miracles

This is where the earlier draft was too optimistic by omission.

The Council does not reform because someone writes a good blog post. It reforms when enough states can see a bargain.

There are already two building blocks.

First, the veto initiative (76/262) was adopted by consensus, and it has already triggered repeated debates after vetoes.² UN press reporting in November 2025 noted that multiple vetoes had triggered corresponding General Assembly debates under this mechanism.¹⁵

Second, there are existing coalitions around voluntary restraint and working methods, like the ACT group’s Code of Conduct.⁶

A practical coalition path looks like this.

1. Start with elected members and accountability-minded middle powers pushing working methods reforms, because working methods do not require Charter change.
2. Use the General Assembly debate mechanism after each veto to normalize structured records and structured questions.²
3. Build a “default expectation” that a veto without a brief is a veto without legitimacy, even if it remains legally valid.
4. Only then push composition reform, when the system has already shifted culturally toward accountability.

This does not guarantee success. It does something more valuable.

It creates a ratchet. A direction. A path that can be walked.

Closing thought

Institutional design cannot force good faith. But it can punish bad faith with friction, sunlight, and repetition.

The veto will remain a power tool. The question is whether it remains a power tool that operates in fog, or a power tool that must operate in daylight.

In fog, the Council becomes theatre. In daylight, it at least becomes a record. And sometimes, that record becomes the first step toward a better bargain.

References

You could point to a place in your program and say: “Go there.” The computer would nod, politely, and do exactly that.

And for a beginner, this felt comforting. Orderly. Almost architectural.

10 PRINT "Hello"
20 PRINT "World"
30 END

A neat little staircase of intentions.

Then we learned the spell.

The seduction of GOTO

GOTO is the programming equivalent of discovering you can teleport.

Why walk like a peasant when you can jump?

Want a loop? Jump back.

10 LET X = 0
20 LET X = X + 1
30 PRINT X
40 IF X < 5 THEN GOTO 20
50 END

It works. It’s simple. It even feels clever.

But teleportation has a cost: once you start jumping, your program stops being a story and becomes a maze.

The day BASIC stopped feeling friendly

At some point the program gets longer than your short-term memory.

You add one more rule. Then another.

Now you’re jumping forward to handle special cases, jumping back to repeat, jumping sideways to “retry,” and suddenly you’re not writing code.

You’re playing detective.

Here’s the kind of shape that starts to appear:

10 INPUT "Enter a number (1-10)"; N
20 IF N < 1 THEN GOTO 90
30 IF N > 10 THEN GOTO 90
40 PRINT "OK"
50 GOTO 110
90 PRINT "Invalid. Try again."
100 GOTO 10
110 END

This is still readable.

But scale it up a bit: ten validations, multiple modes, nested loops, an error path, a “back” option, and suddenly the logic is scattered across line numbers like breadcrumbs thrown into a hurricane.

You don’t read it anymore. You trace it.

Tracing burns attention. Attention is expensive.

That’s the real crime of spaghetti code: not aesthetics, cognitive cost.

Why it turns into spaghetti

A clean program has a shape you can hold in your head:

Start → do things → finish.

Unstructured jumps destroy that shape.

GOTO breaks the one promise your reader desperately wants: that control flow will be local and predictable.

If any line can jump to any other line, then every line must be read with paranoia.

That’s not programming. That’s anxiety with line numbers.

The escape: structured programming

Structured programming wasn’t invented to be fancy. It was invented to make code readable at scale.

Instead of “jump anywhere,” you get a small set of composable structures:
• sequence (do this, then that)
• selection (if/else)
• iteration (for/while)

You still do the same things, but the control flow becomes visible again.

Here’s the key move: instead of scattering retry logic across labels, you put it inside a loop.

If your BASIC dialect supports WHILE…WEND (many did), you can do:

10 PRINT "Enter a number (1-10)"
20 INPUT N
30 WHILE N < 1 OR N > 10
40   PRINT "Invalid. Try again."
50   INPUT N
60 WEND
70 PRINT "OK"
80 END

Now the program reads like a story again:

Ask → repeat until valid → proceed.

Same behavior. Different shape.

And that shape is the whole point.

The lesson: don’t use GOTO

Here’s the grown-up version, stated plainly:

Don’t use GOTO.

Yes, there are rare cases where it can be used carefully: generated code, constrained environments, or very low-level cleanup paths.

But that’s not the world most of us are programming in.

In real software, with real teammates and real deadlines, GOTO is a trap. It makes control flow non-local, and non-local flow makes reasoning expensive. It turns debugging into archaeology.

So the beginner-to-professional upgrade is simple:

Stop jumping. Start structuring.

If you need to repeat, use a loop. If you need to choose, use IF…THEN…ELSE. If you need to reuse, use a function. If you need to abort, return early or throw an error.

Your future self will thank you. Your teammates will thank you. Your pager will thank you.

Final Thoughts

Logo taught me wonder: move the turtle, watch a picture appear.

BASIC taught me discipline: tell the machine exactly what to do, step by step.

But the most important thing BASIC taught me might be this:

A program is not just instructions for a computer.

It is a story for the next human.

And the moment your story needs a map and a compass, you’ve stopped writing a program and started writing a trap.

BASIC taught me to instruct.

If Logo felt like whispering wishes to a turtle, BASIC felt like standing next to a machine and giving it crisp, literal orders. Not suggestions. Not vibes. Orders.

And the machine was obedient in the way only machines can be: perfectly, relentlessly, and without mercy for ambiguity.

The BASIC mindset: the computer is dumb, so be precise

BASIC’s core lesson is simple:

Computers do not infer intent. They execute steps.

So you learn to think in sequences:
1. Put the input somewhere.
2. Transform it in small moves.
3. Store intermediate results.
4. Print the outcome.
5. Stop.

That “step-by-step” habit is not just syntax. It is a worldview.

Programs as recipes, not drawings

In Logo, the turtle is the main character. You tell it to move, and the picture emerges.

In BASIC, the program itself is the main character. It is a recipe.

Here’s the kind of thing early BASIC invites you to write:

10 INPUT “Enter side length”; S
20 P = 4 * S
30 PRINT “Perimeter = “; P
40 END

No magic. No hidden state. No geometry fairy.

Just: ask, compute, print.

And even that tiny program quietly teaches important ideas:
variables, arithmetic, input/output, and the idea that a program is a controlled sequence of actions.

Line numbers: the original breadcrumb trail

The first thing you notice in old-school BASIC is the line numbers.

They are not decoration. They are control points.

You don’t just write code.
You create a path the computer will walk.

10 PRINT “I will count.”
20 FOR I = 1 TO 5
30 PRINT I
40 NEXT I
50 PRINT “Done.”

The flow is visible, like a little parade.

And once you learn that you can jump…

GOTO: power, then chaos

BASIC makes it very easy to say: “Go there next.”

10 LET X = 0
20 LET X = X + 1
30 PRINT X
40 IF X < 5 THEN GOTO 20
50 END

This works. It is also the seed of future pain.

Because once your program becomes a web of jumps, your brain becomes a detective in a bad mystery novel. Every GOTO is a plot twist.

This is why people later talked about “structured programming”: it’s not about being fancy, it’s about keeping the story readable.

State is the real subject

In BASIC, you’re always holding state in your hands.

Variables are the center of gravity. They change, they accumulate, they persist.

That teaches a different kind of thinking than Logo:

Logo: move an agent, watch an effect

BASIC: change a value, watch consequences

And you start noticing patterns: • Counters • Accumulators • Flags • Branches • Loops

In other words: the basic building blocks of the “imperative” style of programming, where you tell the machine how to do the job, not just what you want.

Error messages as teachers

BASIC’s errors are blunt little teachers.

“Syntax error.”
“Type mismatch.”
“Out of data.”

Each one says: you assumed the computer would guess what you meant. It will not.

So you learn to be explicit.
You learn to reduce ambiguity.
You learn to debug.

Not as a skill for code, but as a skill for thought.

The punchline

Logo gave me wonder.
BASIC gave me discipline.

Logo made me feel like programming was art.
BASIC made me feel like programming was logic.

And both were true.

BASIC’s gift is not that it’s the most elegant language.
Its gift is that it forces you to think like a machine for a while.

And once you can do that, you can later learn the higher trick: how to make machines feel a little more human.

The first day of the class we were excited. We did not get to see the newly build Computer Labs but were told lots about Computers - what is a computer? what is data? what is meaningful information? cpu, alu, monitor, keyboard and the funniest of all - the mouse. Soon we progressed to learn programming and the language of choice for that was Logo⁴.

In Class IV, Logo felt like magic with training wheels.

A turtle sat at the center of the screen and waited for commands. You would say:

FD 50 RT 90 FD 50 RT 90 FD 50 RT 90 FD 50 HT

and a square would appear, as if geometry had agreed to be friendly for once.

Logo is Lisp?

Years later, I discovered a fact that sounds like a prank until you stare at it long enough:

Logo is often described as a dialect of Lisp, or at least a Lisp-family language.⁵

That claim is confusing at first because Logo does not look like Lisp. Lisp is famously parenthesized. Logo is famously turtle-ish. So what gives?

The trick is that “dialect” here is not about surface syntax⁶. It is about the underlying ideas: evaluation, data structures, and the way programs are shaped.

Below are the family resemblances hiding in plain sight.

1. Prefix thinking: verbs first

Lisp’s signature habit is that functions come first, arguments follow.

(+ 3 4)
(forward 50)
(right 90)

Logo does the same thing, it just drops the parentheses and speaks like a teacher.

sum 3 4
fd 50
rt 90

Same mental model. Different costume.

2. Lists matter a lot

Lisp is built on lists. Logo inherits that list-centered worldview.

In many Logo dialects you can work with lists directly:

print [1 2 3 4]
print first [a b c]     ; a
print butfirst [a b c]  ; [b c]

If you have ever met Lisp’s car and cdr, you can feel the same head-and-tail spirit here, just with names that won’t scare a fourth grader.

3. Quoting and symbols: “name” vs “value”

In Lisp, quoting is essential because you often want to talk about symbols without evaluating them.

Logo has a similar separation between a name and a value.

In UCBLogo-style notation:

make "x 10
print :x

The “x is the symbol name. The :x is the value stored in that name.

Different punctuation, same conceptual split: symbol vs value, data vs evaluation.

4. Recursion feels natural, not exotic

Lisp culture loves recursion because it pairs naturally with lists and self-similar problems.

Logo teaches recursion early too, especially in dialects like UCBLogo.

A simple recursive spiral:

to spiral :n
if :n < 1 [stop]
fd :n
rt 90
spiral :n - 1
end

Here we are declaring the function named spiral. to is the keyword to declare functions in Logo.

This is not “turtle magic.” This is a core Lisp-family habit: define a procedure, then solve the big problem by repeatedly solving smaller versions of it.

5. Code-as-data vibes: instruction lists you can run

One of Lisp’s deepest tricks is that code and data are made of the same stuff. That enables patterns like building code as a data structure, then evaluating it.

Logo approaches that idea in a friendlier way: lists can represent sequences of commands, and many Logo environments support executing those command lists.

Even when you never say the word “eval,” you are inching toward the same philosophical cliff: programs can be treated as manipulable objects.

That is very Lisp. It is also very sneaky.

Final Thoughts

Logo doesn’t look like Lisp because it was designed for humans first, especially young humans.

But the bones show through:
1. Prefix function application (verbs first)
2. List-centered data thinking
3. Quoting and symbol/value separation
4. Comfort with recursion
5. A path toward code-as-data

So the sentence “Logo is a Lisp dialect” is not a joke. It is a reminder that programming languages can share a soul even when they do not share a wardrobe.

Back where it all begin

In Class IV, we had no idea that we were accidentally being taught one of the deepest ideas in CS, that lists can represent both data and instructions, and the difference between them is often just “how you choose to evaluate.”

Notes and references

It has brought back the joy to programming. The kind of joy you thought adulthood, meetings, and Jira had permanently confiscated.

And yet, right now, most agents are more or less super intelligent babies.

They are brilliant. They are fast. They can surprise you. But they still need to be fed context again and again.

Today, while working on my service virtualizer, I had to continuously inform the agent about my preference for naming API models and domain models. The difference matters:

• API models are edge interfaces, representing outward state.
• Domain models are internal shapes, used to pass messages within the API.

The agent continuously “lied” that it was following the instructions I provided under the .github/instructions folder. After multiple rounds of trial and error, it partially understood the assignment.

That’s the gap between intelligence and autonomy.

The autonomy ladder: vibe coding, ping pong, vacation

It is going to take some time before agents can act independently while you play ping pong. And slightly longer for you to delegate the work completely to a few AI agents and go on vacation.

AI agents need to be context-aware for me to enjoy ping pong. They need to write properly logged and observable clean code before I can trust them enough to enjoy a vacation.

That last line is the whole story.

Ping pong is a context problem. Vacation is an accountability problem.

A concrete example: my model naming rule

This is where “feed context again and again” shows up in real code.

API models should be nouns

API models “datafy” representational state. So there is no separate request and response. There is only one state to represent for both request and response.

Some fields are read only, sure. But it is still one state.

So instead of:

• CreateEndpointRequest
• CreateEndpointResponse
• EndpointResponse

I want:

• Endpoint

Domain models should not say “Request”, “Response”, or “Data”

Domain models don’t need Request, Response, or Data as suffixes. That information is redundant.

EndpointData as a class serves no purpose compared to Endpoint as a class.

If it is the domain concept, name it like the concept: Endpoint, VirtualService, Route, Rule, Match, Mapping.

If context matters, packages can carry it: in.systemhalted.api.model.Endpoint in.systemhalted.domain.model.Endpoint

Same noun, different layer.

The real issue: preferences are not enforceable

Human teams survive because we turn preferences into systems.

“Please follow this convention” is polite. But politeness is not a compiler.

If you want agents to stop “lying” (really: confidently guessing), you have to move from memory to mechanism.

In other words, from vibes to accountability.

Make conventions executable

The big move is simple: turn conventions into checks that fail loudly.

Then the agent doesn’t need to remember your rules. It just needs to pass reality.

Option 1: enforce architecture rules with ArchUnit

ArchUnit is a Java testing library for validating architectural decisions in code. It lets you write tests for package boundaries, dependency direction, layering rules, and conventions that are otherwise tribal knowledge.

That is exactly what an AI agent struggles with: it will agree with tribal knowledge, then forget it, then agree again.

Here’s a practical enforcement approach:

• API models live in ..api.model.. and must not end with Request, Response, or Data
• Domain models live in ..domain.model.. and must not end with Request, Response, or Data
• Domain must not depend on API

// src/test/java/in/systemhalted/architecture/ModelConventionsTest.java
package in.systemhalted.architecture;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

class ModelConventionsTest {

    private final JavaClasses classes = new ClassFileImporter()
            .importPackages("in.systemhalted");

    @Test
    void api_models_must_not_end_with_request_response_or_data() {
        ArchRule rule = classes()
                .that().resideInAPackage("..api.model..")
                .should().haveSimpleNameNotEndingWith("Request")
                .andShould().haveSimpleNameNotEndingWith("Response")
                .andShould().haveSimpleNameNotEndingWith("Data");

        rule.check(classes);
    }

    @Test
    void domain_models_must_not_end_with_request_response_or_data() {
        ArchRule rule = classes()
                .that().resideInAPackage("..domain.model..")
                .should().haveSimpleNameNotEndingWith("Request")
                .andShould().haveSimpleNameNotEndingWith("Response")
                .andShould().haveSimpleNameNotEndingWith("Data");

        rule.check(classes);
    }

    @Test
    void domain_must_not_depend_on_api() {
        ArchRule rule = noClasses()
                .that().resideInAPackage("..domain..")
                .should().dependOnClassesThat().resideInAnyPackage("..api..");

        rule.check(classes);
    }
}

This does not prove a name is a noun. But it blocks the most common failure mode: growing a forest of *Request, *Response, and *Data types that all mean the same thing.

Option 2: generate API models, handcraft domain models

If your API layer is OpenAPI driven, treat API models as edge artifacts and generate them. Then keep domain models intentionally authored and stable.

The principle is simple:

when the outside world changes, your domain shouldn’t shatter like glass.

Option 3: a definition of done for agents

Agents struggle because “done” is fuzzy.

So make it concrete:

1. Restate conventions from .github/instructions in plain English
2. Implement the change
3. Run tests
4. Show evidence: test output, files changed, and convention checks passing

That’s how you replace “trust me” with “see for yourself.”

Observability is the vacation requirement

Ping pong needs context awareness. Vacation needs observability.

If an agent writes code that “works” but cannot explain itself at runtime, you have not delegated work. You have adopted a mystery.

Vacation grade code needs boring grown up traits:

• structured logs you can search
• correlation IDs you can follow
• meaningful error handling
• metrics and traces where it matters

Because when you are on vacation, the only thing worse than an outage is an outage that speaks in riddles.

Final thoughts

Agents don’t mainly need to be smarter. They need to be more accountable.

An agent without a stop condition is just a very confident infinite loop.

The trick is not to lecture the agent harder. The trick is to build a world where “following instructions” is measurable.

Then you can pick up the paddle.

And later, maybe, the suitcase.

I began this post in 2016, when Java 9 was still unreleased and Project Jigsaw felt like an approaching weather system. Java 9 eventually shipped, and the module system became real, imperfect, and unexpectedly enlightening.

This post keeps the original question intact: what is modularity and why did Java need the platform itself to care?

Java already had “modules”… right?

For the past few years, Java has evolved quickly, mostly for the better. JDK 8 changed everyday Java with lambdas and streams, making a more functional style feel native instead of like cosplay.

Then came JDK 9 and Project Jigsaw, the Java Platform Module System (JPMS). The obvious objection was, and still is:

Java already has JARs. Enterprise Java has WARs and EARs. Source code has packages and access modifiers. So why add “modules” at all?

To answer that, we need to be annoyingly precise about what a module is.

What is a module?

A module is not just “a bunch of related code.” That definition is so generous it would make my Downloads/ folder a module, and it absolutely should not be trusted with responsibility.

A better definition:

A module is a unit with an enforceable boundary.

In practice, a module needs at least these traits.

1. Encapsulation (a hidden interior)

Encapsulation is the right to say: “this part is implementation detail; do not touch.”

Java supports encapsulation via access modifiers (private, package-private, protected, public) and via packages. In the POJO world, we keep fields private and expose behavior through methods so nobody can accidentally mutate internal state and then act surprised when physics happens.

But here is the catch:

Packages are excellent organizing units, but by themselves they are not deployment boundaries.

Once code is on the classpath, it tends to behave like a single sprawling neighborhood where everyone can wander into everyone else’s backyard, sometimes through reflection, sometimes through “it was convenient,” sometimes through sheer dependency gravity.

2. A public surface (an intentional API)

A module must have a public surface: a set of types meant to be used by outsiders.

This matters because modularity is not just hiding. It is also communicating on purpose.

When modules interact, they should do so through the exported API, not through accidental knowledge of internals. This is how systems remain refactorable without becoming brittle.

So far, this sounds like “write disciplined code,” which is true, and still not the full story.

The painful question is: can the platform help enforce that discipline?

Why packages and JARs were not enough?

Packages and JARs let us aspire to be modular. They do not consistently let us enforce it.

Here are the classic failure modes that show up as systems grow.

1. The classpath is a soup

The classpath is wonderfully simple and brutally permissive. Put things on it, and they exist.

Common outcomes:

• Accidental dependencies form silently.
• Internals become “public” by habit. “Just import it.”
• Debugging becomes archaeology. “Who pulled in this version, and why does it only fail on Jenkins?”

2. JAR hell is real, and it has receipts

When multiple JARs provide overlapping classes, or when classloading order changes, you can get failures that only appear at runtime and only on certain machines.

Even when your build tool is trying to help, the model is still basically: assemble a pile of bytecode and hope it behaves.

3. Encapsulation at runtime was historically negotiable

Before JPMS, it was common for libraries to reach into non-public areas, either:

• Using reflection to access private members.
• Using internal JDK APIs because they existed and were “handy.”

This worked until it did not. And the “did not” usually arrived as a production upgrade - not an upgrade by choice but force.

4. Split packages and duplicate worlds

On the classpath you can end up with the same package name spread across multiple JARs. Tools can limp along, humans can suffer quietly, and then one day something breaks in a way that makes you question reality.

A modular system has to be stricter about identity, or it cannot reason about the graph.

What Jigsaw actually adds

Project Jigsaw turns modularity into something the compiler and runtime can understand.

A Java module has:

• A name (a stronger identity than “whatever the filename is”).
• Declared dependencies (what it requires).
• Declared exports (what it makes available to other modules).
• Strong encapsulation by default (if you do not export it, it is not part of your public world).

This is expressed with a module descriptor: module-info.java.

A minimal example:

module com.example.billing {
    requires java.sql;
    exports com.example.billing.api;
}

The point is not ceremony. The point is boundaries that can be checked.

Packages vs modules, a clean mental model

Think of it like this:

• A package groups related types and helps structure code.
• A module groups packages and declares which packages are visible to the outside world.

Packages help you organize. Modules help you enforce.

“Enforce” how, exactly?

JPMS enforces things in two major places: compilation and runtime.

1. Reliable configuration (dependency truth)

With modules, dependencies are not an emergent property of “whatever happens to be on the classpath today.”

Instead, the runtime resolves a module graph:

• Each module declares what it requires.
• The system checks that required modules exist.
• The system checks for conflicts that would make the graph incoherent.

This catches certain categories of surprise runtime failure earlier, because the platform can actually see your dependency structure.

2. Strong encapsulation (real boundaries)

With modules, code in a non-exported package is not accessible to other modules at compile time, and at runtime access is strongly controlled.

This is the key philosophical shift:

You are not just suggesting which parts are internal. You are declaring it, and the platform can enforce it.

A quick tour of module descriptor concepts

The module-info.java file is small, but it has teeth. Here are the ideas you will see in real projects.

requires

A module can state that it depends on another module.

module com.example.app {
    requires com.example.billing;
}

exports

A module can export a package to make it part of its public API.

module com.example.billing {
    exports com.example.billing.api;
}

Everything else stays internal by default.

There is also qualified export, where you export only to specific friend modules:

module com.example.billing {
    exports com.example.billing.internal to com.example.app;
}

That is useful for tightly coupled modules, though it should be used sparingly because it creates special relationships that age poorly.

opens

Exporting is about normal access. Opening is about reflection.

Frameworks use reflection for dependency injection, serialization, proxies, and other wizardry. JPMS makes you be explicit about that:

module com.example.model {
    opens com.example.model.entities;
}

You can also open to specific modules only:

module com.example.model {
    opens com.example.model.entities to com.fasterxml.jackson.databind;
}

Services: uses and provides

The service mechanism is the module-friendly way to do plugin architecture.

Consumer:

module com.example.app {
    uses com.example.spi.PaymentProvider;
}

Provider:

module com.example.stripe {
    provides com.example.spi.PaymentProvider
        with com.example.stripe.StripePaymentProvider;
}

But what about my existing non-modular JARs?

JPMS did not pretend the world would instantly become modular. It introduced a migration story, and it is worth understanding because it explains a lot of real-world behavior.

The unnamed module

If you put JARs on the classpath instead of the module path, they effectively live in the unnamed module. This unnamed module can read everything, and everything can read it, which is intentionally permissive to keep legacy code running.

It is the compatibility bridge. It is also where modular purity goes to take a nap.

Automatic modules

If you put a regular JAR on the module path, the system can treat it as an automatic module with a derived name and permissive readability rules.

This is a practical stepping stone, not a perfect end state.

A common migration path looks like:

• Run as classpath, accept the unnamed module.
• Move some things to module path, tolerate automatic modules.
• Modularize the important libraries and applications over time.

Not glamorous, but it works, and it respects the fact that software is mostly sedimentary rock.

The JDK itself became modular

One of the most concrete outcomes of Jigsaw is that the JDK stopped being a monolith. It became a set of modules.

This matters because:

• The platform itself has clearer internal boundaries.
• The JDK can strongly encapsulate internal APIs, reducing accidental dependencies on JDK internals.
• Tools can assemble smaller runtimes for specific applications.

That last point is where tools like jlink enter the story, but it is better saved for a later post, once the basics are anchored.

So why Project Jigsaw?

Now we can answer the original “why” without hand-waving.

Java had packaging and namespacing. It did not have platform-enforced boundaries.

Project Jigsaw exists to make modularity:

• Declarative, so the platform can see your intent.
• Verifiable, so tools can reason about your dependency graph.
• Enforceable, so “internal” actually means internal.

It turns modularity from a cultural norm into a constraint you can build against.

That is the difference between “please do not touch” and “the door is locked.”

What is next

This was Part 1: the definition, the motivation, and the shape of the solution.

In Part 2, we will go concrete:

• A tiny multi-module project you can compile and run.
• The first “why can I not access this package anymore?” moment, explained.
• Practical patterns: what to export, what to keep internal, and how to avoid designing a module system that only you understand.

Because nothing teaches architecture faster than a compiler error that is technically correct and emotionally rude.

But testing cannot guarantee a perfect product.

At best, testing gives you information. That information helps you mitigate the risk of releasing something that is quietly wrong, and quietly expensive.

If you want a perfect product, you would need perfect and exhaustive testing. Gerald M. Weinberg points out the trap: exhaustive testing implies an infinite number of tests, and that takes more time than the life of the product itself¹.

Edsger W. Dijkstra said, “Testing may convincingly demonstrate the presence of bugs, but can never demonstrate their absence.”²

So do not treat tests like a purity ritual. Treat them like a flashlight. A very practical flashlight. One you point at the dark corners first.

Testing is important, but knowing what to test is imperative

Most teams do not fail because they do not test. They fail because they test the wrong things, at the wrong layer, for the wrong reasons.

The real question is not “Do we have tests?” The real question is “Are our tests buying us truth, where it matters most?”

A simple way to choose is to think in tiers - Must Haves (Guarantees), Should Haves (Safeguards), Good to Have (Hardening)

Must be tested (Guarantees)

These are the tests for the things that, if they break, make the business bleed, trust vanish, and regulators reach for their red pens.

Examples:

1. Money movement and irreversibility: double charges, missing payments, incorrect balances, wrong rounding.
2. Identity and authorization: user A accessing user B’s data, broken MFA, weak reset flows.
3. Data integrity invariants: dedupe rules, ordering guarantees, idempotency, “exactly once” assumptions.
4. Privacy and compliance: PII leakage, audit log gaps, retention and encryption failures.

Should be tested (Safeguards)

These tests cover the everyday production failure modes, not glamorous, but relentlessly loyal to chaos.

Examples:

1. Integration seams: timeouts, retries, partial failures, schema changes.
2. Negative paths: invalid inputs, missing fields, weird encodings, malformed payloads.
3. Performance cliffs: cold starts, peak traffic, queue buildup, slow queries.

Good to have (Hardening)

This is maturity. Not mandatory for day one, but it pays rent for years.

Examples:

1. Property based tests: verify invariants across many generated inputs.
2. Fuzzing: especially for parsers, inputs, and security boundaries.
3. Chaos and resilience tests: inject latency, kill dependencies, verify graceful degradation.
4. Observability checks: alerts that fire, logs that help, traces that connect.

Your test portfolio

Think of tests like a portfolio. You are allocating limited time to buy maximum confidence.

Some tests are cheap and plentiful. Some are fewer but high value. Some are expensive insurance policies.

A healthy suite is not “more tests”. It is better allocation.

Two rules keep you honest:

1. Put most assertions as close to the code as possible. Fast feedback. Precise failures.
2. Put a small number of assertions as close to the user as necessary. Real confidence.

The testing pyramid

The classic pyramid is still useful, not as dogma, but as economics.

End-to-End (few)
Integration / Component (some)
Unit (many)

Unit tests are cheap, fast, and local.

End-to-end tests are expensive, slow, and brittle, but they buy you “did the actual business journey work?”

The pyramid is not a moral statement. It is a cost statement.

Unit tests

Best for pure and deterministic logic: calculations, transformations, validation, edge cases, invariants.

Unit tests answer:

Is this piece correct in isolation?

A unit test is most valuable when it is small, fast, deterministic, and cheap enough to run on every change. Google’s testing guidance³ emphasizes “small tests”, their closest equivalent to unit tests as constrained in resources, and their book⁴ stresses that unit tests should be fast and deterministic so engineers can run them frequently.

Michael Feathers’ commonly cited rule of thumb is also useful as a boundary. If a test touches a database, the network, the filesystem, or needs a special environment configuration, it’s not a unit test. It’s pretending to be one⁵.

A common trap is over-mocking. If a unit test is mostly mocks, stubs, and call verification, you may be testing your imagination instead of behavior. Prefer asserting outputs and state over asserting call choreography. Only lean on interaction-based or call-count assertions when the unit’s job is orchestration, for example retries, sequencing, or enforcing that a collaborator is invoked a specific number of times.

Integration and component tests

These test the seams where production loves to bite.

Integration tests answer:

Do my assumptions about the world hold?

Martin Fowler’s simplest framing is still the most useful⁶: integration tests check whether independently developed units work correctly when connected. The term is overloaded, so it helps to state the scope you mean (two components, one service plus its database, one service plus a message broker, etc.).

Component tests are a related idea: they limit the exercised software to a portion of the system (a component) rather than the full stack. In practice, that often means “this service works with its dependencies, without standing up the entire ecosystem.”

Google’s “test sizes” vocabulary maps nicely here. Their guidance often treats “medium tests” as the place where a small number of tiers communicate properly, which is exactly the integration sweet spot.⁴

Examples:

1. Database queries, migrations, transaction boundaries.
2. Serialization, schema evolution, backward compatibility.
3. Messaging, retries, dedupe, idempotency under real conditions.
4. Service-to-service calls with real HTTP and real headers.

Contract tests

The underappreciated secret weapon in distributed systems.

Contract tests answer:

Are we still speaking the same language across the boundary?

Martin Fowler’s framing is crisp: contract tests check the contract of external service calls, focusing on the format and expectations, not necessarily the exact data values.⁷ In other words, they verify the handshake between a consumer and a provider without requiring a full end-to-end environment.

Thoughtworks makes the “why now” argument for microservices: consumer-driven contract testing is a key part of a mature testing portfolio because it enables independent service deployments without accidentally breaking consumers.⁸

A contract test asserts the handshake between consumer and provider: request shape, response shape, defaults, error contracts, compatibility.

End-to-end tests

Keep these few, but sacred.

End-to-end tests answer:

Does the customer story still work?

Google’s testing guidance treats these as “large” tests: higher fidelity, but slower, more expensive, and more prone to flakiness than smaller tests, which is exactly why you keep them few and focused.³⁴

A common trap is using end-to-end tests to compensate for missing lower-level tests. That’s how you get a flaky suite that everyone learns to ignore. The testing equivalent of buying a treadmill and using it to hang jackets.

Pick critical business journeys and test them like brakes on a car: payment flow, login flow, upload-and-view flow.

A “modern pyramid” that fits microservices better

Many teams quietly evolve toward this:

End-to-End (tiny cap)
Integration / Component (solid middle)
Contract tests (thin band)
Unit (broad base)

This reduces the urge to build a giant end-to-end “everything suite” that is slow, brittle, and mostly good at wasting Tuesday afternoons.

A practical decision rule: where should a test live?

Use this mental routing table:

1. If it is a business invariant, test it at the unit level first.
2. If it crosses a boundary you do not control, add a contract test.
3. If it depends on real infrastructure behavior, add an integration or component test.
4. If it is a critical customer journey, add an end-to-end test.

Test the truth close to the source. Test the handshake at the boundary. Test the journey only where it matters.

Real world examples

Example 1: Payments or loan servicing posting pipeline

A customer makes a payment. It gets authorized, posted, and the receipt is generated.

Must be tested:

1. Idempotency: the same payment request processed twice must not double-post.
2. Ledger correctness: principal vs interest allocation, fees, rounding, balance changes.
3. Atomicity: either all related records update, or none do. No “half paid” states.

Should be tested:

1. Retries and timeouts between services.
2. Duplicate events from the bus, out-of-order delivery, delayed settlement.
3. Reconciliation: what happens when tomorrow’s batch notices a mismatch?

Good to have:

1. Chaos: gateway latency spikes, downstream returns 503, does your system degrade or panic?
2. Property tests: ledger invariants remain true across random sequences.

A tiny invariant sketch:

record Ledger(long debitCents, long creditCents) {
  long net() { return creditCents - debitCents; }
}

@Test
void ledgerNetMatchesArithmetic() {
  var r = new java.util.Random(0);
  for (int i = 0; i < 10_000; i++) {
    long debit = r.nextInt(1_000_000);
    long credit = r.nextInt(1_000_000);
    var l = new Ledger(debit, credit);
    org.junit.jupiter.api.Assertions.assertEquals(credit - debit, l.net());
  }
}

This does not prove correctness. It proves you declared a truth, and you keep checking it.

Example 2: Login plus token issuance

Must be tested:

1. Authorization boundaries: user A cannot access user B’s resources. Ever.
2. Token expiry and refresh: no immortal sessions.
3. Password reset and MFA: the “I lost access” path is where attackers live.

Should be tested:

1. Clock skew behavior in token validation.
2. Rate limiting and lockouts without harming real users.
3. Key rotation behavior in realistic rollout windows.

Good to have:

1. Fuzz JWT claims and headers.
2. Replay and session fixation abuse cases.

Example 3: Document upload plus classification

Must be tested:

1. Correct customer association: misfiled documents are silent disasters.
2. Access control: only authorized users can view or reclassify.
3. PII handling: retention, redaction, encryption behavior.

Should be tested:

1. Corrupt PDFs, huge files, mixed encodings, virus scan failures.
2. Async pipeline correctness: retries, dead-letter paths, idempotent processing.
3. Search indexing lag and eventual consistency behavior.

Good to have:

1. Drift checks on classification confidence over time.
2. Canary documents monitored continuously.

Closing

Testing will not make your product perfect. It will keep your product honest.

Use tests to gain information about bugs, then fix them. Do not let the presence of bugs shame you if your testing caught them.

A perfect product is a myth. A low-quality product is a choice.

References

The list was short, and a bit grand for a college kid’s diary:

Lord Krishna. Mahatma Gandhi. Bhagat Singh. Ram Prasad Bismil. Premchand. Jawaharlal Nehru. Sardar Vallabhbhai Patel. Dr. A.P.J. Abdul Kalam. Dr. Manmohan Singh.

And that night, one more name joined them:

Dr. Karan Singh.

I had just encountered his articulation of Hinduism and Hindutva, and it quietly rearranged the furniture in my head.

The rare people who touch both mind and heart

I have always been suspicious of “inspiration.”
Most grand speeches evaporate by the time you reach the parking lot.

But every once in a while, someone’s words don’t just sound wise, they start doing slow, patient work inside you. They challenge you, annoy you, educate you. They sit on your mental bookshelf and refuse to leave.

That is what these figures did for me.

• Krishna’s conversations in the Gita taught me that doubt is not a sin but a starting point.
• Gandhi’s stubborn insistence on non-violence showed how inner discipline can become political force.
• Bhagat Singh and Ram Prasad Bismil embodied courage that did not wait for “perfect conditions.”
• Premchand dragged everyday Indian life into literature and forced us to look at it without filters.
• Nehru and Patel turned impossible theory into a functioning state.
• Kalam and Manmohan Singh represented a quiet, technocratic ideal: intelligence without theatrics.

From this crowd of giants, I did not receive a single “formula for life.”
What I absorbed was a way of thinking: to question, to empathize, to stay curious.

And then came Karan Singh, with a deceptively simple distinction:

Hinduism as a way of seeking;
Hindutva as a project of identity.

Hinduism: river, not fortress

The Hinduism I grew up with did not arrive as a rulebook.
It arrived as:

• stories my elders told at night
• bhajans floating from a neighbour’s house
• a temple visit that was half spirituality, half street food
• a vague habit of folding hands before exams “just in case”

It was messy, contradictory, generous. You could argue with God, ignore God, or turn God into a metaphor and nobody came to confiscate your ration card.

When I later read and heard Karan Singh speak, he put sharper language to what I had only felt:

Hinduism is a civilizational habit of searching.
It is comfortable with multiplicity: many deities, many philosophies, many paths.

You can be drawn to Advaita’s non-dual silence, to Bhakti’s emotional surrender, to Yoga’s discipline, or to a calm agnosticism that still respects the tradition. All of these can sit around the same metaphorical kitchen table and argue late into the night.

The point is not that Hinduism is flawless or superior. History is littered with its own injustices and blind spots. The point is that, at its core, it contains tools to self-correct: debate, commentary, reinterpretation, dissent from within.

That is what makes it feel like a river; ancient, meandering, sometimes polluted, but always capable of renewal.

Hindutva: when a river is turned into a wall

Hindutva is something else.

Hinduism asks, “What is the nature of reality, self, and duty?”
Hindutva asks, “Who truly belongs here?”

One is metaphysical and ethical.
The other is political and majoritarian.

Hinduism is comfortable with questions that may never be fully answered.
Hindutva is obsessed with answers that must never be questioned.

Once you see this difference, it becomes hard to unsee:

• Hinduism can live alongside other faiths, learn from them, even absorb ideas without feeling threatened.
• Hindutva needs a permanent sense of threat to justify itself. Without an enemy, it has no purpose.

Hinduism invites you to look inward and transform yourself.
Hindutva invites you to look outward and suspect your neighbour.

Hinduism is vast enough to hold the Gita, the Upanishads, the Charvaka materialists, the Bhakti poets, the Sufi-infused traditions, and a million local deities with their own stories.

Hindutva tries to compress all of that into a single slogan, preferably in all caps.

Why Karan Singh’s distinction still matters

Back in 2006, I did not fully grasp the political weight of this difference. I just knew it felt right that someone could say:

“I love Hindu philosophy deeply,
and precisely because of that,
I reject narrow, exclusionary nationalism done in its name.”

In a time where every identity is being sharpened into a weapon, this stance feels almost revolutionary.

It offers a third path:

• Not self-hating rejection of your own culture.
• Not blind worship of a mythical golden past.
• But a rooted openness: secure enough in its heritage to be self-critical and humane.

That is why I put Karan Singh on that short list in my notebook.
He did what real teachers do:
he gave language to a discomfort I already had, and showed that loving a tradition and resisting its misuse are not contradictions — they are obligations.

Where this leaves me today

Nearly two decades after that late-night entry, I find my relationship with faith has become more agnostic, more questioning, sometimes more impatient.

But the basic architecture remains:

• I am still more interested in Dharma as a lived, everyday ethic. Hinduism gives me identity.
• I am still suspicious of any ideology that needs enemies to survive.
• And I still feel that if your God cannot coexist with someone else’s God or their lack of one, the problem is not with them, it is with your God-concept.

Hinduism gives me metaphors, stories, and philosophical toys to think with.
Hindutva tries to reduce all that complexity into a political loyalty test.

I know which side of that line I want to stand on.

That boy in 2006 thought he was just making a list of impressive people.
What he was really doing was choosing his intellectual ancestors.

I am still trying, clumsily, to be worthy of that lineage where courage, curiosity, and compassion matter more than flags and slogans.

If Hinduism is a river, I would rather spend my life learning to swim in it,
than helping anyone build walls around it.

I know you would not have expected your future self to write to you, but this is in fashion these days and you have always been fashionable, so here it is.

I want to talk to you about this whole “find your passion” thing you keep worrying about.

You keep saying you are not sure what you are passionate about. You say it like it is a defect, like some magical signal that never arrived from the sky. I want to tell you gently: that sentence is hiding the truth instead of revealing it.

Most people, including you, already have some sense of what they enjoy. You know which problems make you forget the time. You know which topics your eyes light up for, because your family has to tell you to stop talking about them. When you say “I don’t know my passion,” what is usually happening inside you is not emptiness. It is a mix of fear, confusion, and borrowed ideas about what passion is supposed to look like. Don’t let other people define your preferences. Decide and build your own.

So let us unpack the lies you have quietly absorbed.

The first lie is that there is one true passion.

You are not a single label. You never were. You like computer science, physics, management, writing, astronomy, history, mentoring, and three other things you will discover later. You are not broken because you cannot squeeze all of that into one tidy word like “developer” or “writer”.

For you, passion is not a single topic. Passion is the way you engage with many topics. You love taking things apart, understanding how they work, building something from that understanding, and then explaining it to someone else. That pattern keeps repeating in different domains. That pattern is your passion, whether you are debugging a system, appreciating history, writing an essay, or teaching someone to look at Jupiter for the first time.

When you try to force yourself to choose one banner and kill everything else, you feel like you are betraying yourself. You are right to resist that.

The second lie is that you must discover your passion before you are allowed to move.

You imagine that somewhere out there is a perfect fit, a calling with neon lights and background music. Until you “find” it, you feel you are just wandering.

Here is what you will slowly learn. Passion is not a lightning bolt from the sky. Passion is a story you tell later about the things you have stuck with long enough to get good at and care about. You start with something you already kind of like. You do it again. You do it when it is fun. You do it when it is boring. You survive the part where you think you are terrible. You improve. Other people benefit from what you do. Somewhere along that path, it stops being just a task and starts becoming part of who you are.

From the outside, people say, “You found your passion.” From the inside, it feels much more ordinary. You chose something. You stayed with it. Habit, skill, and meaning slowly braided themselves into something deeper.

This is not ordinary. Building habit and skill takes effort and time, and you did it. Yourself.

This is true for writing. It is true for leadership. It is true for engineering. You did not “find” those passions like lost keys. You built them out of small, stubborn repetitions.

The third lie is that real passion feels like a 24/7 fire.

You secretly believe that if something is truly your passion, you will wake up excited every single day. No doubt. No friction. No boredom. Always “on fire”. Therefore, whenever you feel tired, or bored, or stuck, you quietly conclude, “Maybe this is not my passion after all.” Then you start scanning the horizon for the next thing that will keep you permanently excited. You call this searching for passion. Mostly it is just running away from discomfort.

Here is what you need to know. Real passion has seasons. Sometimes it looks like flow and obsession and that lovely tunnel-vision when code, or prose, or an idea just pours out of you. Sometimes it looks like maintenance: cleaning up old messes, answering emails, debugging someone else’s bug, rereading and rewriting the same paragraph ten times. The fire is still there, but it is not always a bonfire. Some days it is just a candle that you protect with your hands while the wind blows.

Years later, you will read Mark Twain saying:

“No, Sir, not a day’s work in all my life. What I have done I have done, because it has been play. If it had been work I shouldn’t have done it.”

You will recognise yourself in that line. Not because your life was effortless, but because the things you cared about most often blurred that line between work and play. Some days it felt like play. Some days it felt like hard work. It was still yours.

The absence of constant excitement does not mean the absence of passion. It usually means you have moved from the honeymoon phase to the craft phase.

So where does this leave you?

You are multi-passionate. That is not a diagnosis. It is a description. You love many domains, and you also love the process itself: learning, building, connecting, teaching. You will never be happy stuffing all of that into one narrow identity. You do not need to.

You also do not need to sit on the floor and wait for a divine “passion notification” to arrive. You already know enough to start. You know which things you enjoy more than average. You know which problems you complain about and secretly want to fix. You know where your curiosity keeps returning when nobody is watching.

So, here is the advice I wish you would trust a little earlier.

Stop searching for a single, mythical passion. Start taking small bets on the things you already like.

Write one blog post, even if only three people read it. Take on one slightly scary problem at work and see it through. Teach one person something you know. Let yourself be bad at new things long enough for them to become familiar. Let habit, skill, and impact do their slow, quiet work.

Over years, what will emerge will not be a single word you can put in your bio. It will be a pattern of work and play that feels deeply yours. Call that passion if you want. Call it craft. Call it your way of being in the world.

Just do not keep telling yourself you do not have it.

You have always had it. You were just expecting it to look different.

Regards, Palak

Not a mystical gateway to “better design”.
Not a guarantee of fewer bugs.
A Taylorian construct whose main achievement is simple: it forces people to write unit tests.

I still believe that.

What has changed is this:
I now care less about TDD the ritual and more about the broader habit hiding underneath it.

Thinking seriously about testing and evaluation before writing code is valuable.
Not just at the unit level, but at the functional, component, and integration levels too.

The ritual can be Taylorism.
The mindset is design.

Version 1: TDD as Taylorism

Let me quickly restate the original thesis.

Unit tests are good. They reduce maintenance costs, prevent regressions, and give us courage to refactor.

The problem is human, not technical:

1. Left alone, many teams will not write enough tests.
2. Even when they do, tests are often an afterthought, written just before merge, or not at all.
3. Management wants fewer bugs and lower maintenance cost, but cannot directly measure “future headaches avoided”.

Enter TDD.

TDD turns “write tests” into a visible, enforceable step:

1. Write a failing unit test
2. Make it pass
3. Refactor
4. Repeat

That loop is eminently measurable.

You can ask:

• Did the developer write tests first
• Is the build green
• What is the code coverage

That is classic Taylorism: break down work into small steps, make them observable, then control them.

From that angle, TDD is not a design religion.
It is management plumbing for test-writing behavior.

I still find that framing useful. It explains why TDD took off in large organizations obsessed with metrics and “best practices”.

But it is incomplete.

What changed: from ritual to evaluation

Over time I noticed something awkward.

Even in teams that never practiced “pure TDD”, the best engineers tended to do a version of the thinking behind it:

They imagined failure modes before they wrote code.
They thought about inputs and outputs.
They mentally ran scenarios in their heads.
They cared about how their work would be evaluated, not just how it would compile.

That is not uniquely “TDD”.
That is just good engineering.

So my view shifted:

• TDD-as-ritual is still a Taylorian construct.
• But test-first thinking, in a broader sense, is something you want almost everywhere.

The mistake is to shrink “test-first” down to “unit tests only” and treat everything else as a side quest.

The real question is larger:

Before we add this behavior to the system, how will we know it works?
At every relevant level.

Once you phrase it that way, you are automatically pushed beyond unit tests.

Four levels of thinking before you code

When I say “think about testing and evaluation before writing code”, I do not mean “write a unit test file before a class file” and declare victory.

I mean something more layered.

1. Functional: what would convince a user?

Start at the top.

Imagine a reasonably skeptical product partner or end user sitting next to you. What would convince them that this feature actually works in their world?

That question leads to things like:

• Example flows: “A customer with X, who does Y, should see Z.”
• Edge scenarios: “What if the user loses connectivity halfway through?”
• Policy constraints: “What are we allowed or not allowed to do?”

This is the territory of acceptance or functional tests.

You do not need a test framework to start. Even a one-page doc with concrete examples is already “test-first thinking” at the functional level.

2. Component: what contract does this service promise?

Next layer down: the component boundary.

For any service or module, ask:

• What contract am I promising to the rest of the system
• What do I guarantee about behavior, latency, and failure modes
• How will other teams know we broke something

These questions give rise to component or API-level tests.

Designing them early tends to reveal awkwardness:

• “Why are there three ways to call this?”
• “What happens if the downstream is slow but not down?”
• “Do we retry? For how long? With what backoff?”

Note that we have not yet written a single “public void testSomething()”. We are still shaping the surface area of the system.

3. Integration: how does this behave in the real ecosystem?

The third level is where reality barges in.

Databases. Message queues. Third-party APIs. Authentication. Caches. Time.

Integration thinking asks:

• Can this survive real data, not just happy-path fixtures?
• What happens when the schema changes?
• What if Kafka is briefly on fire?

You might not be able to write full integration tests before any code exists. But if you do not think about them early, you will unconsciously design a system that only works in your unit test universe.

This is where many “nice” designs die in production.

4. Unit: what invariants must always hold?

Finally, the part everybody talks about: unit tests.

At this level, the questions are more granular:

• What assumptions must never be violated inside this function or class?
• What bug would be extremely annoying to debug in prod?
• Which branches are easy to forget about?

Unit tests are excellent at enforcing local invariants and giving you courage to refactor internals.

They are not sufficient to guarantee that the system does what you think it does. But they are a crucial layer in the overall evaluation story.

The important bit is the order of thought:

You do not start from “how do I hit 85 percent coverage”.
You start from “what does success look like at each level” and let tests follow.

TDD as a management tool, test-first as a design habit

This is where I have landed:

I still see TDD, as originally popularized, as a management-friendly practice:

• It decomposes work into simple, repeatable, measurable steps.
• It helps organizations enforce test-writing behavior.
• It pairs nicely with coverage dashboards and pipeline gates.

Nothing about that is inherently bad. In large systems with many teams, some enforcement is necessary. Otherwise tests are the first thing sacrificed under pressure.

The problem is when the enforcement mechanism becomes the goal.

“We do TDD here” becomes identity theatre.
Coverage numbers become performance proxies.
Green builds become the scoreboard.

Meanwhile, nobody is asking basic questions:

• Are we testing the right things at the right levels?
• Do our tests reflect how the system is really used?
• Are we over-investing in unit tests while under-investing in integration and functional evaluation?

That is the shift I care about.

I now treat:

• Tests as management control: useful, but limited.
• Tests as design and evaluation tools: essential, and much broader than TDD usually admits.

So what do we actually do differently?

This all sounds very philosophical, so let me anchor it in a few concrete habits.

First, for any non-trivial feature, write down “how we’ll know this works” before someone opens the IDE.

Not a 20-page spec. A short, sharp checklist:

• Key functional scenarios that must work
• Any user-facing behavior we care about (latency, error messages, data correctness)
• Critical integration points and their expectations
• A couple of nasty edge cases we are afraid of

Second, encourage teams to think in layers of evaluation.

When a design is proposed, ask:

• What are the acceptance tests, even if they are manual
• What API or component tests will protect other teams from our changes
• What integration tests will keep us honest about reality
• Where do unit tests actually provide value, and where are they just “coverage padding”

Third, be explicit about where TDD fits.

If a team finds “write a failing unit test, then code” helpful to structure their work, great. Let them use it.

Just do not confuse the ritual with the outcome.

The outcome is:

• We have a clear, shared understanding of success.
• We have tests at the right levels to guard that success.
• We can change the system with confidence.

Whether that came from strict TDD, loose test-first thinking, or some other workflow is secondary.

Closing the loop

So yes, my old self was right about one thing:

TDD has a strong Taylorian flavor. It is a management technique that emerged to tame the chaos of software development and make test-writing behavior more predictable.

But if I stop there, I miss the deeper point.

The valuable instinct is not “thou shalt always write tests first”.
The valuable instinct is:

Before I add behavior to a complex system, I should be very clear about how that behavior will be evaluated.

At the functional level.
At the component boundary.
At the integration seam.
Inside the unit.

You can reject TDD-as-religion and still embrace that instinct.

In fact, if you care about real systems in the real world, you probably should.

I call it the Org Incentive Optimization Problem.

Here’s how it usually behaves:

You say:

“I fixed a bunch of bugs, cleaned up tech debt, and made the platform more reliable.”

The system hears:

“did routine work”.

You say:

“I built a new platform.”

The system hears:

“high impact, visionary, promotable”.

Same keyboard. Same brain. Completely different reward curve.

The catch is that reliability and maintenance work are compounding assets.
They just don’t come with launch emails, codenames, or shiny demos.

Avoided outages never show up on a slide.
Stable systems don’t page executives at 2am.
So they quietly vanish from the story.

From a computing perspective, this is a messy credit-assignment problem with delayed rewards and noisy signals.

From a human perspective, it looks like this:

• People chase visible “new” work, even when the real value is in strengthening what already exists.
• Platform teams feel pressure to rebrand every major refactor as a “new platform” just to get air cover.
• The folks who keep things boring and dependable get labeled “steady” instead of “high potential”.

If you model it in CS terms, it roughly looks like this:

Input

• A graph of teams, platforms, incidents, and features
• Noisy signals: outages, launches, OKRs, customer metrics
• Human agents who optimize whatever you measure

Objective

Maximize:

• Reliability
• Long-term velocity
• Fair rewards for “unsexy” maintenance work

Minimize:

• Cargo-cult “new platforms”
• Incentive gaming
• Burnout and PIPs for the people keeping it alive

Most orgs end up running a greedy online heuristic:

if (work.isVisibleLaunch()) {
    promote++;
} else if (work.isQuietReliability()) {
    shrug++;
}

Bug fixing gets treated as constant-time hygiene, while “new platform” is treated as quadratic impact, even when the real business value is reversed.

The trick, if you are inside the system:

Make reliability work computable. Never leave it as “I fixed bugs”.

Translate it into:

I reduced incident rate by 40%.

I removed a whole class of failures that used to wake people up every weekend.

I made it safer and faster for five other teams to ship.

Same work.
Different representation in the algorithm.
Very different outcome.

Dhurandhar is a lot to take in – literally the longest Hindi film in 17 years – nearly three-and-a-half hours, very violent, very loud, very extra. But it never felt boring.

Everyone in the cast was fantastic. It was such a fun surprise to see both Rakesh Bedi and Gaurav Gera. It was also a joy to watch Akshaye Khanna after so many years. I’ve been a fan of his since Border, and he still holds the screen with that same quiet intensity. R. Madhavan and Sanjay Dutt were great as usual and Arjun Rampal was properly menacing. Ranveer Singh was simply phenomenal. Sara Arjun, who is just 20, showed her skills even with limited screen time.

The violence is definitely not for the faint-hearted. That was the part Priti didn’t enjoy. But despite the brutality on screen, both of us walked out genuinely loving the movie and the experience of watching it together.

After a long time, a Hindi movie in a theatre felt worth every minute.

A nuclear test.
A war with Pakistan.
Some new sanctions.
A US president lecturing India on something.
An Indian PM “aligning” with Non-Aligned Movement.

Today the relationship is everywhere and nowhere at once. It is in H-1B visas and OCI cards, in TikTok bans and chip fabs, in Quad communiqués and tariff notices to the WTO. It is no longer an exotic foreign policy file. It is infrastructure.

This is my attempt to trace that long arc, from 1947 to the current round of tariff drama that started under Trump and simply refuses to go away.

Non-alignment, nuclear tests, and the Cold War hangover

India became independent in 1947 and partition ripped through the subcontinent. The US, fresh out of the Second World War and already looking at Moscow, wanted allies. India wanted space. Nehru’s trip to the US in 1949 produced warmth in photos and distance in policy. Soon after, India formally planted itself in the Non-Aligned Movement, which Washington always read as “nice words for not being on our side”. ¹²

The first big fracture was 1971. As Pakistan tore itself apart and Bangladesh was born, India intervened decisively and signed a 20-year Treaty of Friendship with the Soviet Union. The US, busy courting China via Pakistan, tilted towards Islamabad even as reports of atrocities in East Pakistan piled up. ¹³

Then came 1974. India tested a nuclear device at Pokhran and declared itself, very politely, a country that would not be told where its nuclear red lines lay. The US response was predictable for that era: non-proliferation laws, nuclear technology cut-offs, and a long season of frost. For more than two decades, “estranged democracies” became the default label for India and the US. ¹²⁴

The relationship in that phase was transactional and narrow. Food aid during the Green Revolution. Some cooperation, some lectures. A lot of mutual irritation. Very little trust.

1991: when economics finally crashed the party

The real reset started not with a summit, but with a balance-of-payments crisis.

In 1991, Narasimha Rao’s government and a then-little-known finance minister called Manmohan Singh opened the Indian economy under duress. Tariffs fell. Markets opened. Foreign investment stopped being a dirty phrase. That single move changed how Washington looked at India, and how Indian business looked at the world. ²⁴

Suddenly, India was not just the country that tested nukes and talked about moral leadership. It was also a place where American companies could sell planes, computers, telecom equipment, and consulting services. It was a place that had cheap, well-educated engineers.

Y2K, offshoring, and the IT services boom did what no amount of diplomacy had managed. They created a dense mesh of everyday connections. Indian engineers in US suburbs. US customers on the other end of a phone line in Bangalore. Companies with more Indians in their org chart than some Indian PSUs.

Even the nuclear argument began to bend. Pokhran-II in 1998 triggered another round of US sanctions, but this time they did not last. By 2000, President Clinton was in India and people were already talking about “warmed ties” instead of “estrangement”. ³⁴

The nuclear deal and the strategic turn

The real political signal came in the mid-2000s.

Between 2005 and 2008, India and the US negotiated and passed the civil nuclear agreement. India separated its civilian and military nuclear facilities, accepted IAEA safeguards on the civilian side, and in return the US worked to tear down a three-decade-old moratorium on nuclear trade with India. ⁵⁶⁷

You can argue about the exact economic value of that deal for hours. What matters for this story is something else. It told the world that Washington now saw Delhi as a long-term strategic bet, not a charity case to be managed with aid and occasional scolding. ⁶⁸

Around the same time, the US declared India a “Major Defense Partner”. Defense trade went from almost zero to billions. Malabar exercises grew in scope. The Quad slowly crawled out of acronym limbo and acquired ballast. ³⁸

Terrorism, Pakistan, Afghanistan, Iran, Russia – these remained real areas of friction. But the big axis had shifted. The primary shared headache had a different name now: China. ²⁸

Trump, tariffs, and the mini trade war

Then came Trump, and with him, tariffs as a lifestyle choice.

In 2018, the US used the “national security” provision to slap tariffs of 25 percent on steel and 10 percent on aluminium from a long list of countries, India included. Those duties hit hundreds of millions of dollars’ worth of Indian exports, a couple of percentage points of what India sold to the US. ⁹¹⁰

In 2019, Washington went a step further and yanked away India’s GSP status – the preferential trade program that gave duty-free access to a basket of Indian exports. That decision affected more than 6 billion dollars of trade and triggered what economists politely called a “mini trade war”. India retaliated with higher duties on selected US goods. ¹⁰¹¹

Trump’s messaging was blunt and on brand. India was a “tariff king”. The US was being taken for a ride. Tariffs were justice. ⁹

If you lived in the diaspora, you got used to this strange split-screen. On one side, “Howdy Modi” in Houston and “Namaste Trump” in Ahmedabad – full stadiums, warm hugs, and talk of “natural allies”. On the other side, steel tariffs, GSP removal, and a constant drumbeat of trade complaints.

What held through that turbulence was the strategic layer. Defense cooperation deepened. Intelligence sharing increased. The Indo-Pacific became a more explicit frame. The two militaries worked together more. The Chinese PLA’s behaviour on the LAC made sure of that. ²⁸

After Trump’s tariffs: less romance, more plumbing

Changing presidents did not magically reset the economics.

Under Biden, some of the sharp edges were filed down. Trade talks restarted. There was more predictable messaging. The tone softened. But the age of painless access to the US market was clearly over. Tariffs and “national security” in trade policy are now a permanent part of the furniture. ⁹¹⁰

At the same time, the strategic and technological embrace accelerated.

In 2023, Modi’s state visit to Washington produced an unusually dense joint statement. It covered everything from clean energy to space, from AI to critical minerals. The two sides pushed the Initiative on Critical and Emerging Technology (iCET), agreed on deeper cooperation in 5G and 6G, advanced chip partnerships, and moved forward on co-production of jet engines and other defence technologies. ^12131415

Trade numbers quietly told the same story. The US emerged as India’s largest trading partner in goods, while India climbed into the top tier of US trading relationships. Services, digital trade, and investment deepened the connection further. ¹⁰¹¹

Yet the tariff saga did not die. It mutated.

In 2025, Washington expanded its use of steel and aluminium tariffs again, doubling duties in the name of national security. New orders raised headline rates and widened the coverage. ¹⁶¹⁷

Delhi responded by formally notifying the WTO that it was considering retaliatory duties on a fresh list of US products, as a suspension of earlier concessions. The filing put the potential impact at about 7.6 billion dollars of Indian exports. ¹⁸¹⁹

The situation further deteriorated when US imposed 25% ban on Indian goods in August with additional 25% soon after, citing New Delhi’s continued imports of Russian oil as the trade talks between the two nation resulted in a “no deal”.²⁰²¹

The hugs are still there. So are the tariff notices.

So where are we, really?

If you zoom out from the daily noise, the India–US story can be read in three large movements.

First, the moral and ideological phase. Non-alignment, nuclear lectures, food aid, sanctions, righteous speeches from both sides.

Second, the economic and technological phase. Liberalisation, IT services, diaspora, the nuclear deal, defense cooperation, the Indo-Pacific, the Quad.

Third, the current messy phase. High strategic convergence, thick economic interdependence, and a running gunfight over tariffs, data, digital rules, visas, and domestic politics in both countries. ²⁸¹⁰

The centre of gravity has moved from ideology to interest.

India no longer wants to be told whom to buy oil from or what its nuclear doctrine should be. It wants market access, technology transfer, and room to play Russia and the West off each other on its own terms.

The US no longer looks at India primarily through the lens of poverty, non-alignment, or Pakistan. It looks at India as a hedge against China, a market, a talent pool, and a sometimes-difficult partner that still matters a lot more inside Washington than it did thirty years ago. ²⁸¹⁰

Tariffs in this picture are not an aberration. They are a tax on that new intimacy.

When you barely trade and barely cooperate, sanctions and tariffs are symbolic. When you are each other’s top partners in multiple domains, they are friction in the plumbing. They hurt very real businesses and very real workers on both sides, even as the broader relationship keeps moving forward.

My bias, laid bare

I grew up with stories of a distant superpower that alternated between lecturing India and sanctioning it.

I now live in a world where the US is inside Indian lives in a way that would have been hard to imagine in 1974. Phones, apps, films, VCs, H-1Bs, climate finance, chip supply chains, drones, joint statements, Netflix specials. India, in turn, is inside America through its people, its IT systems, its doctors and engineers, and increasingly through its market and its politics.

So when I look at the current tariff regime and whatever its next avatar will be, I see it as part of a longer story, not a breaking-news headline.

The story is simple.

Two large, loud democracies spent decades talking past each other.
Then they discovered they had overlapping interests and compatible fears.
Now they are trying to work together without becoming each other’s client state.

That is not a romance. It is a negotiation.

Tariffs will come and go. Leaders will hug and glare in cycles. There will be real disagreements on Russia, on digital rules, on climate, on human rights.

Underneath all that, the India–US relationship will keep doing what it has been doing for the last thirty years.

Getting denser.
Getting messier.
And, slowly, becoming too important to be left to just diplomats and tariff lawyers.

References

In Java, double feels like a real number. You write 1.0, the compiler nods, the program runs, and everything looks fine. Until it does not.

Take this tiny example:

List values = List.of(
1e16, 1.0, 1.0, 1.0, 1.0
);

double s1 = values.stream().reduce(0.0, Double::sum);
double s2 = values.parallelStream().reduce(0.0, Double::sum);

System.out.println(s1);
System.out.println(s2);