DEV Community: Miguel Shinyenyi

What Becomes True When Both Stay

Miguel Shinyenyi — Tue, 29 Sep 2026 22:54:22 +0000

The curtain of silence

Sapiens describes the evidence for prehistoric life as a Rorschach test. A burial site with
ornaments on a skeleton might mean hierarchy. It might mean something else entirely. A
fracture on an ancient bone might mean violence. It might not. The book calls this its
Curtain of Silence, evidence thin enough that even careful scholarship can't get a clean
answer through it. Scholars keep asking anyway, because the past still shaped what came
after it, but the honest version of that inquiry holds its answers loosely.

That's a claim about archaeology. It turned out to be useful somewhere closer to home.

Two truths instead of one

Dialectical thinking, how my mind works?,
it generates a position and its counter-argument at the same time. Useful when pointed
outward. Corrosive when pointed inward, because the counter-argument doesn't sit next to the
first position, it tries to erase it. Grateful for the past, but it cost me something real,
failing a job interview among the costs. Forgiving someone, but not reconciled with them.
The old move was picking one of those as the real feeling and discarding the other as noise.

The question that actually helps isn't which one is true. Both are. The question is what
becomes true if I stop forcing a choice between them.

A system that already does this

The settlement engine I built has a state called
UNKNOWN. It's not a bug, it's a deliberate third option, used when a payment might have
gone through or might not have, and the system genuinely doesn't have enough information yet
to say which.

// Reused across three different situations: a real gateway failure,
// exhausted retries after a database deadlock, and a hard crash that
// left a settlement stuck with no way to confirm what happened.
settlementTransactions.finalizeSettlement(settlementId,
        new GatewayResult(SettlementOutcome.UNKNOWN, null));

The tempting design is to force an answer immediately: retry until you get a clean yes or no,
because "unknown" feels like a failure to decide. The actual design holds UNKNOWN as a
first-class state, moves on, and lets a separate reconciliation process resolve it later,
once there's real information to resolve it with. Forcing a premature CONFIRMED or FAILED
would be lying to the rest of the system, papering over uncertainty that was still genuinely
open. The honest version of "I don't know yet" turns out to be more useful than a fast, fake
certainty. That's the same shape as forgiving without reconciling. Not every open state needs
collapsing into a resolved one on a deadline. Some of them get resolved later, correctly,
once there's enough to resolve them with. Some of them are just allowed to be two things at
once, permanently, the way gratitude and grief can both be true about the same period without
either one cancelling the other.

Where this gets tested, not just described

I've also been carrying a specific belief:
that my anxiety comes from a need to control everything. It's a real, documented idea in
general, intolerance of uncertainty, anxiety tracking unpredictability rather than actual
danger, controlling behavior as an attempt to shrink that unpredictability back down. But a
documented general pattern isn't the same as a verified account of one specific person, and
right now I don't have an instance attached to it, just the label.

There's a code parallel here too, and it's not a flattering one. The same idempotency work
this week turned up two concurrency races, both caused by the system trying to guarantee
too much certainty upfront.

Two requests, same key, same instant.

Option A: lock everything before
either proceeds. Force certainty
immediately.

Option B: let both proceed. The
database's unique constraint decides
who wins. The loser recovers by
reading the winner's result.

The actual code takes option B. Locking everything upfront to force immediate certainty is
exactly what produces a deadlock later, two transactions each holding what the other one
wants, both stuck, because the system tried to control too much of the outcome up front
instead of accepting a controlled version of not-knowing-yet and resolving it after the
fact. The fix that shipped this week for the crash-recovery gap follows the same shape: not
tighter control at the moment of failure, a sweep that runs later, accepts the outcome was
genuinely unknown for a while, and resolves it once enough time has passed to trust the
answer.

I don't know yet whether "addiction to control" is actually what's driving the anxiety, or
just the label that was closest at hand when I needed one. That's not resolved in this
piece, on purpose. If forcing a system to decide before it has enough information produces a
deadlock, forcing a belief about myself into a tidy answer before I've actually tested it
probably isn't any more reliable. The honest state to hold it in, for now, is UNKNOWN.

What I took from it

Two things can both be true about the same period. Stop asking which one is real.
UNKNOWN is an honest state. A fast, fake certainty is worse than a slow, correct answer.
Forcing certainty upfront is what caused the deadlocks. That applies to beliefs about myself too.
"My anxiety comes from control" stays a hypothesis until a real instance tests it.

Originally published on my site.

Knowing and being able to explain are not the same skill

Miguel Shinyenyi — Tue, 29 Sep 2026 22:53:50 +0000

Two different skills

There's a difference between recognizing the shape of a solution and being able to derive it
without the shape already in front of you. The first is pattern matching. The second is
understanding. Most technical education optimizes for the first, because it's faster to teach
and easier to test.

Where the gap shows

The gap only shows up when someone asks "why does it work that way" instead of "does it work."

What I took from it

Recognizing a solution and deriving it are separate skills, and practicing one doesn't train the other.
"Does it work?" tests recognition. "Why does it work that way?" tests understanding. Ask myself the second one.
A gap that only appears under a specific question is worth testing directly, not assuming.

Originally published on my site.

Claim, Argument, and the Discipline of Not Fooling Yourself

Miguel Shinyenyi — Tue, 29 Sep 2026 22:53:19 +0000

The trap

I did a set of exercises this morning to raise my energy, then showered, because I've learned
I need to feel physically settled before my mind is any good to me. Only afterward, reading a
chapter about hunter-gatherer instincts colliding with modern life, did I have language for
why. The insight came after the action, not before it. That ordering turned out to matter
more than the insight itself.

Here's the trap I nearly walked into. I read a compelling argument, that a mismatch between
old wiring and new environments explains a lot of modern unease, and I started treating it as
settled. Not because the evidence demanded it, but because the writing was good. A well-made
argument and a demonstrated fact produce the same feeling of certainty in a reader. That
feeling is not evidence. It's craft.

The distinction that actually matters

A claim is something shown to be true, checked against reality, falsifiable and unfalsified.
An argument is something made to be believed, structured, sequenced, persuasive by design.
Good nonfiction is full of arguments dressed in the confidence of claims, and the better the
writing, the harder that becomes to notice. The specific idea I was reading, that suppressed
movement contributes to depression, is a real argument worth taking seriously. It is not a
settled account of what causes depression, which research treats as a tangle of contributing
factors, not a single mechanism. Losing that distinction wouldn't just cost me an accurate
view of one book. It's the kind of thing that quietly reshapes how you read your own career
decisions, your own dissatisfaction, your own choices, once a persuasive frame is sitting
unexamined in the back of your head.

There's a second version of the same trap, closer in: I'd summarized what I'd read, in my own
words, and then treated my own summary as if it were a faithful account of the source. It's
entirely possible I misread the chapter. My understanding of an idea and a verified account of
that idea are not the same thing, and conflating them means any misreading I make gets
laundered into something that looks like the author's authority instead of my own.

Where I'd already been doing this right

The clearest working example of separating claim from argument that I have access to isn't
philosophical at all. It's a settlement-engine system I built myself, with Claude Code, and
am now restudying deliberately, not to relearn it from scratch, but to make sure I actually
know it well enough to explain it, in passing or in detail, on demand. That gap, between
having built something and being able to explain it under pressure, is one I've caught in
myself before. This restudy is a direct test of it.

What I found worth studying closely is a documentation habit built into the project itself: a
decisions log that doesn't just record what was decided, it records why, one sentence per
decision, stated plainly enough to be checked. "Foreign key validation failures return 400,
not 404, because the bad ID is client input error, not a missing resource being fetched
directly." That's not a conclusion asserted with confidence. That's a reasoned claim, sitting
next to the reasoning that produced it, inviting disagreement rather than discouraging it.

Compare that to a decisions log that just says "we chose 400." Both read as authoritative if
you don't look closely. Only one of them actually lets you check the reasoning instead of
just trusting the confidence of the person who wrote it. That's the whole trick. Confidence is
cheap. Showing your work is not.

What this looks like day to day

In reading: hold two separate questions for anything persuasive. What is being claimed, and
what is being argued for. Notice which one produced your certainty. If it's the second, the
certainty is borrowed from the writing, not earned from the evidence.

In relationships and self-observation: distinguish what happened from what you concluded it
meant. A single explanation that fits doesn't mean it's the only one, or the right one, it
means it's plausible enough to feel finished. Plausible and finished are not the same
condition.

In code, and in any documentation that describes a system: treat a decisions log entry, a
comment, or a design doc the way you'd treat a persuasive book, with the same two questions.
Does this line state a checkable reason, or does it just assert a conclusion with confidence?
A codebase full of confident assertions with no reasoning attached is tunnel vision waiting to
happen, for whoever reads it next, including the person who wrote it, six months later,
having forgotten why. That's precisely the risk I'm restudying my own system to guard
against, having built it doesn't guarantee I could still explain it cold.

The actual discipline isn't suspicion of everything. It's narrower than that: know which of
your beliefs are standing on demonstrated ground and which are standing on good writing, good
confidence, or your own possibly-mistaken summary of something else. Most of the time you can
hold both kinds of belief at once, loosely, without needing to resolve which is which
immediately. The problem only starts when you stop checking.

No tidy ending

I don't have a tidy ending for this one, and I'm treating that as correct rather than
unfinished. The whole point was to stop mistaking a well-argued position for a demonstrated
one. Reaching a neat conclusion here would be exactly the thing I just spent this piece
arguing against doing.

What I took from it

Certainty from good writing feels the same as certainty from evidence. Check which one I'm standing on.
My own summary of a source is not the source. Mark it as mine.
A decision is only checkable when its reason is written next to it, in code and in life.
Not every belief needs resolving now. The problem starts when I stop checking.

Originally published on my site.

A Mind That Lies to You Too

Miguel Shinyenyi — Tue, 29 Sep 2026 22:52:46 +0000

What sapiens traded time for

Every other species that reached a new environment got there the slow way: fins, blubber, a
nose built as a snorkel, millions of years of the body itself changing to fit the place. When
sapiens reached Australia, the body that arrived was the same one that had walked out of
Africa. No gills, no fur suited to a new climate. What made the crossing possible was a mind
good enough to understand the sea and build something that could cross it, in one lifetime,
not a species-length of them.

That's a real trade, not a free upgrade. Every other animal is capped by what its body allows
it to take from an environment. A mind with a plan has no such cap, and it showed almost
immediately. Sapiens gives the number: 23 of 24 Australian animal species over 50kg were gone
within a few thousand years of that crossing. The local megafauna had never seen anything
like this arrival and had no instinct to fear it. In Africa, animals evolved alongside early
humans for close to two million years and learned caution the slow way. Everywhere sapiens
reached quickly instead, that warning never had time to happen.

The same trade explains something closer to us than a wombat the size of a hippo. Before
sapiens spread, several other human species were alive at the same time, Neanderthals,
Homo erectus, others. Sapiens is the only one left. Whatever let a mind out-hunt giant
kangaroos also let it outcompete or eliminate every other kind of human. The mind that solved
the sea didn't stop at animals.

The same tool turns on you

Here's the part that doesn't stay in the past. A mind capable of outthinking millions of
years of evolution is not automatically trustworthy about itself. The same faculty that plans
a boat also generates a justification for whatever you've already decided, and does it just
as fluently. It doesn't announce which mode it's in. A conclusion produced by looking at
evidence and a conclusion produced by protecting a belief you're attached to feel identical
from the inside.

That's not a flaw sapiens escaped by getting smarter. It's the same trade, still running. A
mind good enough to reshape a continent is also good enough to reshape your own account of
yourself, and it will do that for free, without being asked, unless something is actually
checking it.

A short list for checking it

I've been trying to internalize a set of tools for exactly that, and grouping them, not as
ten separate items but as four jobs:

Catching a thought as it forms, and catching the pattern behind thoughts that keep repeating.
One is metacognition, the other is naming your own bias, and they're the same muscle aimed at
two grain sizes.

A test to apply once something's been caught: what evidence would actually prove this wrong?
If the honest answer is nothing, it's stopped being a belief and become something being
protected instead.

The same discipline aimed at feelings instead of thoughts: a feeling is real, but it isn't
automatically information about the world. "This feels like it will fail" is a fact about
right now, not a fact about the plan.

And a decision-making set for anything aimed outward: every choice costs the other choices
you didn't make, small repeated choices compound into large outcomes over time, and a good
decision can still produce a bad outcome, so judge the decision, not just how it turned out.

I don't know yet whether these four groupings hold up as anything more than a convenient way
to remember ten words. That's not settled here on purpose. It's a framework being tried, not
a conclusion being reported.

One place it got tested this week

The clearest test so far wasn't abstract. I explained the ledger in this system's settlement
engine cold, described it as checked double-entry bookkeeping, the kind where a balance is
provable, not just trusted. Then I looked:

public interface LedgerEntryRepository extends JpaRepository<LedgerEntry, UUID> {
}

Nothing in the actual code ever read those entries back. The check I'd described as already
existing didn't exist. That's falsifiability doing its job in real time, not as a concept I
was reading about but as a belief about my own work that had a real, checkable answer, and
the answer was no. The honest move afterward wasn't to feel bad about being wrong. It was to
notice that the explanation had felt just as confident either way, right or wrong, which is
exactly the warning the concept is supposed to be. Confidence was never the signal. Whether
there was a way to be proven wrong was.

What I took from it

A mind good enough to outthink evolution isn't automatically trustworthy about itself. That's the same trade, not a different one.
Confidence in an explanation isn't evidence for it. Whether it could be proven wrong is.
The four groupings are a framework being tested, not a conclusion. One real test this week went the way the framework predicts; that's one data point, not a pattern yet.

Originally published on my site.

The Outbox Held, the Ledger Didn't

Miguel Shinyenyi — Tue, 29 Sep 2026 22:42:43 +0000

Explain it cold, then check

Same method as idempotency: explain the mechanism from memory, then check it against the
actual code, not the other way around. The point isn't to be right on the first try. It's
that a claim about your own system should be falsifiable. If I can't say what I'd expect to
find in the code that would prove my explanation wrong, I'm not really explaining it, I'm
just repeating a shape that sounds right.

Two subsystems, two different results. The outbox explanation held up once checked. The
ledger explanation didn't, not because the mechanism I described was wrong, but because the
part of it I assumed existed simply wasn't built yet.

What the outbox is actually for

The instinct is to describe it as a receipt: proof you sent something, so you can resend it
if it doesn't land. That's close, but backward. The real problem is that a database commit
and a message published to Kafka are two separate systems, and you can't make them one atomic
operation. Publish first, then save to the database, and a crash in between means you told
the world something happened that your own database never recorded. Save first, then
publish, and a crash in between means your database says it happened but nobody downstream
ever hears about it. Either order leaves a gap where the two systems can disagree.

The fix is to make the event write local, so it can share a transaction with the fact it's
describing:

@Transactional
public SettlementExecutionRequest createPendingSettlement(...) {
    ...
    settlementRepository.save(settlement);

    outboxWriter.write(AGGREGATE_TYPE_SETTLEMENT, settlementId, KafkaTopics.SETTLEMENT_REQUESTED,
            new SettlementRequestedEvent(settlementId, source.getId(), destination.getId(),
                    command.amount(), command.currency(), Instant.now()));
    ...
}

Same transaction, same database. The settlement and the event to announce it commit together
or not at all. A separate process then polls for unpublished rows and sends them on, only
marking a row done once the broker actually confirms it:

kafkaTemplate.send(event.getTopic(), event.getAggregateId().toString(), event.getPayload()).get();
event.markPublished();

If that send fails, the row just sits there, unpublished, and gets tried again next poll.
What this buys isn't proof after the fact. It's a guarantee that the event and the thing it
describes can never come apart: if the settlement never happened, no event exists to send. If
it did happen, the event goes out eventually, whatever crashes in between.

What double-entry is supposed to guarantee, and what wasn't there

Double-entry means every transaction writes two sides, a debit somewhere and a credit
somewhere else, and across any transaction the two must net to zero. The point of doing it
this way is that a balance stops being something you just trust. It becomes something you can
prove, by summing the entries that produced it.

The code writes both sides correctly:

source.debit(settlement.getAmount());
destination.credit(settlement.getAmount());
ledgerEntryRepository.save(new LedgerEntry(UUID.randomUUID(), settlementId, source.getId(),
        EntryType.DEBIT, settlement.getAmount()));
ledgerEntryRepository.save(new LedgerEntry(UUID.randomUUID(), settlementId, destination.getId(),
        EntryType.CREDIT, settlement.getAmount()));

But balance is also a stored column, mutated directly by debit()/credit() in that same
method. And this is the whole repository interface for the entries just written:

public interface LedgerEntryRepository extends JpaRepository<LedgerEntry, UUID> {
}

No query beyond what comes free. Nothing anywhere sums those entries back and checks them
against the balance. The entries were being written correctly and never read. A ledger that
nobody checks isn't really double-entry, it's an audit trail sitting next to a number
everyone just trusts.

Deciding what happens when it's wrong

Finding the gap is the easy part. The harder question is what a mismatch should actually do
once the system can see one.

The tempting answer is to auto-correct: recompute the balance from the entries and overwrite
it. That's the wrong incentive to build into the system. A mismatch means you don't yet know
which number is wrong, the stored balance or an entry. Auto-fixing assumes an answer you
don't have, and it means a real bug gets silently absorbed instead of surfaced, which is
exactly how a system keeps producing the same kind of failure: nothing about the mismatch
ever reaches whoever could actually fix the cause. docs/reconciliation.md already states
this as policy for a different case, mismatches with an external gateway: manual review by
default, no silent auto-resolution. That's not a rule specific to talking to a bank. It's the
right rule for any internal disagreement a system can detect but can't safely resolve on its
own, so it's now written that way, a general rule with two implementations rather than one
rule that only happens to apply once.

The fix: every account gets an opening entry so its balance always equals the sum of its own
history, and a check runs on every read. On a disagreement, it records the mismatch, once,
durably, and still refuses to hand back a number it doesn't trust:

public void verify(LedgerAccount account) {
    BigDecimal computed = ledgerEntryRepository.sumNetByAccountId(account.getId());
    BigDecimal stored = account.getBalance();
    if (stored.compareTo(computed) == 0) {
        return;
    }
    if (ledgerMismatchRepository.findByAccountIdAndResolutionStatus(account.getId(), OPEN).isEmpty()) {
        ledgerMismatchRepository.save(new LedgerMismatch(...));
    }
    throw new LedgerInconsistencyException(account.getId(), stored, computed);
}

Resolving that record later never touches the balance either. It records that a human looked
at it and made a decision, the same as the existing gateway-mismatch workflow. Verified
against real data before calling it done: forty-six settlements moved through the actual API,
every untouched account's backfilled history matched its original balance exactly, and one
account whose balance was hand-edited to disagree with its own history was caught,
flagged, and resolved without its balance being touched by the fix itself.

What I took from it

A claim about your own system should be falsifiable. If nothing in the code could prove it wrong, it isn't really an explanation.
The outbox isn't proof you sent something. It's a guarantee that an event and the fact it describes can never come apart.
Entries that are only ever written and never read aren't a checked ledger, whatever they're called.
When a system finds its own mistake, the honest move is to record it and ask, not to quietly fix it and move on.

Originally published on my site.

Idempotency keys, under load

Miguel Shinyenyi — Tue, 29 Sep 2026 22:42:41 +0000

The textbook version

An idempotency key is a client-generated identifier attached to a request, so that if the
same request arrives twice, the server recognizes it and returns the original result instead
of processing it again. That's the textbook version. The real version, the one that shows up
once you put a system under actual concurrent load, has two more layers to it.

The guarantee is "answer it correctly"

The guarantee isn't "block the duplicate," it's "answer it correctly." A retry of an
in-flight request gets told the process is underway. A retry of a finished request gets
back the exact same result the first one got, replayed from a stored snapshot, not a fresh
answer. That second case is the actual point. A caller retrying after a timeout isn't told
"processing," they're told what genuinely happened.

Here's the check, in the real code:

Optional<IdempotencyKey> existing = settlementTransactions.findExisting(idempotencyKey);
if (existing.isPresent()) {
    return handleExisting(existing.get(), requestHash);
}
try {
    executionRequest = settlementTransactions.createPendingSettlement(idempotencyKey, requestHash, command);
} catch (DataAccessException raceLost) {
    IdempotencyKey winner = settlementTransactions.findExisting(idempotencyKey)
            .orElseThrow(() -> raceLost);
    return handleExisting(winner, requestHash);
}

Race one: same key, same instant

Check-then-write always
has a gap. Two requests can both see nothing during findExisting, before either has
written anything. Rather than closing that gap with an upfront lock, the code lets both
proceed, and leans on a database-level unique constraint to guarantee only one insert
survives. The other throws, and gets recovered by re-reading whoever won.

What's not obvious from reading the code: that failure doesn't always look the same. Under
Postgres, the identical race sometimes surfaces as a clean unique-constraint violation, and
sometimes as an outright deadlock between the two competing index insertions, depending on
timing. That's not something you'd predict from the schema. It's something you'd only find
by actually running concurrent load against it and watching what comes back.

t1  A      findExisting(key) -> empty
t1  B      findExisting(key) -> empty
t2  A      INSERT idempotency_keys
t2  B      INSERT idempotency_keys
t3  DB     unique constraint on key:
           only one INSERT wins
t3  loser  fails as EITHER
           - a unique-violation, or
           - a deadlock
             (CannotAcquireLock)
           depending on index timing
t4  loser  catch(DataAccessException)
           -> findExisting(key)
           -> return winner's result

Race two: the winner deadlocks

Race two is a different race, on the winner. The losing threads above, in their own
doomed transactions, are inserting into settlements, which has a foreign key back to
idempotency_keys. Validating that foreign key takes a shared lock on the referenced row.
If those losing transactions haven't rolled back yet when the winner tries to UPDATE that
same row to mark it complete, the update deadlocks against locks held for an unrelated
reason.

1  Winner  createPendingSettlement()
           commits
2  Loser   INSERT INTO settlements
           (FK -> idempotency_keys)
           takes a shared lock on
           that row
3  Loser   rolling back, lock still
           held
4  Winner  finalizeSettlement():
           UPDATE idempotency_keys
           SET status = COMPLETED
           -> blocked on that lock
5  DB      detects deadlock,
           aborts the UPDATE
6  Winner  catches
           TransientDataAccessException
           retries finalizeSettlement
           only (already PENDING;
           rerunning the whole flow
           would see its own key as
           a conflict)
7  Loser   rollback completes,
           lock released
8  Winner  retry succeeds

Five bounded retries, short backoff. If all five are exhausted, still under heavy
contention, the system doesn't leave the settlement stuck. It falls back to a second,
independent retry budget that finalizes the settlement as UNKNOWN, the same "we genuinely
don't know, let reconciliation resolve it later" state used when the external call itself
fails outright. Both concurrency behaviors were found by actually running load and chaos
tests against the system, not by design review.

A third failure mode: the crash

This one was found by studying the first two closely enough to explain them. Neither race above covers what happens if the process hard-crashes between the two
transactions entirely, after the settlement is written as PENDING but before it's ever
finalized. No thread survives to catch anything in that case, and the settlement has no
external reference yet, since that's only set during finalization, which made it invisible
to reconciliation's own query. The idempotency key would stay IN_PROGRESS indefinitely,
409-ing every retry, forever. That was a real, verified gap, confirmed against the actual
repository before writing it down here, not assumed.

It's fixed now. A scheduled sweep, StalePendingSettlementSweepService, runs the same way
reconciliation already does: it finds settlements stuck PENDING with no external reference
past a grace period (300 seconds by default), and finalizes each one as UNKNOWN, reusing
the exact same "we don't know, reconciliation resolves it later" path the two races above
already fall back to. No new state-machine logic, just the same escape hatch applied to a
case that previously had no path to it at all. Covered by its own unit and integration
tests, the way everything else in this system is.

The interesting part was never the key itself. It's every place where "the same request
happening twice" turns out to have more than one way of actually happening, and every place
"finished" turns out to have more than one way of actually finishing.

What I took from it

An idempotency key's job is to answer a retry correctly, not just to block it.
Let the database's unique constraint decide the race instead of locking upfront.
The same race can fail two different ways. Only real concurrent load showed that.
Every path needs an exit to UNKNOWN, including a crash nobody survives to catch.

Originally published on my site.