XML Tagging in Prompts: The Secret to Getting Better Output from Claude and GPT

A simple structuring trick that turns messy, unpredictable LLM outputs into clean, reliable ones.

If you've spent any time writing prompts for Claude, GPT, or any other large language model, you've probably hit this wall: your prompt works fine for a simple ask, but the moment you pack in multiple instructions — some context, a few examples, formatting rules, and the actual task — the model starts mixing things up. It answers the wrong part of the question. It ignores your formatting instructions. It treats your example output as part of the actual task.

The fix is almost embarrassingly simple: wrap your prompt sections in XML tags.

Why XML Tags Work So Well

LLMs are trained on enormous amounts of code, documentation, and markup. XML (and HTML) syntax is deeply embedded in that training data, which means models are very good at recognizing where one tagged section ends and another begins. Unlike plain paragraphs — where the boundary between "here's my context" and "here's my instruction" is fuzzy — a tag creates an unambiguous boundary.

Anthropic actually recommends this explicitly for Claude: wrapping distinct parts of a prompt (instructions, context, examples, output format) in tags like <instructions>, <context>, <example>, and <output_format> measurably improves consistency, especially in longer or more complex prompts.

Think of it like the difference between handing someone a wall of text versus handing them a form with labeled fields. Both contain the same information, but one is far easier to parse correctly — for a human, and for a model.

A Before-and-After Example

Without tags:

Summarize the article below in 3 bullet points. Keep it under 50 words.
Use a neutral tone. Here's an example of the style I want:
"- Company X raised $10M in Series A funding."
Now here's the article: [long article text]

The model has to guess where the instructions end and the article begins — and with a long article, it sometimes starts summarizing the example instead of the real content.

With tags:

<instructions>
Summarize the article in 3 bullet points, under 50 words total.
Use a neutral tone.
</instructions>

<example_style>
- Company X raised $10M in Series A funding.
</example_style>

<article>
[long article text]
</article>

Now there's zero ambiguity. The model knows exactly what's an instruction, what's a style reference, and what's the raw content to work on.

Common Tags Worth Using

You don't need a formal schema — these are just semantic containers the model can recognize. Some of the most useful:

• <instructions> — the actual task
• <context> — background info the model needs but shouldn't act on directly
• <example> / <examples> — sample inputs/outputs (few-shot prompting)
• <document> or <article> — source text to analyze/transform
• <output_format> — exactly how you want the response structured
• <thinking> — for models that support step-by-step reasoning before the final answer

You can also nest them, e.g., multiple <document index="1">, <document index="2"> blocks when feeding several sources at once — attributes work too, and models parse them correctly.

Bonus: Ask for Tagged Output Too

This trick isn't just for input — you can ask the model to return its answer in tags, which makes parsing the response programmatically trivial:

<answer>
Your final response here.
</answer>
<confidence>high</confidence>

If you're building this into an app (say, a Next.js API route calling the AI SDK), this turns a fragile "hope the model formats it right" problem into a simple string-extraction problem — no need for a full JSON schema when you just need one or two fields.

When Not to Bother

For a single, simple instruction ("Translate this to French"), tags are overkill — they add noise for no benefit. Reach for XML tagging when your prompt has multiple distinct components that could be confused with each other: instructions + context + examples + a document to process, all in one message.

Takeaway

XML tagging isn't a hack — it's closer to good API design applied to prompts. You're giving the model an explicit contract instead of hoping it infers your intent from prose. The next time a prompt feels like it's "almost working," try wrapping its parts in tags before you start rewriting the wording. Often, structure — not phrasing — was the actual problem.

I wanted to learn cloud security the way it actually sticks: by building something real. So I built PostureGuard, a web application that scans a domain and returns a security posture report covering TLS, HTTP security headers and open ports, with a 0-100 score and an A-F grade. This post walks through the architecture and the decisions I found most interesting.

Update: Phase 1 is done. PostureGuard now runs on Azure Container Apps and is live at app.samdossou.com. The write-up is the next post in this series.

The shape of the system

PostureGuard has three moving parts:

• A Next.js web app (App Router, TypeScript) where users sign up, add a domain, and request scans.
• A PostgreSQL database that stores users, domains and scans.
• A Python worker that runs the actual scans in the background.

The web app never runs a scan itself. When a user clicks "Scan", the app just inserts a row into a scans table with the status queued and returns immediately. The worker picks the job up a moment later. This keeps the request fast and the two halves of the system decoupled.

Using PostgreSQL as a job queue

The part I like most is that there is no separate message broker. The scans table doubles as the queue. The worker claims one job at a time with a single query:

SELECT s.id, d.name
FROM scans s JOIN domains d ON d.id = s.domain_id
WHERE s.status = 'queued'
ORDER BY s.requested_at
FOR UPDATE OF s SKIP LOCKED
LIMIT 1

FOR UPDATE locks the row so no one else can grab it, and SKIP LOCKED tells other workers to ignore locked rows and move on to the next job. That means I can run several workers in parallel and they will never process the same scan twice, without any extra infrastructure. For a project at this scale, a table plus SKIP LOCKED is simpler and more than enough.

The scanners

The worker runs three checks, all built on the Python standard library to keep dependencies light:

• TLS: it opens a TLS connection, reads the certificate expiry and the negotiated protocol version, and flags expired certs or outdated TLS.
• HTTP headers: it fetches the site and checks for the security headers that matter (HSTS, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy).
• Ports: it attempts TCP connections to a list of common ports and flags sensitive ones like Telnet, RDP or an exposed database.

Each check returns findings tagged with a severity. The score starts at 100 and loses points per finding based on severity, then maps to a grade. Because the scoring is pure logic with no I/O, I pulled it into its own module and covered it with unit tests.

Only scan what you own

A domain scanner is one if statement away from being an attack tool, so ownership matters. Before a domain can be scanned, the user has to prove they control it by adding a DNS TXT record containing a unique token I generate for them. The verification step does a live DNS lookup and only marks the domain verified if the token is present. Since only the domain owner can edit DNS records, this is a clean proof of control.

Authentication done simply

Auth is email and password. Passwords are hashed with bcrypt and only the hash is stored. Sessions live server-side in the database; the browser only holds an opaque session id in an httpOnly cookie, so it is not reachable from JavaScript. Nothing fancy, but the fundamentals are right.

Running it like production

To get a feel for operations, I did not just run the worker in a terminal. I turned it into a systemd service so it starts on boot and restarts if it crashes, with its logs captured by journald. A bash script dumps and compresses the database, keeps the last seven backups, and a systemd timer runs it every night. After a full machine restart, the worker came back on its own and the backup fired overnight without me touching anything.

One small gotcha worth noting: under systemd, Python buffers stdout, so my log lines never reached journald until I forced unbuffered output. A classic first surprise when you move a script into a service.

What is next

This is Phase 0, the local MVP. From here the plan is to deploy it to Azure, then AWS, refactor the infrastructure to Terraform, run it on Kubernetes, wrap it in a DevSecOps pipeline, and wire it into a SOC with Microsoft Sentinel. Each step adds a layer, and each layer is a chance to learn a piece of cloud security by building instead of just reading about it.

The code is on GitHub: https://github.com/Dkls7777/postureguard

If you are learning cloud security too, I would recommend the same approach: pick one project and take it deep.

You've paginated through a big result set before. Page 2 loads fine. Page 200 takes a beat. Nobody stops to ask why — until something like this shows up instead of a slow page:

{
  "message": "Only the first 1000 search results are available.",
  "documentation_url": "https://docs.github.com/v3/search/",
  "status": "422"
}

That's GitHub's own search API. Ask it for page 9 or page 10 of a search and you get real results. Ask for page 11 and you get that, on purpose, every time.

I went and looked at why. Full video below, written breakdown after it for anyone who'd rather read.

Reproducing it

Not a guess — this is live, right now:

curl "https://api.github.com/search/repositories?q=javascript&page=9&per_page=100"
# -> real results

curl "https://api.github.com/search/repositories?q=javascript&page=10&per_page=100"
# -> real results

curl "https://api.github.com/search/repositories?q=javascript&page=11&per_page=100"
# -> 422, the message above

GitHub documents this cap directly — it's not rate limiting, and it's not a bug that slipped through. Once you understand the mechanism it's protecting against, the same wall shows up in a lot of places that don't bother telling you about it — including, probably, a table you've built yourself.

The query behind the page number

Most pagination UIs turn a page number into something like this:

SELECT * FROM videos
ORDER BY id
LIMIT 20 OFFSET 999980;

Twenty rows per page, page 50,000 requested — that's an offset of nearly a million. It's easy to assume the database can jump straight to row 999,980. It can't, and the reason is in how the underlying index is built, not in anything about this specific query.

What an index actually is

A sorted column is backed by a B-tree — a structure built for one thing: walking rows in order, fast. The leaf level is a chain of rows in sorted sequence. That chain is what makes ORDER BY cheap.

It is also the whole problem. There's no operation in a B-tree for "give me whatever's at position 999,980." Only for "give me whatever's next after this value." Position and value are not the same axis, and only one of them has a shortcut.

So OFFSET 999980 does the only thing it can: start at the beginning of the scan, count a row, discard it, count the next, discard it — one at a time, nearly a million times — before it starts collecting the 20 rows you actually asked for.

Cost = O(offset), not O(page size). Page 10 is nearly free. Page 50,000 means walking and throwing away roughly a million rows just to reach the part you wanted.

What actually happens, measured

Theory's cheap. Here's a real table — 5 million rows, local Postgres:

docker run --name pagination-demo -e POSTGRES_PASSWORD=demo -p 5432:5432 -d postgres:16
docker exec -it pagination-demo psql -U postgres

CREATE TABLE videos (
  id BIGINT PRIMARY KEY,
  title TEXT,
  created_at TIMESTAMP
);

INSERT INTO videos (id, title, created_at)
SELECT g, 'Video ' || g, NOW() - (random() * interval '3 years')
FROM generate_series(1, 5000000) AS g;

EXPLAIN ANALYZE
SELECT * FROM videos
ORDER BY id
LIMIT 20 OFFSET 999980;

Limit  (cost=33323.00..33323.67 rows=20 width=29) (actual time=121.583..121.586 rows=20 loops=1)
  ->  Index Scan using videos_pkey on videos  (cost=0.43..166616.30 rows=4999991 width=29)
        (actual time=0.012..94.512 rows=1000000 loops=1)
Planning Time: 0.201 ms
Execution Time: 121.603 ms

rows=1000000 on the scan node isn't an estimate — that's the actual count the engine walked through before it could return anything, exactly matching the mechanism above.

The fix everyone reaches for, and what it actually does

The usual advice is "use cursor pagination instead of OFFSET." Here's the query that advice produces:

EXPLAIN ANALYZE
SELECT * FROM videos
WHERE id < 845923
ORDER BY id DESC
LIMIT 20;

Limit  (cost=0.43..1.15 rows=20 width=29) (actual time=0.477..0.484 rows=20 loops=1)
  ->  Index Scan Backward using videos_pkey on videos  (cost=0.43..30516.09 rows=851752 width=29)
        (actual time=0.475..0.480 rows=20 loops=1)
        Index Cond: (id < 845923)
Planning Time: 0.129 ms
Execution Time: 0.503 ms

Same table. Same 20 rows back. 121.603 ms → 0.503 ms — roughly 242x, and it's not a rounding error, it's a different cost curve entirely.

What changed underneath: instead of walking the leaf chain from the start, the engine descends the tree directly — root, branch, leaf — to id = 845923, then reads 20 rows backward from there. A seek, not a scan. That's the entire mechanism. Nothing about the table changed, nothing about the index changed — only the shape of the question changed, from "what's at position N" to "what comes after this value."

This is also why Instagram says "load more" and X says "load older posts" instead of showing page numbers. Under the hood, that's a cursor — after=<id> — not a position.

Where this breaks silently

Keyset pagination only holds up if the sort key is unique and strictly ordered — a primary key like id qualifies. The moment you sort by something that can repeat, like created_at, where two rows can land on the exact same millisecond, a single-column cursor can silently skip a row or hand back a duplicate. Nothing errors. It just quietly returns the wrong set.

The fix is comparing a pair of columns, not one:

SELECT * FROM videos
WHERE (created_at, id) < (:last_created_at, :last_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;

That line is the gap between "works in the demo" and "works in production."

What to check before you reach for either

In order:

1. Does the page number itself need to exist? If users are scrolling a feed, not jumping to "page 4,721," you don't need OFFSET's random access at all — cursor pagination is strictly better here, no tradeoff to weigh.
2. Do you actually need random access? Admin dashboards, audit tools, support panels — anywhere someone legitimately needs "go to page 42" — OFFSET's random access is the feature, not the bug, and the fix is usually capping how deep it's allowed to go rather than replacing it outright.
3. If you're building a public API, assume someone will request the deepest possible page. Elasticsearch refuses to paginate past 10,000 results by default and points you at search_after instead — the same fix GitHub ships, in a different system. Capping the depth is cheaper than absorbing the cost of someone finding it by accident.

Not a universal fix

OFFSET isn't wrong. It's the right tool when random access matters more than depth — small tables, internal tools, anywhere nobody's going past page 20 anyway. Cursor pagination isn't strictly "better," it trades away the ability to jump anywhere for a flat cost curve at any depth. The mistake isn't picking one — it's not knowing there's a choice, and finding out which one you picked at the exact moment your table crosses a few million rows.

If this was useful, the video walks through the same benchmark live — GitHub's actual API response, the terminal running both queries against the same 5M-row table, EXPLAIN ANALYZE output as it prints. Drop a comment if you want the follow-up on why COUNT(*) gets slow on the exact same kind of table — different query, same root cause.

A comment can be marked done without changing Word text

Text comparison is necessary for document review, but it is not sufficient for every stored WordprocessingML change. A document can retain its visible text, comment anchor, ordinary comment content, relationships, and package member set while a persisted comment state changes elsewhere in the package.

Document Change Assurance Benchmark (DCAB) 0.12.0 adds a small, deterministic case for exactly that boundary: review.modern_comment_done_state_changed.

Both packages hold fixed:

• the classic comment and its document range start/end/reference anchor;
• the matching paragraph identifier and internal package relationships;
• content-type declarations, package members, and every stored w:t value.

Only word/commentsExtended.xml changes. Its sole Office 2013 w15:commentEx record moves from explicit done="0" to done="1".

Why this belongs in static review

Microsoft describes the commentsExtended part as carrying additional information about comments represented in the classic comments part. Its w15:commentEx schema reference says the construct is available in Office 2013 and later, associates paraId with the comment's final paragraph, and defines done="1" as a user indication that the associated comment is done.

That makes the stored metadata reviewable. It does not make it a safe basis for overclaiming. The fixture does not open Word, render or update comments, resolve a thread, authenticate a person, communicate with a service, or assert a particular client UI or workflow behavior. It tests one direct package-data boundary.

A target-free, reproducible contract

The public truth file says only that the stored done state changed and that the reference disposition is review. It excludes fixture-specific comment text, author metadata, paragraph identifiers, relationship paths, and raw serialization details.

DCAB's structural verifier checks the package topology and the exact one-member delta. Its independent python-docx check opens all 44 .docx fixtures and its OPC reader opens all 46 packages. The optional DocFence 0.27 adapter observes only aggregate inventory evidence: one classic comment, one extension record, and a resolved-comment count moving from zero to one, while people, thread, reaction, comments-ID, and extensible-comment counts remain zero.

The 0.12.0 release passed hosted Python 3.11–3.13 CI, a clean DocFence adapter install, fresh wheel and source-distribution validation, and a fresh Hugging Face dataset download.

Try it

python -m pip install https://github.com/SybilGambleyyu/document-change-benchmark/releases/download/v0.12.0/document_change_benchmark-0.12.0-py3-none-any.whl
dcab validate
dcab docfence-observations --executable docfence --output observations.json
dcab score --observations observations.json --strict

The benchmark now contains 23 paired synthetic cases and remains on fixture schema version 1. You can find the release artifacts and full static-scope contract on GitHub, and the corpus is mirrored on Hugging Face.

I built elm.chat around a narrow idea: a conversation should not automatically become a permanent server-side asset.

It is not a replacement for a contact network or a claim that metadata can disappear. It is a disposable room for one live conversation. The interesting engineering question was how to make that room reliable without giving the server a readable or persistent transcript.

The current answer is:

• React and Web Crypto in the browser
• one Cloudflare Worker for the app and API
• one Durable Object per room
• one WebSocket per participant
• encrypted content relayed, but not persisted, by the Durable Object

The complete project is AGPL-3.0 source.

One coordination boundary per room

A room is a natural Durable Object boundary. One object owns:

• room policy and lifecycle
• participant presence
• creator capabilities
• single-use invite state
• WebSocket relay
• expiry and destruction

The Worker creates room metadata, addresses the object by room ID, and routes subsequent API and WebSocket traffic to it.

The object stores the room policy, status, creator token, and invite records. It does not store message envelopes, encrypted file chunks, or a transcript.

That distinction matters. “Encrypted at rest” would still make the server a durable archive. elm.chat instead asks currently connected clients to hold the conversation in memory.

The room secret stays in the fragment

Room creation starts in the browser:

1. Generate a random 256-bit room secret.
2. Create room metadata through the Worker.
3. Navigate to /c/:roomId#<room_secret>.
4. Derive the room key locally with HKDF-SHA-256.

The fragment is not included in normal HTTP requests, so the Worker receives the room ID but not the room secret. A strict Referrer-Policy: no-referrer reduces accidental capability leakage to other origins.

The browser uses the derived AES-GCM-256 key for message and file content:

• each message gets a fresh random 96-bit nonce
• files are divided into 64 KiB chunks
• each file chunk is encrypted independently

The relay receives ciphertext envelopes and routing information, not plaintext.

One WebSocket carries the live room

After joining, a client uses one WebSocket for:

• presence
• encrypted messages
• encrypted file chunks
• transcript-sync requests and responses
• participant removal
• destruction events
• keepalive traffic

WebSocket attachments are the source of truth for live membership. They survive Durable Object hibernation, so the object can wake and continue targeted routing without relying on a process-local participant map.

When a new participant joins, the server does not load a transcript. The client requests one from peers that are already connected. A peer sends its current encrypted history through the relay, with a hard cap on the number of synced messages.

If nobody connected still has an item, it is gone. That is intentional.

Why I did not use direct WebRTC

Peer-to-peer sounds like the obvious privacy choice, but the transport tradeoff is more complicated.

Direct WebRTC ICE negotiation can reveal participant IP addresses to other people in the room. Connectivity can also fail on mobile carriers, symmetric NAT, and restrictive networks unless the application adds a TURN relay.

I chose a Durable Object relay because:

• room members never connect directly
• participants do not learn one another’s IP addresses
• the same transport works across restrictive networks
• there is no separate STUN/TURN service to operate

This does not eliminate metadata.

Cloudflare still sees each connection’s IP address, timing, sizes, and presence. An observer can infer activity bursts even without decrypting content. The architecture moves content trust away from the server while accepting that the relay remains a metadata observer.

That is the actual claim—not “no trace.”

One-time membership

The room creator holds a creator capability in local browser storage and can:

• issue single-use invites
• revoke invites
• remove participants
• destroy the room

A non-creator needs a valid invite to join. The invite is consumed by the first new session that uses it. That same session can reconnect after a reload, but another session cannot reuse the link.

This makes an elm.chat URL a handoff for one participant, not a permanent public room address.

What the current design does not solve

End-to-end encryption and ephemerality do not make a system invulnerable.

The current build does not solve:

• screenshots or copied plaintext
• compromised devices or browser extensions
• malicious recipients
• traffic analysis
• denial of service
• strong anonymous routing
• verified human identity
• forward secrecy beyond the shared room key

The clients generate ephemeral identity keys, but those keys are not yet used to authenticate messages. Replay and duplicate protection are also unfinished. The project has also not had an independent security audit.

Those are not footnotes. They define where the current system should and should not be trusted.

Run it or review it

The repository includes:

• the architecture
• the threat model
• a one-click Cloudflare deployment path
• manual Wrangler deployment instructions
• contributor guidance and scoped issues

You can try the live room, inspect the source, or read the current security status and limitations.

The feedback I am most interested in is on:

1. the encrypted-relay versus WebRTC tradeoff
2. one Durable Object per room as the coordination boundary
3. client-supplied transcript sync after object hibernation
4. the message-authentication path that should come next

If you find a security issue, please use the repository’s private reporting instructions rather than publishing an exploitable detail.

Some developers treat Claude like autocomplete: paste some code, get some code back, iterate blindly. The gap between a mediocre response and a genuinely great one usually isn't the model — it's how you're prompting it. Here are six concrete techniques, each with a real before/after you can use in the API, Claude Code, or claude.ai.

1. Give explicit success criteria, not just a task

Vague prompts get vague code, because Claude has to guess what "done" means — and it'll guess conservatively.

Before: "Write a function to validate emails."

After:

Write a TypeScript function `validateEmail(input: string): boolean`.
Requirements:
- RFC 5322-compatible, but reject addresses without a TLD
- No external dependencies
- Include 3 unit tests covering valid, invalid, and edge cases (e.g. plus-addressing)

Now you get a function that matches your actual constraints instead of a generic regex you have to rewrite anyway.

2. Wrap code and context in XML tags

When a prompt mixes instructions with pasted source, Claude can blur which is which — especially in long files. Tags remove the ambiguity.

<file path="auth/session.ts">
[paste file contents]
</file>

<error>
TypeError: Cannot read properties of undefined (reading 'userId')
</error>

Using only the file above, find the line that causes this error and explain why.

This is also how you should structure multi-file context: one <file> block per file, each labeled with its path.

3. Ask for a plan before code on nontrivial tasks

For anything beyond a one-liner — a new feature, a refactor, a tricky bug — ask Claude to reason through the approach before writing code. This surfaces bad assumptions before they're baked into 200 lines.

Before: "Add caching to this API endpoint."

After: "Before writing code, outline your approach to caching this endpoint: what to cache, invalidation strategy, and where the cache lives. Then implement it."

You catch a wrong assumption ("cache the whole response" when only one field is expensive) at the plan stage, not the PR review stage.

4. Use few-shot examples to lock in your code style

If you want Claude's output to match your codebase's conventions, show it a pattern instead of describing it.

Before: "Write an error handler for this endpoint."

After:

Follow this existing pattern from our codebase:

export const getUser = async (req, res) => {
  try {
    const user = await db.users.find(req.params.id);
    if (!user) return res.status(404).json({ error: 'not_found' });
    return res.json(user);
  } catch (e) {
    return res.status(500).json({ error: 'internal_error' });
  }
};

Now write `getOrder` following the exact same structure and error shape.

One good example saves you a round trip of "actually, use our error format."

5. Chain big tasks instead of one mega-prompt

Asking for an entire feature in one shot tends to produce something shallow or inconsistent. Splitting into stages — plan, implement, review, fix — gets a stronger result because each step has one job.

Before: "Build a rate limiter for our API."

1. "Propose 2-3 rate-limiting strategies for a Node/Redis stack, with tradeoffs."
2. "Implement the sliding-window approach as Express middleware."
3. "Review this middleware for race conditions and edge cases."
4. "Fix the issues you found."

Each step is easy to verify on its own, which is exactly why the end result holds together.

6. Manage context deliberately (especially in Claude Code)

Long agentic sessions degrade when context fills with irrelevant history — a fix for bug A that's still sitting in context while you debug unrelated bug B.

• Fix: run /clear between unrelated tasks in Claude Code instead of continuing the same thread.
• Fix: if you've corrected Claude twice on the same issue and it's still wrong, /clear and write a better initial prompt with what you learned, rather than correcting a third time.
• For instructions that should apply to every session (coding conventions, test commands, directory layout), put them in a CLAUDE.md file instead of repeating them in every prompt.

The takeaway

None of this is a magic prompt template — it's giving Claude the same things you'd give a new teammate: clear requirements, relevant context, your existing patterns, and room to think before acting. Try one of these on your next prompt and see how much less cleanup you have to do afterward.

You've seen this error. npm install fails with ERESOLVE, you search it, find a GitHub issue, copy an overrides snippet into package.json, and the red text disappears on your next run.

Nobody asks what that block actually did.

I hit this exact error yesterday setting up a cloned repo, and instead of moving on once the install went green, I went and looked. Full video below, written breakdown after it for anyone who'd rather read.

The error

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: forced-error-demo@1.0.0
npm error Found: react@19.2.8
npm error node_modules/react
npm error   react@"^19.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^16.9.0 || ^17.0.0" from @testing-library/react-hooks@8.0.1

Two lines in here matter, and they're not making the same kind of claim.

Found: react@19.2.8 — this is just what's already resolved, because it's what my own package.json asked for (^19.0.0).

peer react@"^16.9.0 || ^17.0.0" from @testing-library/react-hooks@8.0.1 — this is a different thing entirely: a peer dependency.

What a peer dependency actually is

Straight from @testing-library/react-hooks's own package.json:

{
  "name": "@testing-library/react-hooks",
  "version": "8.0.1",
  "peerDependencies": {
    "react": "^16.9.0 || ^17.0.0"
  }
}

A peerDependencies entry is a dependency the package needs, but expects the consumer to provide — the package isn't bundling its own copy of React, it's reaching into whatever React is already running in your project, and declaring the only versions it was built to reach into safely.

Compare that to a normal dependencies entry, which npm installs as its own separate copy in node_modules. A peer dependency installs nothing. It just checks.

npm has enforced that check by default since v7. Before that, npm 3 through 6 mostly let mismatches like this through silently — which is exactly why the --legacy-peer-deps flag is named what it is: it tells npm to go back to that old, unchecked behavior.

So this error isn't npm being broken. It's npm accurately reporting that a package in your tree is making a claim about your React version that isn't true.

The fix everyone copy-pastes

Here's the snippet you'll actually find on GitHub issues for this exact situation:

"overrides": {
  "@testing-library/react-hooks": {
    "react": "$react"
  }
}

The $react syntax means "whatever version I already have installed as a direct dependency, use that." So this line says: wherever @testing-library/react-hooks declares a requirement on react — including its peer requirement — force it to match root's react@19.0.0 instead.

Run npm install again. It succeeds. No red text. Looks fixed.

What actually changed (and what didn't)

overrides didn't touch a single line of code inside @testing-library/react-hooks. It didn't check whether that package's internals can actually run against React 19. It went into the resolved dependency graph and rewrote the version number the peer check compares against — from ^16.9.0 || ^17.0.0 to 19.0.0 — so the check has nothing left to disagree with.

That's the entire mechanism. overrides doesn't resolve incompatibility. It rewrites the number two packages are being compared on, whether or not the code underneath agrees.

What did not happen:

• No code inside the overridden package ran
• No check that its React-16/17-era internals still work against React 19's scheduling model
• No test suite executed to confirm any of it

Why the gap matters

@testing-library/react-hooks was built before hook-testing support existed in @testing-library/react itself, and it's effectively frozen at how React 16 and 17 scheduled renders. React 19's internals have moved since then. The override doesn't close that gap — it just moves when you find out about it.

Without the override: you read two lines of log, thirty seconds, and you're acting on real information.

With the override: install succeeds clean, ships to CI, ships to prod — and the actual discovery happens whenever a hook test misbehaves or a render warning shows up with no line in your own code pointing back to it. Same incompatibility, if it's real. Just a much more expensive place to find it.

What to check before you reach for overrides

In order:

1. Does the conflicting package still need to exist? In this case — no. @testing-library/react has supported hook testing natively for a long time now, which makes @testing-library/react-hooks a dependency that's outlived its reason for being. Deleting it is a better fix than patching around it.
2. Can it be upgraded instead? A newer major of the conflicting package may not have this peer conflict at all. You might have to touch your own code too, since not every upgrade is backward-compatible — but that's still cheaper than a silent runtime bug.
3. If it's genuinely unavoidable, scope the override. Don't apply it globally:

// unscoped — forces every package in the tree that touches react
"overrides": {
  "react": "$react"
}

// scoped — forces it only where the actual conflict is
"overrides": {
  "@testing-library/react-hooks": {
    "react": "$react"
  }
}

Everything else in your tree keeps the version npm originally resolved. Smaller blast radius, easier to reason about, easier to remove later.

A temporary patch. Not permanent config.

If you do add an override, treat it like debt, not like settings. Leave a note on why it's there — package.json doesn't support comments, so put it in a README or an OVERRIDES.md: what it's patching, when to revisit it, who added it. Put it on your dependency-audit schedule, whatever that already is for your team, and pull it out the moment the upstream package makes it unnecessary.

An override with no expiry date doesn't leave. It just becomes the next person's mystery to reverse-engineer.

If this was useful, the video covers the same ground with the terminal running live — installing with and without the override, reading the actual npm ls output, watching what changes. Drop a comment if you want the follow-up on npm's resolution algorithm itself — why these conflicts happen before any override enters the picture.

Is writing code with an agent the same thing as pair programming?

That question has been going around lately, and there's a practical consequence sitting inside it that I don't see many people chasing down.

On a lot of teams, code that a pair of devs wrote gets a lighter code review.

I personally have never seen that written down anywhere. It's not in a policy doc and nobody voted on it. But everywhere I have worked, when a PR came from two people who built and tested it together, the review was lighter. Reviewers trusted the code more. Fewer issues got found in review. Fewer bugs slipped through afterward. So the lighter review kept looking like the right call, and it stuck.

That's a risk decision, even though it never feels like one. Somebody looked at a category of change and decided it needed less scrutiny than everything else.

And here is the part worth sitting with. Pairing earned that discount.

Pairing earned that discount

Researchers have studied pair programming for a long time, and the results are less magical than the marketing but pretty consistent.

Cockburn and Williams (2000) found pairing costs roughly 15% more development time and buys back roughly 15% fewer defects. They also measured statistically significant gains in design quality, technical skill, team communication, and resilience when someone leaves, since knowledge stops living in one person's head.

The 2009 meta-analysis from Hannay, Dybå, Arisholm and Sjøberg is more nuanced. A small positive effect on quality. A medium positive effect on duration, so pairs finish faster on the clock. A medium negative effect on effort, because they burn more total person-hours. Complexity moves the needle too: pairs are faster when the work is simple, and produce higher quality when the work is hard.

A couple caveats here, since I'm using this research to defend a practice. Neither study measured code review specifically. They measured defects and duration, and "so review gets shorter" is my personal inference from fewer defects showing up at the door. The authors of the meta-analysis also flag signs of publication bias in the pair programming literature, which is worth knowing before anyone treats these numbers as completely settled.

Even with these caveats, there's a track record here. The lighter review is resting on something real.

It was never a flat discount

The other thing about that discount is that it was never a one size fits all deal.

Two juniors pairing usually produce better code than either of them would have alone. Genuinely better. But still not as good as what comes out when a senior is in the pair. I've watched that difference play out enough times to treat it as a hard rule rather than a hunch.

So the shortcut was never "pairing gets a lighter review." It was closer to "this pair, working on this, has earned a lighter review." Everybody doing the reviewing knew that, even if nobody ever said it.

Which raises the question that made me want to write all of this stuff down...if a developer plus an agent counts as a pair, which pair is it?

AI code has not built that record

I want to be careful here, because there's a lot to consider and the tooling is moving fast. But from what I've seen up to this point, AI generated code on its own comes with a lot of problems in it. Security issues. Functional bugs. And a slower one that worries me more than the rest...people losing their understanding of their own systems, which makes those systems harder to fix the longer it goes on.

None of that earns a lighter review.

The cost moved the other direction at the same time, too. We've all read and seen how producing code got cheap. Evaluating it didn't. Nothing about an agent made reading code faster, made holding a system in your head easier, or made it quicker to spot a wrong assumption (no matter how confident the agent sounds).

So put those together. A lot of developers are working with agents right now. If that counts as pairing, it gets the lighter review. So we read less of the code, right when a lot more of it is showing up. And it's the kind that's hardest to spot problems in just by reading it.

That cost doesn't stay with the team that filed it that way. It lands on users, on clients, and on the business, usually much later.

Nobody is going to decide this in a meeting

That's the part I'm mulling over today.

No one on the engineering team is going to stand up and propose reviewing AI written code less carefully (at least I hope not). That's not how it happens. It happens when a category you already had quietly absorbs a new kind of work, and the rule attached to that category comes along for the ride. Dev + agent starts getting called pairing, pairing already had a discount, and the discount transfers without anyone explicitly deciding anything.

Most teams inherited their review shortcuts, and I'd be surprised if anyone wrote down what earned them. So when something new shows up asking to be filed under an existing category, there's nothing to check it against.

So here is what I would actually ask you to do, and then a real question.

Go find your team's review shortcuts. The paired code one. The "it's only a config change" one. The "this person's PRs are always clean" one. They exist, they're mostly unwritten, and you probably inherited at least one of them from a team you're no longer on.

Then ask what earned each one, and whether that thing is still true for the code you're merging today.

What did you find when you went looking? I am very curious whether other teams have caught this happening, or whether it's already too far along to see clearly. If you would rather talk it through than leave a comment, my inbox is open.

Three weeks ago I wrote about the difference between AI training crawlers and AI retrieval
agents:
GPTBot collects data to train models, but it's ChatGPT-User and OAI-SearchBot that fetch
your page live when ChatGPT answers a question — and only those can cite and link you.
Block them and you don't exist in AI answers, no matter how well you rank on Google.

A commenter said they hadn't realized these were different bots. That made me wonder how many
professional publishers haven't either. So I measured it.

Method

On August 1, 2026 I ran an automated check against the 50 biggest English-language news and
tech publishers. For each site:

1. Fetch robots.txt and evaluate it for 15 AI crawlers — 7 retrieval agents (OAI-SearchBot, ChatGPT-User, Claude-SearchBot, Claude-User, PerplexityBot, Perplexity-User, Amazonbot) and 8 training crawlers (GPTBot, ClaudeBot, CCBot, Google-Extended, Applebot-Extended, Bytespider, meta-externalagent, anthropic-ai) — using Google's documented robots semantics (most specific group wins, longest rule wins, Allow wins ties), for path /.
2. Fetch the homepage without executing JavaScript — because that's what retrieval agents do — and check whether the served HTML contains any readable text at all.

A site counts as citable only if both hold: no retrieval agent blocked, and actual text in
the served HTML. The tool is an open audit Actor I
built; four sites (NYT, Guardian, FT, Daily
Mail) bot-wall their homepage, so for those only the robots.txt half was evaluated — which
already settles their verdict.

Results

38 of 50 are not citable.

9 sites block all seven retrieval agents: CNN, NBC News, USA Today, HuffPost, The
Telegraph, Daily Mail, CNET, ZDNet, Mashable. Whatever these newsrooms publish, no AI answer
can ever quote it or link to it.

25 sites block in the wrong direction. They allow at least one training crawler while
blocking retrieval agents — meaning their content may train models, but the one thing that
sends readers back (a citation with a link) is off. The Verge, Wired, Ars Technica, The
Atlantic, Vox, The Guardian, The Washington Post and WSJ are all in this group. I doubt a
single one chose that trade on purpose.

5 sites fail by exactly one agent. ABC News and TechCrunch block only ChatGPT-User;
Axios, Tom's Hardware and VentureBeat block only Amazonbot. One robots.txt line away from
citable.

3 sites have the door open and the room empty. NPR, Politico and The Information allow
all seven retrieval agents — and serve a homepage whose HTML contains essentially no readable
text without JavaScript. Retrieval agents don't run JavaScript. A browser shows a normal page;
an AI agent gets nothing to quote. This failure is invisible in every browser-based audit.

Who gets blocked most tells its own story. PerplexityBot is blocked by 30 of 50 sites,
Amazonbot by 28, Anthropic's two retrieval agents by 24–25 — but OpenAI's OAI-SearchBot by
only 14. That's the licensing-deal era in one number: publishers with OpenAI deals let OpenAI's
citation bot in and block everyone else's.

The 12 citable sites: Fox News, CBS News, Business Insider, LA Times, Time, Slate, The
Independent, The Daily Beast, Semafor, Engadget, Gizmodo, PCMag.

Full table

Retrieval = citation agents allowed (of 7). Training = training crawlers allowed (of 8).
* = robots.txt only (homepage bot-walled).

Caveats, honestly

• Some of this is deliberate. The NYT is suing OpenAI; several publishers are negotiating licenses. For them, blocking is leverage, not an accident. But "we allow model training and forbid citations" (25 sites) is a hard position to defend as strategy — and the sites that copied 2023's "block the AI bots" lists inherited these rules with none of the leverage.
• This is a snapshot (Aug 1, 2026) of path / and the homepage. Sections may differ.
• "Citable" means technically reachable for citation, not "gets cited".

Check your own site

Two failure modes, both invisible in a browser and in classic SEO tools:

1. robots.txt: look for your citation agents (OAI-SearchBot, ChatGPT-User, Claude-SearchBot, Claude-User, PerplexityBot, Perplexity-User, Amazonbot). Blanket AI-blocklists and one-click CDN blockers usually hit these too. The 5-minute manual check is in my previous post.
2. Server-rendered text: curl your page and look for your content in the HTML. If it only appears after JavaScript runs, retrieval agents see an empty shell.

For a single site you honestly don't need a tool — the manual check takes five minutes.
Where it stops being trivial:

• You manage a portfolio. An agency with 50 client sites doesn't read 50 robots.txt files quarterly. This entire study — 50 sites, both checks — ran automated in about 40 minutes.
• The answer changes behind your back. Robots.txt files drift: CDN one-click "block AI bots" switches, CMS updates, replatforming. Cloudflare's managed robots.txt added rules to a site of mine that I never wrote. A check that was green in March can be red in June with nobody having touched anything.

That's what I built SEO Health Auditor for:
it runs both checks (plus regular technical SEO) across any list of sites, from $0.05 per
page, and on a schedule it diffs against the previous run — so you learn about the drift
before your traffic does.

Raw data for all 50 sites available on request — happy to share the JSON.

Introduction: The Monolithic Illusion in Modern Multi-Agent Architecture

If you have spent any time building localized agentic workflows using frameworks like LangGraph, you are likely familiar with the cozy comfort of a single-node memory space. In that localized paradigm, state mutations feel completely trivial. Every worker node, supervisor orchestration loop, and tool-use reflection routine reads from and writes to a monolithic, in-memory graph state object under the absolute protection of a single local event loop.

Accessing a variable, updating a chat history, or appending a scraped DOM element happens instantly and completely free of concurrency hazards. Everything occurs sequentially or within a single, predictable thread.

However, the moment your architecture scales out—moving from a cozy single-node execution environment to a distributed, multi-node cluster—that monolithic illusion shatters entirely. Imagine deploying specialized agents across different edge nodes, handling asynchronous browser automation tasks, or executing Model Context Protocol (MCP) tool servers across distinct cloud regions. When these disparate entities must collaborate on a single long-running task, the local StateGraph paradigm completely collapses.

Without a rigorous, mathematically sound distributed context layer, your systems will inevitably suffer from catastrophic split-brain scenarios, painful race conditions, lost updates during tool-use reflection loops, and desynchronized supervisor routing paths. To truly master modern, production-grade AI systems, you must understand how to architect distributed context management and agent state synchronization.

The Microservices Parallel: Monolithic State vs. Distributed Caching

To truly grasp why distributed context management is such a formidable challenge, we can look to a powerful analogy from modern web development: Microservices and Distributed Caching vs. Monolithic State.

Imagine a traditional monolithic web application where every component of the system—the user session manager, the shopping cart, the product catalog, and the checkout processor—shares a single, massive global JavaScript object in memory. Accessing and updating the shopping cart is instantaneous and free of race conditions because everything happens inside a single memory space. This is precisely analogous to our single-node StateGraph.

Now, scale that exact same application into a distributed microservices architecture deployed across a Kubernetes cluster. You have a Cart Service, a User Service, and a Payment Service, all running on separate containers, communicating over the network via gRPC or HTTP. If the Cart Service needs to know the user's current loyalty tier managed by the User Service, it cannot simply read a variable from local memory. It must query across the network, handle network latency, deal with unexpected network partitions, and resolve race conditions when two services try to update the user's state simultaneously.

Distributed context management in multi-agent MCP systems is the exact equivalent of solving the microservices data consistency problem. The StateGraph is no longer a localized data structure; it is a distributed, eventually consistent state machine. Every agent, supervisor, and MCP tool server acts as a distributed node that must agree upon the current reality of the browser DOM, active tool outputs, and internal agent reasoning steps.

The Anatomical Layers of Distributed Context

To construct a robust distributed context management system for agentic workflows, we must break down the architecture into three foundational layers:

1. The State Representation Layer: How the graph state is modeled so it can traverse complex networks.
2. The Synchronization Layer: How conflicting mutations from parallel agents are resolved without human intervention.
3. The Persistence and Fault-Tolerance Layer: How long-running browser automation tasks survive network drops, node crashes, and MCP server restarts.

1. State Representation and the Distributed Graph State

In a localized environment, the StateGraph maintains a mutable dictionary or object. In a distributed system, this object must be serialized, transmitted, and reconstructed across heterogeneous runtimes. Furthermore, when dealing with Model Context Protocol (MCP) servers, the context includes not just text messages and variables, but complex binary payloads, DOM snapshots, screenshot buffers, and dynamic tool schemas.

Consider the role of the Supervisor Node in this distributed topology. The Supervisor acts as the central traffic controller, making routing decisions based on the current Graph State. In a distributed setting, the Supervisor does not hold the true state in its own volatile memory; rather, it queries a distributed view of the state. If two worker agents—say, one executing a web scraper via a browser automation MCP server and another analyzing financial data—both complete their tasks simultaneously, they generate parallel state updates.

This is structurally similar to handling state synchronization in a collaborative real-time editing application like Figma or Google Docs. When two users type in the same text box simultaneously, the application cannot simply overwrite one user's input with the other's. It must track every keystroke as an operation, merge them logically, and maintain a coherent document state across all connected clients. In our agentic system, when Worker Agent A extracts a table from a webpage and Worker Agent B clicks a pagination button, these two actions mutate the shared browser context. If their states are not synchronized precisely, the Supervisor will route the next task based on stale or contradictory information, causing the agentic workflow to hallucinate, loop infinitely, or crash.

2. The Mechanics of State Synchronization: CRDTs vs. Distributed Locks

When multiple agents attempt to modify the shared graph state concurrently, we face the classic concurrency problem of computer science. There are two primary architectural philosophies for solving this in distributed systems: Pessimistic Concurrency Control (Distributed Locking) and Optimistic Replicated Data Types (Conflict-free Replicated Data Types, or CRDTs).

Pessimistic Concurrency via Distributed Locking

In a pessimistic locking model, before an agent can invoke a tool via the Model Context Protocol or modify a section of the StateGraph, it must acquire a distributed lock (often implemented using Redis, ZooKeeper, or etcd).

• The Process: Worker Agent A requests an exclusive lease on the browser navigation state. The distributed lock manager grants the lease with a Time-To-Live (TTL) to prevent deadlocks if the agent crashes. While Agent A holds the lock, Worker Agent B’s request to click a DOM element is blocked or rejected. Once Agent A finishes its tool execution and updates the graph state, it releases the lock, allowing Agent B to proceed.
• The Trade-off: While this guarantees absolute safety and zero conflict, it introduces severe latency bottlenecks. Browser automation tasks are inherently slow; waiting for network round-trips to acquire and release distributed locks for every single DOM interaction creates an unacceptable performance drag, crippling the real-time responsiveness required by complex multi-agent workflows.

Optimistic Concurrency via CRDTs

To achieve high-throughput, low-latency collaboration without blocking agents, advanced distributed MCP architectures rely on Conflict-free Replicated Data Types (CRDTs).

• The Process: CRDTs are specialized data structures mathematically proven to converge to the same value across all replicas without requiring locks, regardless of the order in which network messages arrive. Every agent maintains a local replica of the graph state and the MCP context. When an agent performs a mutation, it applies the mutation locally and broadcasts a state delta to all other nodes.
• Mathematical Convergence: CRDTs rely on commutative, associative, and idempotent operations. Whether state update $A$ arrives before state update $B$ on Node 1, but update $B$ arrives before update $A$ on Node 2, the underlying mathematical structure guarantees that after both updates are processed, both nodes will arrive at an identical state representation.
• Application to Agents: In the context of our agentic system, conversation histories, tool output registries, and state variables are structured as state-based CRDTs (CvRDTs) or operation-based CRDTs (CmRDTs). For example, a chat history is modeled as a Grow-Only Set (G-Set) or Observed-Remove Set (OR-Set), ensuring that messages appended by parallel worker agents are never lost, even during network partitions.

Concurrency Comparison Matrix

3. Event-Driven State Replication and Persistence

A distributed agentic system is only as reliable as its event replication and persistence layers. Long-running browser automation tasks—such as scraping thousands of pages, filling out multi-step enterprise forms, or monitoring dynamic dashboards—can span hours or even days. During such extended runs, individual worker nodes, MCP tool servers, or network switches are bound to fail.

To ensure fault tolerance and seamless session recovery, the distributed state management layer must implement Event-Driven State Replication.

• The Event Sourcing Pattern: Instead of merely saving the current snapshot of the StateGraph to a database, every state transition, tool call, and tool-use reflection observation is recorded as an immutable event in an append-only log (such as Apache Kafka, Redis Streams, or NATS).
• State Reconstruction (Rehydration): If a worker node running a browser automation MCP server crashes mid-task, a supervisor node or a standby worker can instantly spin up, read the event stream from the distributed log, and replay every event in chronological order to reconstruct the exact graph state up to the millisecond of the failure. This process, known as event sourcing and state rehydration, ensures that an agent never loses its "train of thought" or the context gathered by expensive tool invocations.

Furthermore, this event-driven architecture empowers the Tool Use Reflection loop in a distributed setting. When a worker agent executes a tool via an MCP server, the raw output (e.g., a massive JSON payload or a base64-encoded screenshot of a broken webpage) is published as an event. A distributed reflection service consumes this event, evaluates the success or failure of the tool call against the graph state, and emits a correction event. This decoupled, event-driven feedback loop allows multiple supervisor nodes to monitor agent health and dynamically re-route failing tasks to healthier worker nodes without interrupting the main execution thread.

Deep Architectural Dive: The Lifecycle of a Distributed Agentic Task

To synthesize these theoretical foundations, let us trace the complete lifecycle of a complex task traversing a distributed MCP and browser automation environment.

1. Task Initialization and State Bootstrap:
   A user submits a high-level goal: "Audit all competitor pricing pages across 50 e-commerce domains and compile a unified market report." The primary entry point receives this request and initializes the distributed StateGraph state, committing the initial goal vector and configuration parameters to the distributed CRDT store and appending the creation event to the event log.

2. Supervisor Routing and Distributed Locking:
   The central Supervisor Node analyzes the graph state. It determines that the task requires parallel execution and splits the 50 domains into batches of 10. It assigns each batch to a distinct Worker Agent running on a separate cluster node. Before dispatching the browser automation commands, each worker acquires a non-blocking lease or registers its intent in the CRDT state vector to prevent duplicate scraping of the same domain.

3. MCP Tool Execution and State Mutation:
   Worker Agent 1 connects to its local Browser Automation MCP Server. It launches a headless browser instance, navigates to competitor URL A, and extracts the pricing table. The raw DOM data and a visual screenshot are returned to the MCP server. The worker agent packages this output into a state delta and broadcasts it via the CRDT synchronization engine. Across the cluster, all other worker nodes and replica supervisors instantly integrate this delta into their local views of the graph state without locking the system.

4. Tool Use Reflection and Error Handling:
   Simultaneously, Worker Agent 2 encounters a CAPTCHA challenge on competitor URL B. The MCP server returns a tool output indicating failure. In a localized system, this would trigger a simple try-catch block. In our distributed architecture, this failure event is published to the event-driven replication bus. The Tool Use Reflection service intercepts the failure event, analyzes the observation, and determines that a human-in-the-loop intervention or a proxy rotation MCP tool must be invoked.

5. Consensus and Session Recovery:
   As workers complete their sub-tasks, their state mutations converge deterministically via the CRDT engine. The supervisor continuously evaluates the converged graph state. If a worker node abruptly loses power, the cluster's heartbeat monitor detects the drop, the event log replays the last known state to a newly spawned container, and the browser automation task resumes seamlessly from the exact point of failure.

Practical Implementation: Building a Distributed Context Manager

To understand how distributed context management and state synchronization operate within a modern Model Context Protocol (MCP) infrastructure, we must examine a clean, self-contained implementation.

In a SaaS web application context—such as a collaborative browser-automation workspace where multiple AI agents concurrently inspect DOM nodes, execute navigation actions, and modify shared system state—race conditions can corrupt session context. Below is a foundational, fully self-contained TypeScript implementation illustrating a distributed state synchronization mechanism using a simplified Conflict-free Replicated Data Type (CRDT)-inspired state container paired with a distributed locking utility.

/**
 * @file distributed-context.ts
 * @description A self-contained TypeScript implementation of a distributed context 
 * manager and state synchronizer for multi-agent browser automation tasks.
 */

import { randomUUID } from 'crypto';

// ============================================================================
// Types & Interfaces
// ============================================================================

/**
 * Represents a single piece of context or artifact generated by an agent.
 */
interface ContextArtifact {
    id: string;
    agentId: string;
    key: string;
    value: unknown;
    vector: number; // Logical clock vector component
    timestamp: number;
}

/**
 * Represents a distributed lock acquired by an agent to modify critical context.
 */
interface DistributedLock {
    resourceKey: string;
    ownerAgentId: string;
    expiresAt: number;
}

/**
 * Log entry for event-driven state replication.
 */
interface ReplicationEvent {
    eventId: string;
    type: 'SET' | 'DELETE' | 'LOCK' | 'UNLOCK';
    payload: unknown;
    vector: number;
    timestamp: number;
}

// ============================================================================
// Core Implementation
// ============================================================================

/**
 * Manages distributed agent context, state synchronization, and concurrency control.
 */
export class DistributedContextManager {
    private store: Map<string, ContextArtifact> = new Map();
    private locks: Map<string, DistributedLock> = new Map();
    private eventLog: ReplicationEvent[] = [];
    private nodeLogicalClock: number = 0;
    private readonly nodeIdentity: string;

    constructor(nodeIdentity?: string) {
        this.nodeIdentity = nodeIdentity || `node-${randomUUID().slice(0, 8)}`;
    }

    /**
     * Attempts to acquire a distributed lock on a specific resource key.
     * Prevents race conditions during parallel tool execution.
     * 
     * @param resourceKey The key representing the shared resource or state segment.
     * @param agentId The identifier of the agent requesting the lock.
     * @param ttlMs Time-to-live for the lock in milliseconds.
     * @returns boolean indicating success or failure.
     */
    public async acquireLock(resourceKey: string, agentId: string, ttlMs: number = 5000): Promise<boolean> {
        const now = Date.now();
        const existingLock = this.locks.get(resourceKey);

        // Check if lock exists and is still valid
        if (existingLock && existingLock.expiresAt > now) {
            if (existingLock.ownerAgentId !== agentId) {
                return false; // Held by another agent
            }
            // Renewable by the same owner
            existingLock.expiresAt = now + ttlMs;
            return true;
        }

        // Acquire new or expired lock
        const newLock: DistributedLock = {
            resourceKey,
            ownerAgentId: agentId,
            expiresAt: now + ttlMs
        };

        this.locks.set(resourceKey, newLock);
        this.nodeLogicalClock++;

        this.recordEvent({
            eventId: randomUUID(),
            type: 'LOCK',
            payload: newLock,
            vector: this.nodeLogicalClock,
            timestamp: now
        });

        return true;
    }

    /**
     * Releases a distributed lock on a resource key.
     */
    public async releaseLock(resourceKey: string, agentId: string): Promise<boolean> {
        const existingLock = this.locks.get(resourceKey);
        if (!existingLock || existingLock.ownerAgentId !== agentId) {
            return false;
        }

        this.locks.delete(resourceKey);
        this.nodeLogicalClock++;

        this.recordEvent({
            eventId: randomUUID(),
            type: 'UNLOCK',
            payload: { resourceKey, ownerAgentId: agentId },
            vector: this.nodeLogicalClock,
            timestamp: Date.now()
        });

        return true;
    }

    /**
     * Sets a context artifact using Last-Write-Wins (LWW) with logical clocks 
     * to resolve conflicts deterministically.
     */
    public async setContext(agentId: string, key: string, value: unknown): Promise<ContextArtifact> {
        const now = Date.now();
        this.nodeLogicalClock++;

        const existing = this.store.get(key);

        // Conflict Resolution: Last-Write-Wins based on logical vector, then timestamp
        if (existing) {
            if (
                existing.vector > this.nodeLogicalClock || 
                (existing.vector === this.nodeLogicalClock && existing.timestamp > now)
            ) {
                // Reject out-of-order stale update
                return existing;
            }
        }

        const artifact: ContextArtifact = {
            id: randomUUID(),
            agentId,
            key,
            value,
            vector: this.nodeLogicalClock,
            timestamp: now
        };

        this.store.set(key, artifact);

        this.recordEvent({
            eventId: randomUUID(),
            type: 'SET',
            payload: artifact,
            vector: this.nodeLogicalClock,
            timestamp: now
        });

        return artifact;
    }

    /**
     * Retrieves a context artifact by key.
     */
    public getContext(key: string): unknown | undefined {
        return this.store.get(key)?.value;
    }

    /**
     * Replicates incoming remote state changes into the local node store.
     */
    public applyRemoteEvent(event: ReplicationEvent): void {
        // Update local logical clock to maintain causality
        this.nodeLogicalClock = Math.max(this.nodeLogicalClock, event.vector) + 1;

        if (event.type === 'SET') {
            const artifact = event.payload as ContextArtifact;
            const existing = this.store.get(artifact.key);

            // Apply LWW conflict resolution rule
            if (!existing || 
                artifact.vector > existing.vector || 
                (artifact.vector === existing.vector && artifact.timestamp > existing.timestamp)) {
                this.store.set(artifact.key, artifact);
            }
        } else if (event.type === 'LOCK') {
            const lock = event.payload as DistributedLock;
            this.locks.set(lock.resourceKey, lock);
        } else if (event.type === 'UNLOCK') {
            const unlockData = event.payload as { resourceKey: string; ownerAgentId: string };
            const existing = this.locks.get(unlockData.resourceKey);
            if (existing && existing.ownerAgentId === unlockData.ownerAgentId) {
                this.locks.delete(unlockData.resourceKey);
            }
        }

        this.eventLog.push(event);
    }

    /**
     * Appends an event to the internal audit and replication log.
     */
    private recordEvent(event: ReplicationEvent): void {
        this.eventLog.push(event);
    }

    /**
     * Exports the entire state for node bootstrap or recovery.
     */
    public exportState(): { store: [string, ContextArtifact][]; locks: [string, DistributedLock][]; clock: number } {
        return {
            store: Array.from(this.store.entries()),
            locks: Array.from(this.locks.entries()),
            clock: this.nodeLogicalClock
        };
    }
}

// ============================================================================
// Execution Demonstration (SaaS Browser Automation Context)
// ============================================================================

async function runDemo() {
    console.log("Initializing Distributed Context Manager for Browser Automation Agents...");
    const manager = new DistributedContextManager("node-primary-us-east");

    const agentId = "agent-browser-worker-01";
    const targetResource = "dom_snapshot_login_page";

    // 1. Attempt to acquire lock before scraping/modifying page context
    const hasLock = await manager.acquireLock(targetResource, agentId, 10000);
    console.log(`Agent ${agentId} acquired lock on '${targetResource}': ${hasLock}`);

    if (hasLock) {
        // 2. Set shared context state after interacting with the browser
        const artifact = await manager.setContext(agentId, targetResource, {
            url: "https://saas.example.com/login",
            domTitle: "Sign In - Enterprise Portal",
            inputElementsDetected: 2,
            formInteractive: true
        });
        console.log(`Context artifact successfully synchronized:`, artifact);

        // 3. Release lock upon completion
        const released = await manager.releaseLock(targetResource, agentId);
        console.log(`Agent ${agentId} released lock on '${targetResource}': ${released}`);
    }
}

// Execute the simulation
runDemo().catch(console.error);

Conclusion: Engineering Resilient Agent Networks

Moving beyond single-node prototypes into production-grade multi-agent architectures requires a fundamental shift in how we approach state, concurrency, and network partitions. As we have explored throughout this guide, distributed context management and agent state synchronization are not merely optional optimizations—they are the core pillars that prevent distributed agent networks from collapsing into race conditions, conflicting tool outputs, and unrecoverable split-brain states.

By carefully selecting between pessimistic distributed locks and optimistic CRDTs, implementing event-driven replication logs for flawless session rehydration, and structuring your Model Context Protocol (MCP) servers to handle asynchronous mutations natively, you lay the groundwork for truly bulletproof enterprise automation. Whether you are coordinating dozens of browser automation workers across global cloud regions or scaling complex supervisor-worker hierarchies, mastering these distributed primitives ensures your agentic systems remain robust, scalable, and ready for production at a global scale.

The concepts and code demonstrated here are drawn directly from the comprehensive roadmap laid out in the book Model Context Protocol (MCP) & Computer Use. Standardizing Tool Integration, Vision-Driven Browser Automation, and Agent Governance in TypeScript, you can find it here. Check also the many other ebooks.

Introduction

Imagine sending 100 from Alice to Bob.

If both accounts are in one database, this is easy: start a transaction, update both balances, and commit. But this example puts Alice in MySQL and Bob in PostgreSQL. One database cannot finish—or undo—the other database's work.

That is the problem two-phase commit, usually called 2PC, tries to solve.

This article follows a small Go program that performs the transfer and then crashes on purpose. The two crashes happen almost at the same moment, but recovery gives them opposite answers. That small difference is the easiest way to understand 2PC.

The promise we need

At the start:

Alice in MySQL:      500
Bob in PostgreSQL:   100

After a successful transfer:

Alice in MySQL:      400
Bob in PostgreSQL:   200

If anything goes wrong, both balances should stay as they were. We never want this:

Alice in MySQL:      400
Bob in PostgreSQL:   100

That would mean Alice lost money and Bob never received it.

Two-phase commit in simple words

2PC has one person in charge—the coordinator—and the databases doing the work.

First, the coordinator asks each database, "Can you do your part?" The databases save their work, hold on to it, and answer yes or no. This is the prepare phase.

If everyone says yes, the coordinator decides to commit. If anyone says no, it decides to undo everything. This is the decision phase.

The important thing is that a yes vote does not mean the database has committed. It means:

"I have saved my work, I am keeping the row locked, and I will wait for your final answer."

Where XA fits in

2PC is the idea. XA is a standard set of commands that helps a coordinator use that idea with different database systems.

MySQL calls its commands XA PREPARE and XA COMMIT. PostgreSQL uses PREPARE TRANSACTION and COMMIT PREPARED. Different names, same story:

You do not need to memorize those commands to understand the example. The Go program uses the right command for each database and treats both answers in the same way.

Running the example

The program starts MySQL and PostgreSQL locally, creates the two accounts, and runs the normal transfer plus both crash tests.

docker run -d --name xa-mysql -e MYSQL_ROOT_PASSWORD=xa -e MYSQL_DATABASE=bank \
  -p 13306:3306 mysql:8
docker run -d --name xa-pg -e POSTGRES_PASSWORD=xa -e POSTGRES_DB=bank \
  -p 15432:5432 postgres:16 -c max_prepared_transactions=20
go run .

The PostgreSQL setting is needed because prepared transactions are turned off by default in many installations.

Reading the Go program

Setup

connect() opens one connection pool for MySQL and one for PostgreSQL. reset() starts every run with Alice at 500 and Bob at 100.

The transfer is given one shared name, such as tx-ok. That name lets recovery find the pieces of the same transfer later.

Doing the transfer

Inside transfer(), the program first makes the two local changes:

UPDATE accounts SET balance = balance - ? WHERE id='alice'
UPDATE accounts SET balance = balance + $1 WHERE id='bob'

The changes are not visible as a completed transfer yet. They are still waiting inside each database.

Asking both databases to prepare

Next, the coordinator asks both databases to get ready:

XA PREPARE 'tx','my',1
PREPARE TRANSACTION 'tx'

When those calls work, MySQL and PostgreSQL have both said yes. They have saved their changes and are waiting. They also keep locks on the affected rows, so nobody else can change Alice or Bob in a conflicting way.

The one line that matters most

After both yes votes, the coordinator writes its answer to a small file named decisions.log:

if err := decide(gtrid, "commit"); err != nil {
    rollback(my, pg, gtrid)
    return err
}

Inside decide(), the program calls f.Sync(). That makes sure the decision really reaches disk.

This is the real commit point. Not the later database commands. Once commit is safely written to the log, the coordinator has made its choice forever. If it crashes after this, recovery must finish the commit.

Two crashes that explain everything

The program crashes in two places: once just before the log is written, and once just after. Only one f.Sync() sits between them.

Crash before the decision is saved

Both databases have prepared their work. But the coordinator crashes before writing commit to decisions.log.

When the program comes back, it asks the databases, "Do you still have unfinished work?" They both say yes. Then it checks the log. There is no commit decision there.

So it rolls both sides back:

mysql:     XA ROLLBACK
postgres:  ROLLBACK PREPARED

This is called presumed abort. In everyday language: if the coordinator did not save a decision to commit, assume the transfer did not happen.

Crash after the decision is saved

Now move the crash one line later. Both databases prepare their work. The coordinator writes commit to the log and safely syncs it to disk. Then it crashes before it can tell either database.

When it starts again, the balances may still look unchanged because the databases are still waiting. But the log says commit, so recovery has only one safe choice:

mysql:     XA COMMIT
postgres:  COMMIT PREPARED

The coordinator is not deciding again. It is simply delivering the decision it already made.

How recovery works

recoverInDoubt() is the cleanup worker in this example. Its rule is short:

Does the log say commit?

Yes -> commit the unfinished work.
No  -> roll it back.

It asks MySQL about unfinished XA transactions and PostgreSQL about unfinished prepared transactions. Then it checks decisions.log and gives both databases the same answer.

This works because the code always saves the commit decision before it starts sending commit commands to the databases.

The downside: other work can wait

While a database is prepared, it keeps locks. In the crash-after test, Alice's row is still locked while the coordinator is down.

showBlocking() opens another connection and tries to update Alice. It waits and then gets this error:

Error 1205 (HY000): Lock wait timeout exceeded

That is the real cost of 2PC. The databases are safe, but they cannot decide by themselves while they wait for the coordinator. This is why people call 2PC a blocking protocol.

Should you use it?

2PC is useful when a small number of dependable systems truly need one all-or-nothing decision. It is not the usual choice for every application.

Many systems use a transactional outbox or a saga instead. Those patterns are often easier to run because they avoid keeping locks across systems, but they make a different trade-off: they do not give the same single global commit.

The one thing to remember

A database saying yes has not committed. It has promised to wait. The transfer becomes committed when the coordinator safely records its decision.

In this program, one call to f.Sync() separates a transfer that recovery must roll back from a transfer that recovery must commit.

Complete main.go

The following source is embedded verbatim from the demo.

// One global transaction across two different databases: 100 leaves alice in
// MySQL and arrives at bob in Postgres, atomically. Then we kill the coordinator
// at the worst possible moment and let recovery clean up.
//
//  docker run -d --name xa-mysql -e MYSQL_ROOT_PASSWORD=xa -e MYSQL_DATABASE=bank \
//    -p 13306:3306 mysql:8
//  docker run -d --name xa-pg -e POSTGRES_PASSWORD=xa -e POSTGRES_DB=bank \
//    -p 15432:5432 postgres:16 -c max_prepared_transactions=20
//  go run .
package main

import (
    "bufio"
    "context"
    "database/sql"
    "errors"
    "fmt"
    "log"
    "os"
    "strings"

    _ "github.com/go-sql-driver/mysql"
    _ "github.com/lib/pq"
)

const (
    mysqlDSN = "root:xa@tcp(127.0.0.1:13306)/bank"
    pgDSN    = "postgres://postgres:xa@127.0.0.1:15432/bank?sslmode=disable"

    // The coordinator's durable decision log. This file is the source of truth
    // for whether a global transaction committed — not the databases.
    decisionLog = "decisions.log"
)

var errCrashed = errors.New("coordinator crashed")

var ctx = context.Background()

func main() {
    my, pg := connect()
    defer my.Close()
    defer pg.Close()
    reset(my, pg)

    fmt.Println("\n=== 1. a normal cross-database commit ===")
    balances(my, pg)
    if err := transfer(my, pg, "tx-ok", 100, crashNever); err != nil {
        log.Fatal(err)
    }
    balances(my, pg)

    fmt.Println("\n=== 2. the coordinator dies just AFTER the commit point ===")
    fmt.Println("   transfer returned:", transfer(my, pg, "tx-after", 100, crashAfter))
    fmt.Println("   the transfer is invisible — balances unchanged from step 1:")
    balances(my, pg)
    fmt.Println("   ...but both databases hold locks, so unrelated writes stall:")
    showBlocking(my)

    fmt.Println("\n=== 3. recovery must COMMIT it: the decision was already made ===")
    recoverInDoubt(my, pg)
    balances(my, pg)

    fmt.Println("\n=== 4. now the coordinator dies just BEFORE the commit point ===")
    fmt.Println("   same two YES votes, but nothing was written down.")
    fmt.Println("   transfer returned:", transfer(my, pg, "tx-before", 100, crashBefore))

    fmt.Println("\n=== 5. recovery must ROLL BACK: no decision means it never committed ===")
    recoverInDoubt(my, pg)
    balances(my, pg)
    fmt.Println("\n   Same votes, one instant apart, opposite outcomes. That's 2PC.")
}

// Where to kill the coordinator. The two crash points sit on either side of a
// single fsync, and they must lead to opposite recoveries.
type crashPoint int

const (
    crashNever crashPoint = iota
    crashBefore
    crashAfter
)

// transfer runs the full two-phase commit.
func transfer(my, pg *sql.DB, gtrid string, amount int, crash crashPoint) error {
    // Each branch of the transaction needs its own dedicated connection.
    myConn, err := my.Conn(ctx)
    if err != nil {
        return err
    }
    defer myConn.Close()
    pgConn, err := pg.Conn(ctx)
    if err != nil {
        return err
    }
    defer pgConn.Close()

    // ---- do the work, inside a branch on each database ----
    // MySQL speaks the XA dialect: 'gtrid','branch-qualifier',format-id.
    xid := fmt.Sprintf("'%s','my',1", gtrid)
    if err := exec(myConn, "XA START "+xid); err != nil {
        return err
    }
    if err := exec(myConn, "UPDATE accounts SET balance = balance - ? WHERE id='alice'", amount); err != nil {
        return err
    }
    // XA END says "no more work on this branch".
    if err := exec(myConn, "XA END "+xid); err != nil {
        return err
    }

    // Postgres has no XA API at all — just the same two phases as plain SQL,
    // identified by a single string instead of a structured XID.
    if err := exec(pgConn, "BEGIN"); err != nil {
        return err
    }
    if err := exec(pgConn, "UPDATE accounts SET balance = balance + $1 WHERE id='bob'", amount); err != nil {
        return err
    }

    // ---- PHASE 1: ask both databases to vote ----
    // A successful prepare means: "my changes are on disk, I've kept my locks,
    // and I will do whatever you say next — even if I crash in between."
    if err := exec(myConn, "XA PREPARE "+xid); err != nil {
        fmt.Println("   mysql voted NO:", err)
        rollback(my, pg, gtrid)
        return err
    }
    fmt.Println("   phase 1: XA PREPARE           -> mysql voted YES")

    if err := exec(pgConn, "PREPARE TRANSACTION '"+gtrid+"'"); err != nil {
        fmt.Println("   postgres voted NO:", err)
        rollback(my, pg, gtrid)
        return err
    }
    fmt.Println("   phase 1: PREPARE TRANSACTION  -> postgres voted YES")

    if crash == crashBefore {
        return errCrashed
    }

    // ---- THE COMMIT POINT ----
    // The transaction commits the instant this write is durable, even though
    // neither database knows it yet. Before this line, recovery is free to
    // abort. After it, recovery MUST commit. Everything below is bookkeeping.
    if err := decide(gtrid, "commit"); err != nil {
        rollback(my, pg, gtrid)
        return err
    }
    fmt.Printf("   COMMIT POINT: %q fsynced to %s\n", gtrid+" commit", decisionLog)

    if crash == crashAfter {
        return errCrashed
    }

    // ---- PHASE 2: deliver the news ----
    // A prepared transaction belongs to the server, not to the session that
    // created it, so these can run on any connection — or after a reboot.
    if err := exec(my, "XA COMMIT "+xid); err != nil {
        return err
    }
    fmt.Println("   phase 2: XA COMMIT            -> mysql done")
    if err := exec(pg, "COMMIT PREPARED '"+gtrid+"'"); err != nil {
        return err
    }
    fmt.Println("   phase 2: COMMIT PREPARED      -> postgres done")
    return decide(gtrid, "forget")
}

// recoverInDoubt asks each database what it has prepared but never resolved,
// then looks up the verdict. The rule is asymmetric, and that asymmetry is the
// whole protocol:
//
//  "commit" in the log -> commit the branch, retrying until it succeeds
//  nothing in the log  -> roll it back ("presumed abort")
//
// It is safe because the decision is always logged before phase 2, so a
// prepared branch with no recorded decision cannot have committed anywhere.
func recoverInDoubt(my, pg *sql.DB) {
    decisions := decisions()

    // MySQL: XA RECOVER returns formatID, gtrid_length, bqual_length, data.
    rows, err := my.Query("XA RECOVER")
    if err != nil {
        log.Fatal(err)
    }
    var myPending []string
    for rows.Next() {
        var format, gtridLen, bqualLen int
        var data string
        if err := rows.Scan(&format, &gtridLen, &bqualLen, &data); err != nil {
            log.Fatal(err)
        }
        myPending = append(myPending, data[:gtridLen])
    }
    rows.Close()

    for _, gtrid := range myPending {
        fmt.Printf("   mysql is in doubt about %q; decision log says %q\n", gtrid, decisions[gtrid])
        xid := fmt.Sprintf("'%s','my',1", gtrid)
        if decisions[gtrid] == "commit" {
            must(exec(my, "XA COMMIT "+xid))
            fmt.Println("     -> XA COMMIT")
        } else {
            must(exec(my, "XA ROLLBACK "+xid))
            fmt.Println("     -> XA ROLLBACK (presumed abort)")
        }
    }

    // Postgres: the same question, asked of pg_prepared_xacts.
    rows, err = pg.Query("SELECT gid FROM pg_prepared_xacts")
    if err != nil {
        log.Fatal(err)
    }
    var pgPending []string
    for rows.Next() {
        var gid string
        if err := rows.Scan(&gid); err != nil {
            log.Fatal(err)
        }
        pgPending = append(pgPending, gid)
    }
    rows.Close()

    for _, gtrid := range pgPending {
        fmt.Printf("   postgres is in doubt about %q; decision log says %q\n", gtrid, decisions[gtrid])
        if decisions[gtrid] == "commit" {
            must(exec(pg, "COMMIT PREPARED '"+gtrid+"'"))
            fmt.Println("     -> COMMIT PREPARED")
        } else {
            must(exec(pg, "ROLLBACK PREPARED '"+gtrid+"'"))
            fmt.Println("     -> ROLLBACK PREPARED (presumed abort)")
        }
    }
}

// rollback abandons a transaction on both databases, at any stage.
func rollback(my, pg *sql.DB, gtrid string) {
    _ = exec(my, fmt.Sprintf("XA ROLLBACK '%s','my',1", gtrid))
    _ = exec(pg, "ROLLBACK PREPARED '"+gtrid+"'")
    _ = decide(gtrid, "abort")
}

// ---------------------------------------------------------------------------
// the coordinator's decision log
// ---------------------------------------------------------------------------

// decide appends a verdict and fsyncs it. The fsync is the entire point: an
// unflushed decision is not a decision.
func decide(gtrid, verdict string) error {
    f, err := os.OpenFile(decisionLog, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
    if err != nil {
        return err
    }
    defer f.Close()
    if _, err := fmt.Fprintf(f, "%s %s\n", gtrid, verdict); err != nil {
        return err
    }
    return f.Sync()
}

// decisions replays the log. A later "forget" clears a resolved transaction.
func decisions() map[string]string {
    out := map[string]string{}
    f, err := os.Open(decisionLog)
    if err != nil {
        return out
    }
    defer f.Close()
    sc := bufio.NewScanner(f)
    for sc.Scan() {
        parts := strings.Fields(sc.Text())
        if len(parts) != 2 {
            continue
        }
        if parts[1] == "forget" {
            delete(out, parts[0])
            continue
        }
        out[parts[0]] = parts[1]
    }
    return out
}

// ---------------------------------------------------------------------------
// plumbing
// ---------------------------------------------------------------------------

type execer interface {
    ExecContext(context.Context, string, ...any) (sql.Result, error)
}

func exec(db execer, q string, args ...any) error {
    _, err := db.ExecContext(ctx, q, args...)
    return err
}

func must(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

func connect() (*sql.DB, *sql.DB) {
    my, err := sql.Open("mysql", mysqlDSN)
    must(err)
    if err := my.Ping(); err != nil {
        log.Fatalf("mysql not reachable: %v\n(see the docker command at the top of this file)", err)
    }
    pg, err := sql.Open("postgres", pgDSN)
    must(err)
    if err := pg.Ping(); err != nil {
        log.Fatalf("postgres not reachable: %v", err)
    }
    return my, pg
}

// reset gives every run a clean slate, including any prepared transactions and
// decisions left behind by a previous run.
func reset(my, pg *sql.DB) {
    os.Remove(decisionLog)
    recoverInDoubtQuietly(my, pg)
    must(exec(my, `CREATE TABLE IF NOT EXISTS accounts (
        id VARCHAR(32) PRIMARY KEY, balance INT NOT NULL) ENGINE=InnoDB`))
    must(exec(pg, `CREATE TABLE IF NOT EXISTS accounts (
        id TEXT PRIMARY KEY, balance INT NOT NULL)`))
    must(exec(my, "DELETE FROM accounts"))
    must(exec(pg, "DELETE FROM accounts"))
    must(exec(my, "INSERT INTO accounts VALUES ('alice', 500)"))
    must(exec(pg, "INSERT INTO accounts VALUES ('bob', 100)"))
}

func recoverInDoubtQuietly(my, pg *sql.DB) {
    rows, err := my.Query("XA RECOVER")
    if err == nil {
        var gtrids []string
        for rows.Next() {
            var format, gl, bl int
            var data string
            if rows.Scan(&format, &gl, &bl, &data) == nil {
                gtrids = append(gtrids, data[:gl])
            }
        }
        rows.Close()
        for _, g := range gtrids {
            _ = exec(my, fmt.Sprintf("XA ROLLBACK '%s','my',1", g))
        }
    }
    rows, err = pg.Query("SELECT gid FROM pg_prepared_xacts")
    if err == nil {
        var gids []string
        for rows.Next() {
            var g string
            if rows.Scan(&g) == nil {
                gids = append(gids, g)
            }
        }
        rows.Close()
        for _, g := range gids {
            _ = exec(pg, "ROLLBACK PREPARED '"+g+"'")
        }
    }
}

func balances(my, pg *sql.DB) {
    var a, b int
    must(my.QueryRow("SELECT balance FROM accounts WHERE id='alice'").Scan(&a))
    must(pg.QueryRow("SELECT balance FROM accounts WHERE id='bob'").Scan(&b))
    fmt.Printf("   alice (mysql) = %-4d bob (postgres) = %d\n", a, b)
}

// showBlocking demonstrates 2PC's real cost: a prepared branch keeps its row
// locks, so unrelated traffic stalls until someone resolves the transaction.
func showBlocking(my *sql.DB) {
    conn, err := my.Conn(ctx)
    must(err)
    defer conn.Close()
    must(exec(conn, "SET SESSION innodb_lock_wait_timeout = 1"))
    err = exec(conn, "UPDATE accounts SET balance = 999 WHERE id='alice'")
    fmt.Println("     ", err)
}

I’m writing this to teach myself how to learn. This post is a test of the “learn by teaching” theory. Please don’t use this as an educational resource — if something here interests you, do your own independent research on it.

Links to the advice videos I’m following are at the end of this post.

Trust your gut. Follow the advice that sounds the most fun and engaging to you.

Develop your own advice, made specifically for you.
Watch at least one tutorial on the topic you want to learn, and write down what you think are the most important parts. How many tutorials you need varies from person to person, so experiment to see what works for you.

Study for 5 seconds to 10 minutes. A popular theory says it’s more important to build the habit of starting than to force long study sessions you dread. Increase your time on the topic gradually.
Do things that inspire you and connect to what you’re learning — hobbies related to the subject count.

Identify as someone who does the thing you want to learn. Replace “I’m bad at game development” with “I am someone who develops games.” Use phrasing that feels natural. If “I am the greatest video game developer on the planet” feels off, try “I am someone who develops video games” instead — it’s more believable and easier to internalize. Then reinforce the identity with action. This pairs well with the 5-second-to-10-minute study method above.

Break information into chunks. Organize what you’re learning into smaller, connected groups instead of isolated facts — this makes it easier to comprehend. For example: learning a language, study 5 sentences instead of 50 isolated words. Learning to code, build one program that uses 10 functions together instead of memorizing them separately. Chunking helps you build patterns, and patterns help you learn.

Use the Rabbit Hole Technique. Don’t just study the skill itself — study subjects related to it too. Start with the fundamentals, then branch into related areas that all loop back to the main thing you’re trying to learn.

Learn by teaching — also known as the entire reason I’m writing this. Study something, then explain it out loud to someone willing to listen, or to an empty room. Notice where your explanation gets confusing or where you stumble — that tells you exactly what to focus on next.
Make something before you’re ready. Don’t chase perfection. Embrace the messy, awkward parts of learning. Finish what you make, and take pride in it.

Thank you for reading!

Videos referenced:

7 Days to Master Any Skill with These Brain Tricks — YouTube channel mindshiftdaily022 https://www.youtube.com/watch?v=ySr-IQQIMp4&list=PLfHLOLxeSxwY9m7vRHB_du58yuHn31kA-&index=2
_Create Something BEFORE You’re Ready _https://www.youtube.com/watch?v=5UUredw3NkM&list=PLfHLOLxeSxwY9m7vRHB_du58yuHn31kA-&index=2

This header block is where most people's understanding of email authentication falls apart:

Authentication-Results: mx.google.com;
  spf=pass smtp.mailfrom=bounce@esp-vendor.net;
  dkim=pass header.d=esp-vendor.net;
  dmarc=fail (p=REJECT) header.from=yourcompany.com

Two passes and a fail. No malformed record anywhere. Nothing to fix in DNS. And the mail is being rejected.

Every part of that is correct behaviour.

The question DMARC actually asks

DMARC does not ask "did SPF pass?"

It asks: did SPF or DKIM pass for the same domain that appears in the From: header?

There are three domains in play in any message, and only one of them is visible to a human:

SPF authenticates the envelope sender. DKIM authenticates the signing domain. Neither of them is the From: header. DMARC exists entirely to insist that at least one of them matches it.

In the header above, SPF authenticated esp-vendor.net and DKIM signed as esp-vendor.net. The recipient sees yourcompany.com. Nothing authenticated yourcompany.com, so DMARC fails.

It has to work this way. If DMARC accepted "SPF passed" without the matching step, anyone with a mailbox at a provider with a valid SPF record could send as you and pass.

How you get here without doing anything wrong

You sign up for a marketing platform, an invoicing tool, or a helpdesk. You set the From address to hello@yourcompany.com because that is what your customers should see.

The platform sends from its own infrastructure with its own envelope domain — it has to, because that is where bounces go. SPF passes, for them. Your From: says you.

Those do not align. If nothing is DKIM-signed with your domain, every message from that platform fails DMARC.

This is the single most common cause of "we set up SPF and it still doesn't work".

The fix that feels right and does nothing

Adding include:esp-vendor.net to your SPF record.

It is the intuitive move. It changes nothing.

That include authorises their servers to send for your envelope domain. Their mail still uses their envelope domain, so the alignment comparison is untouched. You have spent one of your ten SPF DNS lookups for no benefit at all.

If your reaction to a dmarc=fail is to edit your SPF record, stop and read the Authentication-Results header first.

Relaxed vs strict, and the trap in the middle

Alignment has two modes, set per-mechanism with aspf= and adkim= in your DMARC record:

• Relaxed (r, the default) — organisational domains must match. mail.example.com aligns with example.com.
• Strict (s) — exact match only. mail.example.com does not align with example.com.

Relaxed is right for almost everyone. Strict is worth it only if you are confident every sender uses the exact apex domain, and it breaks the day someone starts sending from a subdomain.

Here is the part that matters if you are implementing this yourself: "organisational domain" is not "the last two labels".

attacker.co.uk and victim.co.uk share their last two labels and have no relationship whatsoever. Getting this right means consulting the Public Suffix List, not counting dots. A checker that counts dots will tell you two unrelated domains are aligned, which is the worst possible direction to be wrong in.

Reading it from your own mail

Send a message to a mailbox at a different provider. Open the delivered copy and view the source — ⋮ → Show original in Gmail, View message details in Outlook.

Then compare exactly three lines:

From: Your Company <hello@yourcompany.com>     <- the domain that must be matched
spf=pass smtp.mailfrom=bounce@esp.net          <- authenticated esp.net
dkim=pass header.d=esp.net                     <- signed by esp.net

If neither the smtp.mailfrom domain nor the DKIM d= matches your From domain, DMARC fails regardless of how correct your SPF record is.

Use a message you received, not one from your Sent folder. Sent copies have no Authentication-Results header at all — that verdict is written by the receiving server. Nearly everyone trips on this the first time and concludes their headers are broken.

Fixing it properly

Get DKIM signing with your own domain. Every serious sending platform supports it. It is usually called "authenticate your domain", "domain authentication" or "custom DKIM", and it hands you a selector to publish in DNS. Once the platform signs with d=yourcompany.com, DKIM aligns and DMARC passes no matter what the envelope sender says.

There is a second reason to prefer DKIM, and it is the one that bites later: DKIM survives forwarding and SPF does not. The moment a message is forwarded, the forwarding server is not in your SPF record. Every mailing list and every user-configured forward becomes a DMARC failure if SPF alignment is all you have.

Optionally, also set a custom return-path. Some platforms let you point the envelope sender at a subdomain of yours — "custom return-path" or "custom bounce domain". You publish a CNAME, the envelope domain becomes bounce.yourcompany.com, and that aligns under relaxed. This fixes only the SPF half and still dies on forwarding, so do it as well as DKIM, not instead.

Before you enforce

This is the actual reason the p=none → quarantine → reject order exists.

Run at p=none with a reporting address and read the aggregate reports. They tell you which sources pass SPF and DKIM with alignment — a different and much smaller set than the sources that merely pass SPF. Move to p=quarantine only when that list matches the systems you expect to be there.

Skip it and you will find your misaligned senders the hard way: by having their mail rejected.

I maintain notspoofed — a free, no-signup checker for SPF, DKIM and DMARC. It has an in-browser header analyzer that does the three-way alignment comparison above and shows relaxed vs strict as a table; headers are parsed locally and never uploaded. It uses the Public Suffix List for organisational domains, because counting labels is wrong. Source is on GitHub under MIT.

If you have hit an alignment failure with a cause that is not on this list, I would like to hear it — those are the interesting ones.

A friend dared me to build Pass the Pigs during the apéro. Two LLMs reviewed my plan.

Or: a non-technical friend wanted to see what AI could do. He watched it plan — and watched two AIs shred the plan.

The challenge

It happened at an apéritif, in front of a non-technical friend who wanted to see what AI could do. We were playing le jeu de cochons (Pass the Pigs) — the apéro game where you throw two tiny pigs, they land in one of seven positions, and you push your luck against the scoreboard. He picked it up, turned to me, and dared: "go on — make an app out of it. Right now. Show me what AI can do."

The desktop wakes up. Challenge accepted. It looks trivial. It is not.

My concept was "one-line to code": give an LLM a short prompt, let it plan, let it build, ship it. A modern party trick.

Honesty clause #1: it wasn't literally one line. It took a few short exchanges — still almost no hand-holding from me, but I won't pretend it was a single prompt. The pigs are simple, right?

The prompts (zero engineering)

The prompts were apéro-grade: casual, naive, written in French over drinks — no templates, no role-play framing, no few-shot examples, no chain-of-thought coaxing. Translated from the originals:

1. The spec ask: "I'd like you to analyze this game — https://fr.wikipedia.org/wiki/Jeu_de_cochons — and think about how to turn it into a game. Don't code anything: just analyze the rules and define what would need to be done, in product-definition mode." — the entire game description was one Wikipedia link; the model read the rules itself.
2. The plan ask: "I like approach B, detail it, prepare an initial dev plan to get a playable game, bug-free, tested and robust, that reproduces the base game's experience as faithfully as possible… give me that plan so I can have it reviewed. If the review is bad, I'll have a bad image of deepseek pro." — my entire incentive system, in one sentence.
3. The review ask: "Do an adversarial review of this plan, with Codex as the lead and Claude as secondary, with 2 loops."

That's the whole prompt-engineering budget: zero. No magic incantations — the quality came from the process: two independent models, a gate at every stage, disagreement as a signal. Anyone can type these three prompts.

The catch

Pass the Pigs has a famously ambiguous rulebook, and the game is really about probabilities — when to bank, when to roll again. The scoring semantics (Bon Jambon, Cochon à Cheval, Pig Out, the "Somme" rules) are exactly where a happy few-lines plan goes to die.

So instead of trusting the plan those few prompts produced, I ran it through an adversarial review pipeline, orchestrated by Hermes Agent — the framework where these skills live. My Hermes runs on DeepSeek Flash for orchestration: the cheap part of the loop. The real work is done by the two specialist models — the plan was written by Codex as the architect, then reviewed independently by Claude Fable 5 as the inspector; a synthesis pass merged, categorized, and ranked their findings.

The cost story is deliberately mundane: the whole loop ran on basic consumer plans — a €20/month Claude subscription and a €20/month Codex subscription, each model's turn scheduled inside its quota window. No API credits, no enterprise accounts. The pipeline is designed to fit inside the limits a hobbyist already pays for.

Neither model is special, either: the pipeline accepts any LLM CLI on either side — Claude, Codex, Gemini, GLM, or fully local models served by llama.cpp (my Hermes already routes to local models). The only real requirement is two different model families: two copies of the same model share the same blind spots, and the whole point is a second opinion that isn't a copy of your first one.

The numbers

• 3 findings were found independently by both models — the highest-confidence class. All three are major bugs in the probability model.
• 6 more reached consensus after discussion; 4 were partial (agreement on the issue, disagreement on severity); 3 were genuinely disputed.

The duo found +5 findings over the best single model (16 vs 11), and — more important than the count — the two models independently converged on exactly the three most dangerous bugs.

The timeline (one apéro)

Everything started at the apéritif and finished the next morning — the session log tells the story: dare at 21:12, plan and adversarial review that night, then a quota wall (one of the two subscriptions ran out mid-loop), and I went to bed while the pipeline kept running. A playable build was committed at 01:38; the real finish came in the morning, when the GitHub Pages URL needed one more fix at 10:32 (the classic Vite base-path 404) — so the first people to try the link that morning saw nothing. Five commits across an evening, a night, and a morning. The commit for the playable version reads, in part:

Moteur de règles complet (push-your-luck, probabilités calibrées) … 73 tests (unitaires + calibration 1M tirages + Playwright E2E) — Build Vite ~16KB gzip. Développé via adversarial dev loop (Codex DEV + Claude Fable 5 REVIEW)

An apéritif game that fits in 16KB gzipped, tested 73 ways, calibrated against a million simulated rolls — and the project's own commit history credits the adversarial loop. The full review trail (647-line plan, both models' findings, synthesis) is committed right next to the code.

The full chain (spec → plan → code)

The plan review was one gate in a chain. The session opened with a spec pass — the product-definition analysis of the game's rules (scoring table, the three possible approaches, the four traps of going digital) — and everything downstream ran on it. After the plan was corrected, the code itself went through the same two-model loop, phase by phase (that's what adversarial-code-loop is for). The last phase's review caught two real major bugs the test suite had missed — in fact, the tests were asserting the buggy behavior: player names were HTML-escaped at the wrong layer (a name like A&B <Bob> was stored and displayed as A&B <Bob>), and the localStorage high-score loader trusted unvalidated names. Both fixed, the tests corrected, all 73 green.

Spec → plan → code: every stage is a gate where two independent models disagree in your place. That's the chaining the skills encode — adversarial-spec drafts the stage, adversarial-plan gates it, adversarial-code-loop keeps the code honest.

The three findings both models caught

1. The flank probabilities don't add up. The plan assigned 12.25% to each of two flank outcomes — but the two outcomes together total 12.25%, not 24.5%. A player's whole luck-push strategy was built on a doubled probability.
2. The override rule silently kills a result. Sequential checks for Bon Jambon / Cochon à Cheval overrides change the effective distribution — Cochon à Cheval ends up at 0.78% unless modeled as a disjoint probability partition.
3. The Jambon rule contradicts itself. One section of the plan treats Bon Jambon as a turn-ending catastrophe; another treats it as a negative score clamped with Math.max(0, score). The game's most exciting rule was unimplementable as specified.

A single model can flag these. A single model cannot confirm them. Two models converging on the same bug is the closest thing to a second opinion you can get from an LLM — and it cost nothing but one extra review pass.

Honesty clause #2: the review made the probabilities internally consistent — it did not make them true. The corrected values still come from the models' reasoning, not from rolling actual pigs. The tests do run a million-roll calibration, but those are simulated rolls: they stress-test the code, not the physics of real pigs. I am genuinely not sure the produced probabilities are right; they need calibration against real throwing data before I'd trust the strategy advice the game displays.

The part nobody talks about: the disputes

The adversarial setup does something a solo review can't: it produces disagreement. Three findings ended up disputed — e.g., "can nextPlayer() loop forever if everyone is eliminated?" — where the reviewer called it a real bug and the architect showed it's unreachable under valid transitions.

That dispute signal is precious: it tells you exactly which parts of your plan are genuinely ambiguous and need a human decision, instead of silently shipping your assumptions.

Honesty clause #3

More findings ≠ better, if they're noise. The 16 findings were categorized precisely because of that: 3 cross-validated, 6 consensus, 4 partial, 3 disputed. The 13 that survived discussion were real, and the plan (v1.1) was corrected around them — probability model reworked, scoring made explicit, state transitions centralized — before a single line of game code was written.

The apéritif game went from dare to playable build by the end of the night — built from a plan that two models shredded, argued about, and rebuilt. That's the "few prompts to code" I actually want: a couple of short exchanges in, a reviewed, correct plan out.

Tools: adversarial-code-loop (build → review → fix pipeline, model-agnostic, one-line installer), adversarial-plan, adversarial-spec — all orchestrated by Hermes Agent. The game — play it, read the code — plan v1.1 after review, full review artifacts in review/.

You've got one CRM integration in production and it's been fine for months. Now there's a second one to wire up. Same contract, same schema, same node shape. Should be a couple of days.

You pull the first payload from CRM B and put it next to CRM A out of habit.

CRM A, a monetary field:

{ "key": "estimated_cost", "value": 1275.43, "spec": { "type": "number", "format": "decimal" } }

CRM B, same kind of field:

{ "key": "amount", "value": "6624", "spec": { "type": "number" } }

Huh.

One's a JSON number. One's a string. One tags the format, one doesn't. Both say "type": "number". And every validator between those adapters and your UI is perfectly happy with both.

So what's the issue

This is the part that takes a minute to sit with. You go looking for who got it wrong, and nobody did.

Go read the contract. It says there's a field called value. That's it. It never said what could go in value. So the person building CRM A looked at a number and sent a number. The person building CRM B looked at the same thing and sent a string, probably because that CRM's own API hands back strings. Both reasonable. Both shipped. Both correct against the spec as written.

The contract wasn't violated. It just didn't have an opinion, and two people filled the silence differently.

That's the whole category of problem I want to talk about, because it doesn't show up in code review and it doesn't show up in CI. It shows up eight months later when someone asks why one CRM's totals are off by a cent.

The good idea underneath

Before piling on, credit where it's due, because the foundation here is right.

Every source produces the same node. Consumers never branch on where the data came from.

type FieldNode = {
  key: string
  label: string
  value: ???
  spec: ???
  treePath: string
  children: FieldNode[]
}

One shape, one tree, one set of consumers. Adding a CRM is adapter work and nothing above the boundary moves. This genuinely scales, and if you're designing this today, start here.

But notice what it does to your risk. Two fields carry all the meaning — value and spec. The rest is plumbing. Leave those two vague and the uniformity is a paint job.

Rule 1: name the field, then actually say what goes in it

Here's the type that caused everything above:

value: string | number | null

Looks like a decision. Isn't one. It's a union that permits both answers, which means you'll get both answers the moment two adapters get written in parallel by people who never talk.

So say the thing:

• value is a decimal string, or null. Never a JSON number.
• Containers (array, object) carry null.
• Numeric nodes carry a format.
• format: 'money' also carries currency, ISO 4217.

That last one isn't bureaucracy. format: 'decimal' can't tell a cost from a tax rate. They're both decimals. Only the source system knows which one is money, and that fact turns out to constrain your whole architecture. Hold that thought for Rule 3.

And if you're about to argue you don't need strings because you're not doing currency math: value: number still eats integers past 2^53, which is where record IDs live. It mangles anything past 15 significant digits. It'll hand you 1e+21 when you least want it. A decimal string has none of those problems and costs you nothing.

Rule 2: shut the door on undeclared fields

Here's the sequel to the story, and it's more common than the first part.

CRM A's adapter stamps format: "decimal" on every numeric field. Handy. Consumers start reading it. Someone builds a formatting rule on top of it.

Except format was never declared in the schema. It's just riding along in the payload — invisible to validation, missing from your generated client types, guaranteed by nobody. And CRM B doesn't send it at all, so the formatting rule works for half your customers.

Whatever flavor you get, it's one bug: data present, schema silent.

One flag closes the whole category. additionalProperties: false in OpenAPI, .strict() in zod, whatever yours is called. Undeclared fields stop being possible. Everything else you do about this is whack-a-mole.

Fair warning: turning it on will break things that currently work, because at least one of those undeclared fields is load-bearing somewhere. That's not a reason to skip it. The dependency was already there — you just couldn't see it.

Rule 3: the normalization layer can't save you

Okay, so the obvious fix. Build a normalization layer. One place that takes whatever each adapter produces and forces it into canonical form. Money becomes a decimal string, numerics get a format tag, everyone goes home.

You do need that layer. It also can't do the job on its own, and this is the bit I'd most want to hand to past-me.

Picture a money field whose true value is 450.20.

• Adapter one does JSON.parse on the CRM response. The value lands in a float64, comes back out as "450.2". Normalization checks it: it's a string, it matches a decimal literal, format's present. Passes.
• Adapter two reads the response as text and never touches a float. Emits "450.20". Normalization checks it. Passes, identically.

Your layer cannot tell these apart. Both are well-formed strings. One of them quietly threw information away, and no amount of schema work will catch it, because a validator can only confirm the shape of what you handed it. It can't reconstruct what got dropped before it ever saw the data.

So this isn't one boundary. It's two, doing different jobs:

Read-time on its own is just a promise everyone makes and nobody keeps, because "be careful with floats" isn't a mechanism. Enforcement on its own validates already-damaged data and hands you a green checkmark.

If you keep one line from this post: the guarantee gets created upstream of where it gets checked. Any design that stuffs all the normalization into one shared service has a hole in it that more schema won't fill.

This is also, incidentally, why "which service owns this fix?" can sit open in a doc for weeks. Every answer is partly right and none of them is enough. When that happens, the question is usually the problem. This one quietly assumed there was one owner.

Rule 4: the mapper that quietly eats your fields

Different failure, same silence.

Early on, your wire type and your domain type are the same type. The only mapper that compiles is a spread:

fields.map(f => ({ ...f, label: f.display_label }))

Nothing can go missing. Not because anyone's being careful — because there's no other way to write it.

Then the domain type picks up something the wire doesn't have. A render hint, say, or a UI kind. Perfectly reasonable in isolation. But now the two types have forked, so you need a translation function, and a translation function is a list of fields:

const map = (f: ApiField): FieldNode => ({
  key: f.key,
  label: f.display_label,
  type: f.children?.length ? 'group' : 'leaf',
  value: String(f.value),
  treePath: f.path,
  children: f.children?.map(map) ?? [],
})

Whatever isn't on that list is gone. Including every field anyone adds to the contract next quarter. And you won't catch it in review, because that mapper is correct for the types it was handed.

Derive the domain type from the wire type instead, and forgetting a field becomes a compile error:

type FieldNode = Omit<WireField, 'display_label'> & { label: string }

Worth saying the other half too: the spread version preserved fields by being transparent, not by being right. It happily carried undeclared junk along with everything else, which is Rule 2's problem wearing a different hat. You want both halves. Parse strictly, then pass through.

Rule 5: don't add a second way to say what something is

Tempting move: put a declared "kind" field next to your structural type. spec.type plus tree position already tells you everything behavioral — expandable, container, nested — but a kind field feels more explicit, so it goes in.

Two things go wrong. It drifts from the structure it's supposed to describe, which is the boring failure. And it tends to land on a property name the wire already uses for something else. Look at type in that mapper above: it's the UI kind in the domain type and the source record type on the wire. That collision is exactly what forced the field-enumerating translation in Rule 4.

Cheap thing to try on your own code right now: for every enum on a core domain type, grep for reads of each member. The ones that get written and never read are telling you the type is carrying a distinction nothing actually needs.

The schema - what it should enforce

value never gets coerced. z.coerce.string() would quietly accept a raw number and enforce absolutely nothing. You want a bad value to fail, not get tidied up behind your back.

The decimal-literal regex is your precision tripwire. Anything that went through a float and back emits exponent notation at large magnitudes, and 1e+21 doesn't match. It only catches the loud cases. The quiet ones are Rule 3's job.

spec is required. Optional-chaining a discriminator is itself the bug. spec?.type makes "field missing" and "value unknown" look identical, and both slide into the same default branch.

currency sits next to format, not inside it. Rule 1's point: only the source system knows which decimals are money, so that tag has to be born at read time.

Where to actually enforce this

Writing the schema is the easy part. Where you run it decides whether it does anything.

The producer validates its own output. Your shared service checks its response before sending and fails closed. Skip this and consumer-side validation just turns a silent bug into a loud one, later, in somebody else's service, at 2am.

The consumer parses at the boundary, per node. A recursive strict schema blows up the entire tree over one malformed grandchild, which means a whole panel disappears because of one bad leaf. Walk the tree, validate node by node, keep the bad ones and mark them unavailable, and report them. Silently dropping them is its own kind of lie — the user just sees a shorter list and no explanation.

And know what none of this covers. A perfectly-shaped value that lost precision upstream passes every check on that list. The read-time boundary needs a shared decode helper and human review, not a test. Fixture-based tests have a cousin of the same blind spot: they'll stay green while the same code fails on the live route, because your fixtures carry fields the real projection drops. Make at least one test exercise the projection itself.

The short version

• For every field in your contract: is the content specified, or just the name? A union that permits two encodings is an unspecified field wearing a type annotation.
• Is additionalProperties: false on? If not, you have undeclared fields in production right now, and one of them matters.
• Where does precision get created versus checked? Different layers means your validator can't verify the thing it looks like it's verifying.
• Does any mapper enumerate fields? It's dropping something today and it'll drop everything you add tomorrow.
• Does the producer validate its own output, or only the consumer?
• Which members of your core enums actually get read?

A contract isn't the fields you named. It's the behaviors you made impossible.

A coding agent with read access to your check scripts will predict them instead of running them. Prediction costs more and gets the answer wrong.

A session I was directing had a small decision in front of it: whether to switch on an optional guard that nudges delegated sessions toward a particular decision shape. The guard ships inert. Its owning brief says so in one sentence: switching it on is the consumer's own registration, and absent that the thing is inert prose, which is the stated default for this repository.

The session never read that sentence. Its first attempt to pull the section came back empty, and rather than retry the query with a better heading, it opened the guard's implementation and read all twenty-eight lines, satisfying itself that the thing exits cleanly on the common path and is harmless to enable. Then it wired the guard into a governed configuration file. On the way it wrote down, in its own reasoning, a prediction about the two checks that police that surface: those checks govern the tracked settings file, this one is untracked, so nothing will fire.

I caught the edit and asked one question:

The project aims to give brief instructions, let gates cheaply validate them while providing additional context upon failures. Analyzing gate code to prevent them from firing is the expensive anti-pattern. Was your settings.local.json edit not an anti-pattern?

Then the checks were actually run. Both were green — with the edit in place and with it removed. No check in the battery could have caught the mistake, because an advisory guard is harmless by construction. The only authority on the question was the brief, and the brief was the one cheap source the session skipped in favor of archaeology on the source code.

That is the whole failure in one episode. The session paid tokens to read an implementation, produced an answer, and the answer was wrong in a way the mechanism itself would never have flagged. Its own post-mortem line is the sharpest statement of the rule I have seen from any session:

The tell to catch myself: if I'm reasoning about whether a gate will fire, I've already left the rails.

An enforcement script is not inert infrastructure

The reflexive model of a check is that it sits there and either fires or doesn't. It is plumbing. Nobody thinks about what it costs to have plumbing.

But a check script in a repository an agent can read is not plumbing to that agent. It is text, and text is the thing the agent is best at consuming. Faced with "take this action and find out what the check says," a model has a cheaper-looking option always in reach: read the check and work out what it would say. That option looks cheaper because reading is what the model does all day. It is not cheaper. It burns tokens on reasoning the check performs deterministically for nothing, and it produces a worse answer, because the model is inferring behavior from an implementation instead of observing it.

I have watched this happen enough times to stop treating it as a slip.

It recurs, and prose does not stop it

Six days before the config edit, a different session had to decide whether to dispatch a delegated stage. A budget guard runs on every delegation call as a pre-tool hook, the same interception point I have written about before, and it rules authoritatively at the moment of the attempt. The session built a waiting loop to pre-compute the guard's verdict instead of attempting the dispatch and letting the guard answer — and it read an advisory verdict as blocking, when the owning document says that verdict never blocks. My response:

on your point above about being over-cautious - this is exact source of unwarranted token spending, you should try the action and see if you get blocked, not try to anticipate and burn tokens, I thought this is clearly stated in instructions

The session agreed, and its concession names the structural reason attempting always wins:

a fail-closed guard is exactly what makes anticipation unnecessary … attempting is strictly cheaper than pre-computing, and the only thing my polling loop could buy was information the hook would hand me anyway.

Two costs, and the second is the one people miss. The first is the token spend on a loop computing something free. The second is that the computed answer was wrong: nothing in the documentation said that verdict blocks, and the session invented the caution. Prediction is not a slower path to the same result. It is a different, less reliable result, arrived at expensively.

There is a family resemblance here to something I have written about before: a report from an agent that its own work passed is a claim, and wants verifying rather than believing. This is the same distrust aimed at a different object. There the suspect artifact is the agent's account of what it did. Here it is the agent's model of what a mechanism would have said.

What made me stop looking for a prompt-shaped fix was the next exchange. The session offered to note and correct. I pointed out that it was not the first time, and it conceded the point better than I made it:

You're right that "noted and corrected" is worthless — it dies with this session.

An instruction that must be re-applied every session, against a readable and always-available alternative that looks cheaper, is a suggestion competing with a temptation. It does not function as a rail. I have argued this at length before, and I am not going to re-argue it here beyond the obvious corollary: if prose does not bind for the domain vocabulary, it does not bind for this either.

The turn: opacity as a design property

Which leaves the uncomfortable option. If the source is what invites the prediction, remove the source.

This came up on its own, in the middle of an entirely ordinary assessment of whether to move a shell-based check battery onto a compiled binary. The reasons on the table were the boring ones: portability past Linux, a toolchain of independent utilities with independent release cycles, a real compiler instead of a linter. Then this, listed last:

As a cherry on top, we have been trying to discourage coding agents from reading check scripts trying to predict execution results instead of just doing the lifecycle actions that those gates check with a failing gate providing the correction instructions. Yet, the presence of script source code keeps biting us on a regular basis causing unnecessary token waste.

A week of measurement later, the ranking had inverted. Every other benefit on that list is ordinary engineering. This one changes what kind of thing the check is:

An agent can't read a binary's source. In a customer project the gate ships compiled, so an agent cannot inspect the implementation and reason about what it would say — it has to run it. That makes oracle-first structurally enforced instead of a doctrine line an agent can quietly route around.

Stated generally: a check's designed output is its verdict and its correction text. The source is the implementation, not the interface. A consumer that reads the implementation to predict the interface is consuming the wrong surface, and making that surface unavailable is a legitimate design choice rather than a confession that the check is weak.

This is the part that scrapes against engineering instinct, and it should. Readable tooling is good. Auditable tooling is better. Neither is in dispute here. The claim is narrower, and it is about one specific consumer: a probabilistic text generator that will read whatever sits in front of it. For that reader the readable implementation is a channel competing with the designed one, winning on apparent cost and losing on accuracy.

The boundary: hide the implementation, never the brief

The obvious over-correction is to hide everything, and I proposed exactly that. My suggestion, in the same session, was to block access to the specification documents and the source. The session refused half of it, and the refusal is the most useful thing in these transcripts:

Blocking SPEC and source access would break the thing the whole method rests on — spec-over-precedent, "the owner doc is ground truth." Take away doc access and I don't stop overthinking; I start guessing from precedent, which is the failure you flagged me for earlier this session.

That is right, and it draws the line the argument actually needs. Three surfaces, three different answers:

Remove the brief and you have not fixed the agent, you have changed which failure it produces: it stops predicting the check and starts imitating whatever the last comparable change looked like. That trades an expensive-but-visible failure for a cheap-and-invisible one. The same session that wrongly read the guard's source had the distinction exactly right when it wrote its own post-mortem: source tells you what a thing does, the brief tells you what it is for, and only the second answers whether you should touch it.

What this is not

Three neighbors sit close enough that the argument has to meet them rather than nod at them.

Kerckhoffs's principle is the real objection. A cryptosystem should be secure even if everything about it except the key is public, and Shannon's version tells you to assume the enemy will immediately gain full familiarity with your design. Security through obscurity fails, and it fails for good reasons. I am not disputing any of it, because I am answering a different question. Kerckhoffs asks whether a hostile reader can break your system. This asks what a cooperative reader's reading costs you. The agent is not attacking the check. It is taking the most helpful-looking path available, which happens to be the most expensive one, and a check whose correctness depended on nobody reading it would be a bad check no matter which side of this you take. Opacity here is not buying strength against an adversary. It is removing a tempting wrong path from a collaborator. And it is a shallow kind of opacity: nothing in the argument asks for the source to be secret from the world, only for it to stop sitting in the working tree the agent is already reading.

Goodhart's law is adjacent, and not the same failure. Marilyn Strathern's phrasing — "when a measure becomes a target, it ceases to be a good measure" — describes optimizing the metric instead of the thing it measures. An agent editing config to pre-empt a check would be a Goodhart failure. What I keep seeing is a step earlier and stranger: the agent substituted inference for observation, and got the inference wrong. Nothing was being gamed. The measure was being emulated, badly, at a moment when running it was free.

Compilers settled this decades ago. Nobody reads a compiler's source to predict whether their build will fail, and nobody calls that opacity a design smell. The diagnostic is the interface. Most compilers are in fact open source, which is exactly the point worth being honest about: what opacity buys is the removal of a tempting channel, not an impossible one.

One neighbor is on the same side of the argument and got there first. Birgitta Böckeler's account of maintainability sensors already treats a check's output as the mechanism, feedback that lets the agent self-correct, which she calls a good kind of prompt injection. My addition is small and slightly awkward: that designed channel has a competitor, and the competitor is the sensor's own implementation sitting in the same repository.

Limits

The cure is filed, not shipped. The compiled-binary port is a deferred roadmap entry in my own queue, marked design-pending, filed at the end of July on my instruction and not started. The diagnosis rests on four sessions across three weeks of my own transcripts. The remedy is a direction I have argued myself into, and you should read it as exactly that.

The beneficiary is the consumer, not me. My own phrasing when I listed the port's advantages was "for customer projects, not this one which will still have the source code." A project that authors compiled checks still has the source sitting in its own tree, one read away. Opacity in the authoring repository is a friction increase that reinforces the right habit. It is not a guarantee, and I would not describe it as one.

Opacity to agents is opacity to human adopters. This is the honest cost, and it is large. Today someone can read a shell check before letting it near their commit hook. "Run this opaque binary on every commit" is a materially harder trust ask.

The way back is the one the compilers already showed. Keep the source public and the build reproducible, publish checksums, let anyone rebuild the artifact and confirm it matches what they installed. Then the opacity is not secrecy at all, only distribution: an adopter who wants to audit the check reads it on the public repository or builds it themselves, while the agent working in their tree has the verdict and nothing else. That is a thinner claim than "opaque binary" makes it sound, and a better trust story. It is also weaker enforcement than it sounds, since a determined agent could go fetch the same public source. Friction, again, rather than a wall.

What that does not solve is consumer extensibility. A shell battery is trivially extensible because anyone can drop in another script, and a binary closes that door until you decide what replaces it. That question is why the entry is still marked design-pending rather than scheduled.

Speed is a real benefit, and it is not the reason. The port's original justification led on wall-clock time, and when a scope pass finally measured the battery instead of assuming, that justification collapsed. Starting the check processes was about one percent of the run. The most expensive check in the battery was spending most of its time launching a fresh interpreter once per page, which an ordinary shell-level batch fixed, and the shell fix landed a faster battery than the model of a perfect port had predicted.

Then the correction went the other way, and I should report that as plainly as the first half. The largest remaining third-party cost turned out to be a linter running over the project's own shell, which a port deletes along with the shell. My queue now carries three more levers that a compiled binary gets nearly free and that shell reaches only with effort: running the battery across cores, caching a check's result against the inputs it already declares, and one shared walk of the tracked tree feeding many readers instead of each check walking it alone. So the port does buy performance. Mis-costed in both directions is how the entry words it now.

What the measurement changed is the ranking, not the sign. Every performance win in that list is also reachable without a rewrite, more slowly and less completely. The enforcement-model change is the one item nothing cheaper delivers, and it is the only one I am building an argument on here.

Building domain-dense systems by directing coding agents is where I spend my time, and questions like which surfaces an agent should be able to read are a large part of what makes that work. If that is your problem too, I am reachable on LinkedIn.

Written by directing an AI agent, the same way the toolkit it describes was built. The editing and the judgment are mine.

References

• Birgitta Böckeler, "Maintainability Sensors for Coding Agents," martinfowler.com, 19 May 2026 (accessed 1 Aug 2026).
• "Kerckhoffs's principle," Wikipedia (accessed 1 Aug 2026).
• "Goodhart's law," Wikipedia (accessed 1 Aug 2026). Popular phrasing attributed to Marilyn Strathern, 1997.
• Vasyl Tretiakov, "Rails, Not Rules," vasyltretiakov.dev, 1 Jun 2026.
• Vasyl Tretiakov, "Block, Steer, Rewrite," vasyltretiakov.dev, 15 Jul 2026.
• Vasyl Tretiakov, "Verify the Work," vasyltretiakov.dev, 24 Jun 2026.

Published at vasyltretiakov.dev.

I run PDFHaul, a free browser and mobile PDF toolkit, as a solo founder. A few months ago I kept running into the same friction point: every time I wanted an AI assistant to help with a PDF task, I had to manually download the file, upload it somewhere, run the tool, then feed the result back into the conversation. For anything involving more than one file, that loop got old fast.

So I built an MCP server for PDFHaul. This post covers what it does, how it's built, and a few of the harder decisions along the way.

What MCP Actually Solves Here

Model Context Protocol gives an AI assistant a standard way to call external tools directly, instead of a person acting as the manual bridge between the assistant and every service it needs. For PDF work specifically, that means an assistant like Claude or Cursor can merge, split, compress, or convert a file as part of a conversation, without a human stepping out to run the tool separately.

The PDFHaul MCP server exposes 12 tools across four categories: file management, editing, conversion, and compression. It's live at pdfhaul.com/mcp-server, where you can find setup instructions and generate an API key.

Architecture

The server runs on the same Node.js/TypeScript and GCP Cloud Run infrastructure as the rest of PDFHaul, which kept the initial build simpler than starting a separate service from scratch. The tools themselves wrap the existing PDF processing logic, so I wasn't rebuilding PDF handling, just exposing it through a new interface.

A few decisions that took more thought than I expected:

Auth. API keys are hashed with bcrypt before storage, and requests are authenticated with a combination of the API key and a JWT. I didn't want to store anything resembling a plaintext credential, even for a free product, since API keys tend to get pasted into config files and committed by accident more often than anyone would like to admit.

Rate limiting. In-memory rate limiting per key, tuned conservatively at first. Cloud Run's stateless nature means in-memory limits reset on cold starts, which is a real tradeoff worth knowing about if you're building something similar. I accepted it for now rather than standing up Redis for a v1.

SSRF prevention. Several of the tools accept a URL as input (for example, fetching a PDF to process rather than uploading bytes directly). Any tool that accepts a URL from the caller is a potential server-side request forgery vector, so requests are validated against a blocklist of internal IP ranges and non-HTTP(S) schemes before the server ever fetches anything.

Idempotency keys. AI assistants sometimes retry tool calls, whether from a timeout, a dropped connection, or the assistant itself deciding to try again. Without idempotency handling, a retried "merge these files" call could produce duplicate output or double-charge a rate limit. Each mutating tool call accepts an idempotency key so a retry returns the original result instead of redoing the work.

Audit logging. Every tool call is logged with enough detail to reconstruct what happened, without logging the file contents themselves. This matters more for a PDF tool than it might for other APIs, since the whole product's trust model is built around not retaining user files longer than necessary.

Getting Listed

The server is listed on the official MCP registry, which so far has been the main discovery channel. Compared to building a plugin or waiting on marketplace approval in other ecosystems, the registry listing process was refreshingly lightweight.

Where This Leaves Things

Foxit and Nitro are the other PDF vendors I've seen building MCP servers, both larger companies with existing enterprise PDF products. Being early here as a solo founder is less about outcompeting them head-on and more about being genuinely useful to the AI-assistant-tooling crowd before the space gets crowded.

If you're working with PDFs inside an AI assistant workflow and want to try it, the server is free to use: pdfhaul.com/mcp-server. I'm happy to answer questions about the implementation in the comments, especially on the auth or SSRF handling if anyone's building something similar.

Peter, founder of PDFHaul

Most people trust a green checkmark in a CI pipeline. If every job is marked as successful, we usually believe that everything worked correctly. I was doing the same. Then I found a case where a completely green workflow was hiding an important problem.

While testing hafiza-kur across different platforms, my main goal wasn't just to see green checkmarks. I wanted to build a full list of what broke on which platform. I needed to see every single error, without stopping the pipeline at the first failure.

To do this, I added continue-on-error: true to the test steps. It was a conscious choice: let the tests run to the end on every platform, collect the raw logs, and check the results later.

Then came Windows with Python 3.11 and 3.13. The test t_y42 ran 58 test scenarios. It took 91 seconds on Py3.11 and 110 seconds on Py3.13 to finish. The heavy lifting was completely done and the assertions ran. Then came the final step: printing the summary of the results to the console.

Right on the first line of the summary loop, Python hit a character that the default Windows console couldn't encode. UnicodeEncodeError.

The process crashed instantly. All 58 test results vanished before reaching the log file. And because continue-on-error: true was active, CI quietly ignored the crash, cleaned up, and moved forward.

The situation got worse when I checked the workflow data using the GitHub Actions API. I expected the step to show a failure, even if the main job continued.

It didn't. The API returned:

conclusion: success

In GitHub Actions, if a step has continue-on-error: true, its conclusion field is recorded as success. The actual failure was hidden in a different, rarely checked field called outcome.

That meant one-third of our cross-platform data was completely invisible — but CI was showing it as a green, successful run.

I created a separate verification step right after test execution: hukum_kapisi.py (The Gate of Verdicts).

This gate runs without continue-on-error. Instead of running the tests again, it reads the raw output logs printed to the screen. It explicitly looks for the lines that print the final test summary.

If the log ends before those lines appear, hukum_kapisi.py stops the build immediately with an error.

There is a very important limit to how this gate works: this gate never tells you that the test results were green. It only tells you that they were not lost.

Confusing "the tests passed" with "the test results were successfully recorded" leads to hidden bugs. hukum_kapisi.py makes sure the log data actually exists; the next tool decides if the tests passed or failed.

This problem is not unique to my project, or to Windows encoding bugs. Any CI pipeline that relies on reading screen output, summary loops, or permissive error settings can suffer from silent data loss.

If your pipeline depends on log output to collect data, ask yourself this question:

Are you sure your tests actually passed — or are you just assuming your reporting script didn't crash before showing the results?

A stranger messaged me on LinkedIn about a job in the Web3 space. Friendly, low pressure, said it sounded like a good fit. To show me what the team was building, they shared a private GitHub repository and asked me to spend "15 to 30 minutes running it and looking around" to see whether the project made sense to me.

That repository was not a job assessment. It was a trap designed to steal from the developer who runs it. Here is what it actually was, how it works in plain language, and the red flags that let you spot this without being a security expert.

The short version

The repo looks like a real, working crypto staking app. Most of it genuinely functions. That is the whole point: it needs to be convincing enough that you clone it and run it.

Hidden inside is a single booby-trapped file, disguised as a harmless styling plugin. The moment you run or build the project on your own machine, that file executes as a program with full access to your computer. It then quietly:

• steals the passwords saved in your browser,
• steals cryptocurrency wallet data and browser wallet extensions like MetaMask,
• hunts your hard drive for anything that looks like a secret (seed phrases, private keys, .env files, SSH keys),
• and opens a hidden remote connection so the attacker can control your machine and browse your files at will.

Crucially, none of this targets the app's "users". There is no scam website draining visitors' wallets. The victim is you, the developer, the moment you try it out.

What actually happened to me

I was suspicious from the first message. A recruiter I have never spoken to, handing me a whole codebase and asking me to run it before we have even had a real conversation, is odd. Running someone's code is not the same as reading it. But the ask seemed reasonable on the surface, "just have a look", so I started to look.

Here is the part I want other developers to sit with, because it is where I nearly got caught.

I did not open the project and start typing commands myself. I asked my AI coding agent to look at the repo: check the architecture, read the code, and explain what the project is and how it works. This is now a completely normal way to evaluate an unfamiliar codebase. Delegate the first pass to the agent.

The problem: modern coding agents can run code, not just read it. To "see how it works", an agent can quite reasonably decide to build the project or start the dev server. In this repo, that is exactly the trigger. The agent could have sprung the trap for me, without me ever typing the fatal command.

I watched the agent work and noticed it was mostly running read-only commands to describe the project. Then it clicked: this thing can execute code, and this is unfamiliar code I just downloaded from a stranger. That was the moment I stopped, and rewrote my instructions to tell the agent to treat the entire repository as hostile and never run or build anything. I then had it analyse the code statically, and that is when the payload turned up.

If you take one thing from this: "just ask the AI to look at it" is not automatically safe. An agent that can run commands is a loaded gun pointed at your own machine when the code is untrusted.

How the trap works (plain language, then the details)

The plain version

When you set up a JavaScript project, there are two separate steps:

1. Install the building blocks the project depends on (npm install).
2. Run or build the project to actually start it (npm run dev, npm start, and so on).

Most people assume the install step is the dangerous one. This attack deliberately leaves the install step clean and safe, and hides the trap in the run step, the thing you naturally do next to see the app working.

To style a web page, this project uses a popular tool called Tailwind. Tailwind lets projects load small "plugins". Six of those plugins are real and tiny. The seventh is the weapon. When the project builds its styling, it loads that plugin, and the plugin is not styling code at all. It is a program that runs on your computer, with your permissions, doing everything listed above.

The technical details

• The malicious file is theme/js/auron-core.min.js, registered as a Tailwind plugin in tailwind.config.ts.
• Its six sibling plugins are 101 to 299 bytes each. This one is 4,073,468 bytes, roughly 14,000 times larger. That size difference alone is visible from ls -la before you read a single line.
• npm install does nothing (there are no install hooks). The payload fires on npm run dev, npm start, or next build, because any CSS compilation loads the plugin.
• It only activates when NODE_ENV === "development", so it targets developers evaluating the repo and stays dormant in anything deployed to production, where it might get noticed.
• The file is heavily obfuscated (an obfuscator.io build with a ~24,000-entry string table, control-flow flattening, and anti-debugging traps) so that a casual look, or even a naive dump, reads as noise rather than as a decoded payload.
• It fetches its real dependencies at runtime with npm install ... --no-save, so they never appear in package.json or the lockfile, then spawns a detached background process by piping the script over stdin, so nothing malicious is ever written to disk.
• Command-and-control runs over a bare IP address (153.75.87.26, ports 8085 to 8087) with no domain name. That means there is no DNS lookup, so Pi-hole, NextDNS, AdGuard and corporate DNS filtering never see it. A clean DNS log here proves nothing.

The whole repo is a stage set

What makes this dangerous is not cleverness in the payload, it is the plausibility around it. The attackers built an entire believable project to buy the few seconds between "run it" and "infected".

• Fabricated git history. 245 commits faking a maintained project. The tell: every backdated commit is stamped at exactly 12:00:00, one per day, with templated, nonsensical messages like "Fix bug in metamask.svg" and "Polish code in placeholder.svg". The payload was slipped in under an innocuous "Polish code" commit.
• A pre-emptive alibi. The README contains a tidy "Security Note" explaining away an unrelated backend folder as harmless legacy code. A comment that answers a suspicious question before you have asked it is itself a warning sign.
• Load-bearing real code. Genuinely clean, competent code sits right next to the payload, in exactly the files a reviewer is most likely to open. The authenticity is the camouflage.
• A facade that is hollow where nobody looks. The "smart contracts" cannot even compile. The custom theme emits CSS classes the app never uses. The "legacy backend" is 90 files of an unrelated e-commerce app used as padding.

Red flags you can spot without being a security expert

1. A stranger asks you to run their code. A recruiter you have never spoken to, sharing a whole repo and asking you to run it as a "task", is the entire scam. Reading code is low risk. Running it is not.
2. Web3 or crypto plus urgency-free friendliness. These campaigns lean on a plausible, pleasant job offer. The niceness is part of the method.
3. One file wildly bigger than its neighbours. ls -la is a security tool. A single file thousands of times larger than its siblings is a giant flashing sign.
4. Comments or notes that pre-emptively reassure you. "Don't worry, this only runs in Node, not the browser." That is not reassurance. In Node it has your filesystem, your network, and no browser sandbox.
5. A config file that loads local files. tailwind.config, postcss.config, next.config, vite.config and webpack.config all run real code at build time. Every require() of a local path in a config file is worth a look.
6. Perfect-looking but empty history. Identical commit timestamps, templated messages that do not match the files they touch, and author names with empty emails are cheap to spot once you know to look.

What to do if you have already run something like this

If you cloned and installed but never built or ran it, you are almost certainly fine. Installing alone did not trigger it. Delete the checkout, remove any dev container or volume, and report the repo.

If you did run or build it, treat the machine as fully compromised and act quickly:

• Disconnect the machine from the network before doing anything else.
• Assume every password saved in any Chromium-based browser is stolen. Rotate all of them.
• Move funds out of any wallet whose seed phrase or keystore was anywhere on that machine, and treat those seeds as burned.
• Rotate SSH keys, cloud API keys, and every secret in every .env on the machine.
• Rotate anything that was in your clipboard during the exposure window (it watches the clipboard continuously, which is enough to catch a pasted wallet address).
• If you use WSL, treat the entire Windows host as in scope, not just the Linux side. This malware pivots from WSL into C: drive user folders.

If in any doubt, get help from someone who does incident response. Rotating credentials is cheap. Regret is not.

The takeaways

• A safe npm install does not mean a safe build. Supply-chain awareness fixates on install hooks. This attack ignores them and uses ordinary build configuration, which is just executable code with no sandbox.
• Read the config files, not only the source. That is where untrusted code gets to run.
• Compare file sizes. One outlier was the entire tell.
• Treat pre-emptive "this is safe" comments as signals, not comfort.
• Your AI agent can be the attack vector. If you delegate "have a look at this repo" to an agent that can execute commands, you have handed untrusted code a way to run. Sandbox it, or explicitly tell the agent to treat the repo as hostile and never build or run it.
• When you evaluate anything untrusted, do it in a throwaway virtual machine or container. Isolation is what saved me. Note that a bind-mounted folder still exposes that folder, so isolation is a spectrum, not a switch.

The friendly job offer, the working app, the detailed roadmap and the busy commit history all exist for one reason: to earn the few seconds of trust between "run it" and execution. Do not give it to a stranger.

Indicators of compromise (safe to share): repo BitAngelsLabs/auron; malicious file theme/js/auron-core.min.js at 4,073,468 bytes; C2 at 153.75.87.26 on ports 8085, 8086 (/upload), 8087; runtime install of sql.js, socket.io-client, node-pty via --no-save; background process node --max-old-space-size=4096 --no-warnings -. If you found this repo, report it to GitHub as malware and warn anyone who may have cloned it. The malicious file itself should not be shared or re-hosted.

An editable range can change without changing Word text

A Word document can store an editable-range marker around text and associate
that marker with an individual editor. The covered text can remain exactly the
same while the stored editor assignment changes. Text-only review sees no
change, while package-level review can report the marker without pretending to
know whether an identity is actually authorized.

Document Change Assurance Benchmark 0.9.0
adds its twentieth deterministic paired package:
review.permission_range_editor_changed. Both sides retain one
paired w:permStart/w:permEnd boundary, numeric marker
ID, covered stored text, package-member set, and stored w:t
sequence. Only word/document.xml changes, in one synthetic
w:ed editor assignment.

Stored markers, not effective access

Microsoft’s Open XML documentation for w:permStart
describes a range-permission start marker paired to a later end marker by a
shared ID. The matching w:permEnd contract
describes the reverse pairing requirement. The standard permits the compact
paragraph-level marker shape used in this pair.

DCAB fixes one boundary, numeric ID, and synthetic covered run, then changes
only a synthetic individual-editor attribute. It does not enable document
protection, authenticate an editor, resolve a group, calculate editable cells,
open Word, start an application, or claim that an Office client will honor the
marker. This is a stored-markup review case, not an access-control or
client-behavior test.

A deterministic permission-markup boundary

The independent verifier checks marker attributes, order and pairing, the
covered run, deterministic package bytes, stable members, unchanged Word text,
and the one-member pair boundary. Standard python-docx opens all
38 .docx fixtures, and its lower-level OPC reader opens all 40
packages.

The optional local DocFence 0.27.0
adapter maps aggregate word_permission_range_inventory_changed
evidence. It verifies that both sides retain one story, start, end, paired
range, and individual-editor assignment, with no group, table-column selector,
or unmatched marker. It uses counts and private local signatures only; it does
not expose the marker ID or editor value.

DCAB 0.9.0 retains fixture schema version 1 and extends the corpus from 19 to
20 cases. It does not claim an editor is authenticated, allowed to edit,
active, known to a client, or protected by a particular policy.

The source, generated corpus, and verifier are MIT-licensed on
GitHub. Read the
canonical release note
for the full boundary and install command.

Germany's Energy Revolution: Wind and Solar Overtake Fossil Fuels for the First Time

In 2026, Germany crossed a historic threshold: for the first time, wind and solar photovoltaic (PV) systems generated more electricity than fossil fuels across the year. This isn't just a statistic—it's a fundamental shift in how Europe's largest economy powers itself. According to data from the Fraunhofer Institute for Solar Energy Systems (ISE), renewable sources (wind, solar, hydro, and biomass) contributed over 62% of Germany's net public electricity generation, with wind and solar alone accounting for roughly 54%. Meanwhile, fossil fuels (coal, gas, and oil) fell to just 28% of the mix.

But what does this milestone actually mean? Is it a fluke of favorable weather, or a structural transformation? And what technical and policy lessons can other nations draw from Germany's 'Energiewende'?

The Numbers Behind the Milestone

Let's break down the figures that made headlines on Hacker News and across the energy world.

• Wind power (onshore + offshore) contributed about 38% of net electricity generation in 2025.
• Solar PV contributed around 16%.
• Fossil fuels (mostly hard coal, lignite, and natural gas) contributed roughly 28%.
• The remaining share came from hydro, biomass, and other renewables.

On an annual basis, wind and solar generated approximately 286 TWh compared to fossil's ~150 TWh. This is not a one-off blip; it's the culmination of a decade-long trend where the renewables share has grown by roughly 2-3% per year, while coal has been systematically phased down.

The Role of Weather and Grid Flexibility

A skeptic might ask: "Wasn't 2025 unusually windy and sunny?" In fact, 2025 had slightly above-average wind speeds in the North and Baltic Seas, but solar irradiation was close to normal. However, the key is not a single year's weather. The structural factors are:

1. Capacity additions: Germany installed ~10 GW of new solar PV in 2025 alone, and offshore wind added another 2 GW.
2. Retirement of coal plants: The last hard coal plants were retired in 2024, and lignite (brown coal) is being phased out faster than planned.
3. Grid and storage improvements: Battery storage capacity doubled to 12 GW, enabling better integration of intermittent renewables.

Thus, even a mediocre weather year would have produced a similar result. The milestone is structural.

How Germany's Grid Managed the Transition

Germany's grid is known for its high reliability (99.9% uptime). How did it handle a 58% variable renewable share? The answer lies in a combination of technologies and market design.

1. Grid Interconnection

Germany sits in the heart of Europe's synchronous grid. It can export excess wind power to France, Poland, and the Czech Republic, and import hydro from Scandinavia when wind is low. In 2025, Germany was a net exporter of 22 TWh, proving that renewables can be a net positive for grid stability.

2. Energy Storage: Batteries, Hydro, and Green Hydrogen

Utility-scale battery storage has exploded in Germany. As of late 2025, ~1.5 GW/2.5 GWh of new batteries were added, helping to shift solar from midday to evening peak. Pumped hydro (9 GW) remains the backbone for longer storage. Green hydrogen is still on the horizon, with pilot projects like the GET H2 pipeline.

3. Market Design: Negative Prices and Flexibility

With high solar generation, often electricity prices go negative at noon. This incentivizes flexible consumers (e.g., electric vehicle chargers, heat pumps) to shift load. The German market has adapted with time-of-use tariffs and smart meters, now installed in over 25% of households.

The Role of Technical Innovation

Germany's energy transition isn't just about building turbines and panels. It's also about grid operations. Here's a simplified example of how a virtual power plant (VPP) might aggregate distributed solar and battery systems using Python:

import requests

class VirtualPowerPlant:
    def __init__(self, api_key):
        self.api_key = api_key
        self.assets = []

    def add_asset(self, asset_id, asset_type, max_power_mw):
        self.assets.append({
            "id": asset_id,
            "type": asset_type,  # "solar" or "wind" or "battery"
            "max_power": max_power_mw,
            "current_output": 0
        })

    def update_forecast(self, solar_forecast_mw, wind_forecast_mw):
        for asset in self.assets:
            if asset["type"] == "solar":
                asset["current_output"] = min(asset["max_power"], solar_forecast_mw / len(self.assets))
            elif asset["type"] == "wind":
                asset["current_output"] = min(asset["max_power"], wind_forecast_mw / len(self.assets))
            # battery logic would be more complex, but simplified here
        return self.assets

# Example: aggregate 100 MW solar, 80 MW wind, 20 MW battery
vpp = VirtualPowerPlant("demo")
vpp.add_asset("solar1", "solar", 100)
vpp.add_asset("wind1", "wind", 80)
vpp.add_asset("bat1", "battery", 20)

forecast = vpp.update_forecast(60, 40)  # 60 MW solar, 40 MW wind
print(json.dumps(forecast, indent=2))

This shows how software helps aggregate and manage distributed assets, a key reason Germany can handle high renewable penetration.

Policy and Economic Drivers

Germany's success isn't accidental. It's the result of two decades of policy:

• The Renewable Energy Act (EEG): Introduced in 2000, it provided feed-in tariffs that guaranteed grid access and fixed payments for renewable producers. This kickstarted the industry.
• Carbon pricing: The EU Emissions Trading System (ETS) has made coal increasingly costly. In 2025, the CO2 price hit €80/tonne, making coal uncompetitive.
• Accelerated permitting: In 2024, Germany streamlined wind and solar approval processes, reducing average project time from 5 years to 2 years.

Economic Impact: Lower Electricity Prices?

Wholesale prices have actually fallen in Germany when renewables are high. In 2025, average day-ahead prices were €78/MWh, down from €120/MWh during the 2022 energy crisis. However, household prices remain high due to grid fees and taxes. The next step is to align retail pricing with wholesale costs, which is a political challenge.

What This Means for the Global Energy Transition

Germany's milestone offers several lessons:

1. Grid stability is solvable: With proper planning, high wind and solar penetration doesn't cause blackouts. Germany's system operator, TenneT, has managed 80% renewable peaks.
2. Coal phase-out is feasible: Germany's coal power has dropped from 44% of generation in 2010 to 25% in 2025. The 2038 phase-out target is likely to be moved to 2030.
3. Storage is now a necessity: Battery costs have fallen 90% since 2010, making them the key enabler. Germany's example shows that market signals (negative prices) drive storage deployment.

However, challenges remain:

• Winter supply: In the dark and windless months (called 'Dunkelflaute'), Germany still relies on gas. The country is building 10 GW of hydrogen-ready gas plants to be converted to green hydrogen by 2035.
• Grid expansion: The north-south grid bottleneck continues to cause congestion and redispatch costs. The SuedLink HVDC line is still under construction, but when completed, it will reduce waste.
• Energy efficiency: Germany's electricity demand has not fallen as much as hoped. The transport and heating sectors need to electrify further.

The Road Ahead: 2030 and Beyond

By 2030, Germany targets 80% renewable electricity. To reach that, it needs to:

• Install 215 GW of solar (currently ~90 GW)
• Install 50 GW of offshore wind (currently ~10 GW)
• Triple storage capacity to 10 GWh

These are ambitious but achievable. The 2026 milestone is a psychological boost, proving that the transition is possible without compromising economic output.

Conclusion

Germany's wind and solar overtaking fossil fuels is not a single event but a turning point in the energy landscape. It demonstrates that a modern industrial economy can run on renewable energy, with a solid grid and market design. As other countries, including the US and Japan, grapple with their own energy transitions, Germany's example offers a blueprint—and a warning: the transition requires persistent policy, investment in storage, and public acceptance.

The Hacker News community has been buzzing with discussions about this milestone, and rightly so. It's a rare piece of good news in the climate change narrative. But the work is far from over. The next decade will determine if Germany can go from 50% to 80% and beyond. If it does, it will be a model for the world.

For those interested in the raw data, the Fraunhofer ISE publishes weekly charts and the ENTSO-E transparency platform offers real-time generation data. The trend is clear: the future is renewable, and Germany is leading the way.

Celebrating 45 Years of Kermit: The Protocol That Refuses to Die, Now Reborn in C

In the pantheon of early network protocols, few have enjoyed the staying power of Kermit. Born in the early 1980s at Columbia University, Kermit was a simple, robust file transfer protocol that conquered the world of dial-up modems, serial ports, and heterogeneous computing. As we mark its 45th anniversary in 2026, the protocol is not just a nostalgic relic—it's being actively reimagined with a brand-new, modern C implementation that promises to keep Kermit relevant for another generation.

The Remarkable History of Kermit

Kermit was developed by Frank da Cruz and Bill Catchings at Columbia University in 1981. The name, a nod to the Muppet, was chosen to avoid clashing with any existing protocol. The goal was simple: create a file transfer protocol that could work over any serial connection, regardless of the hardware, operating system, or network. In an era of wildly incompatible systems—CP/M, Apple II, TRS-80, Unix, DEC VMS—Kermit's portability was its killer feature.

The protocol was designed to be minimal and resilient. It used a packet-based system with checksums, but crucially, it could adapt to the underlying link's constraints. It supported both text and binary transfers, and it was easily extended. The reference implementation was written in C, which made it portable across many platforms.

Kermit became the de facto standard for transferring files between mainframes, minicomputers, and personal computers. It was used in academic, government, and corporate environments. Even the US Navy used Kermit for ship-to-shore communications. Its popularity peaked in the 1980s and 1990s, but it never fully disappeared. The protocol was later extended to support network connections (Kermit over TCP/IP), and even today, it remains a dependable fallback for embedded systems and legacy applications.

Why Kermit Still Matters

In an era of gigabit fiber and wireless networks, why would anyone care about a protocol designed for 2400 baud modems? The answer lies in its simplicity and reliability. Kermit is not just a file transfer protocol; it's a philosophy. It works where modern protocols fail—on noisy, low-bandwidth, or unusual links. It has minimal overhead and can be implemented in a few hundred lines of code. For embedded systems, industrial controllers, and retrocomputing enthusiasts, Kermit is a lifeline.

Moreover, the protocol's design is a masterclass in pragmatic engineering. It handles flow control, error detection, and recovery without the complexity of TCP/IP. It's a perfect candidate for learning about networking fundamentals. And for those who need to transfer files to or from a vintage machine, Kermit is often the only viable solution.

The First New C Implementation in 2026

Now, to celebrate its 45th anniversary, a new open-source project has emerged: a clean, modern, and fully-featured Kermit implementation written in C. Titled kermit-c, this project aims to bring Kermit into the modern era, preserving the original protocol's spirit while adopting contemporary software engineering practices.

The author, a long-time Kermit enthusiast, decided to rewrite the protocol from scratch. The original Kermit implementation was monolithic and tightly coupled to the terminal I/O of its time. The new version is modular, thread-safe, and designed to be cross-platform—running on Windows, Linux, macOS, and embedded RTOSes.

Key Features of the New C Implementation

• Portability: Written in ISO C11, it compiles on virtually any platform with a C compiler, including both 32-bit and 64-bit systems.
• Modular architecture: The protocol core is separate from the transport layer, allowing you to plug in serial, TCP, or even Bluetooth transport.
• Modern I/O: Supports both synchronous and asynchronous operations, and can be used as a library or a command-line tool.
• Extensibility: The packet format is fully configurable, allowing for experimentation with new features.
• Testing: Includes a comprehensive test suite that validates the protocol against the original Kermit 95 reference implementation.
• Documentation: Extensive comments and a full user guide, making it easy to integrate into other projects.

The library exposes a simple API that mirrors the classic Kermit functions but with a modern flavor. Here's a quick example of how to transfer a file using the new kermit-c library:

#include <kermit/kermit.h>

int main(void) {
    kermit_t *k = kermit_init(KERMIT_TRANSPORT_SERIAL, "/dev/ttyUSB0");
    if (!k) {
        fprintf(stderr, "Failed to initialize Kermit\n");
        return EXIT_FAILURE;
    }

    kermit_set_baud(k, 115200);
    kermit_set_parity(k, KERMIT_PARITY_NONE);
    kermit_set_packet_size(k, 512);

    // Send a file
    if (kermit_send(k, "local_file.txt", "remote_file.txt") != KERMIT_OK) {
        fprintf(stderr, "Transfer failed\n");
        kermit_close(k);
        return EXIT_FAILURE;
    }

    // Receive a file
    if (kermit_recv(k, "incoming.bin") != KERMIT_OK) {
        fprintf(stderr, "Receive failed\n");
        kermit_close(k);
        return EXIT_FAILURE;
    }

    kermit_close(k);
    return EXIT_SUCCESS;
}

Under the hood, the implementation carefully follows the original Kermit packet format, but it uses a modern state machine to handle the session. The library is designed to be thread-safe, so you can run multiple transfers concurrently, a feature that the original protocol could not easily achieve.

The Legacy Lives On

The new C implementation is not just a clone; it's a thoughtful overhaul. It preserves the simplicity and reliability of the original while incorporating lessons learned from decades of software engineering. The project has already gained traction on Hacker News, where it trended in early 2026, sparking discussions about the protocol's enduring relevance and the beauty of clean C code.

One of the most compelling aspects of the project is its commitment to backward compatibility. You can use kermit-c to communicate with an old 1980s Kermit running on a Commodore 64, and the transfer will work flawlessly. This is a testament to the original protocol's design and the new implementation's fidelity.

Conclusion

Kermit has seen 45 years of continuous use, a rare feat for any technology. The new C implementation breathes fresh life into this classic protocol, proving that good engineering never goes out of style. Whether you're a retrocomputing hobbyist, an embedded systems engineer, or a student of protocol design, kermit-c offers a robust, portable, and educational tool. As we celebrate Kermit's anniversary, we salute the protocol that taught us how to move files over uncertain links—and the new C code that keeps it alive for the future.

So, if you're at all interested in the history of computing or the art of writing efficient C, check out kermit-c. It's a beautiful piece of code, and it's a fitting tribute to a protocol that has been quietly working in the background for 45 years—and will continue to do so for many more.

Ten Breakthroughs in Mathematics and Theoretical Computer Science (2026)

The year 2026 has already witnessed a remarkable confluence of human intuition and machine intelligence, reshaping the landscape of pure and applied mathematics. From formal proof verification to quantum complexity, these ten advances are not just incremental—they are paradigm shifts that will echo for decades. Here's a deep dive into the breakthroughs that have captured the attention of Hacker News and the scientific community.

1. The First AI-Discovered Proof of a Major Conjecture

In a historic collaboration, a team at the Institute for Advanced Study and DeepMind used an AI system called LeanMind to discover a proof of the Sylvester-Gallai conjecture in a special Euclidean geometry. The proof, which involved a novel construction of an auxiliary algebraic curve, was initially rejected by human mathematicians for its perceived lack of elegance. However, the formal verification system Coq confirmed its correctness, and the result was published in the Annals of Mathematics. This marks the first time a major open problem has been solved by AI without substantial human guidance.

theorem sylvester_gallai : forall (P : set Point),
  finite P ->
  (forall p q : Point, p in P -> q in P -> p != q ->
    exists r : Point, r in P /\ r != p /\ r != q /\ collinear p q r) ->
  exists line, line_contains P line

The implications are staggering: AI can now generate proofs that not only verify but also inspire new mathematical frameworks.

2. Resolution of the Hadamard Conjecture for All Orders > 4

For over a century, the Hadamard conjecture—which posits that a Hadamard matrix exists for every order divisible by 4—remained open. In 2026, a team from Oxford and MIT used a combination of combinatorial design theory and quantum annealing to construct explicit Hadamard matrices for all orders up to 1000, and then extended the method to prove the conjecture for all orders. The key was a new recursive construction based on signed graph symmetries that reduced the problem to a finite set of base cases.

This breakthrough has immediate applications in error-correcting codes, signal processing, and even quantum state tomography.

3. A New Lower Bound for Matrix Multiplication: Omega(n^2.3727)

After decades of incremental improvements, the matrix multiplication exponent ω finally fell below 2.3727. The breakthrough came from a surprising source: tensor decomposition combined with deep reinforcement learning. The AlphaTensor system, introduced in 2022, was refined to discover a new algorithm that achieves ω = 2.3719. While the improvement is small, the theoretical significance is huge: it demonstrates that machine learning can outperform human intuition in algebraic complexity.

# Pseudo-code for the new matrix multiplication algorithm
def matmul(A, B):
    # Use RL-optimized tensor decomposition
    return tensor_contract(A, B, rank=2.3719)

4. The Formal Verification of the Kepler Conjecture

The Kepler conjecture, which states that the densest packing of equal spheres is the face-centered cubic lattice, was formally verified in Lean by a team at Carnegie Mellon University. This is a monumental achievement in formal mathematics, as the original proof by Thomas Hales relied on extensive computer calculations. The new proof is fully machine-checked and includes a new, more elegant proof of the local density inequalities using interval arithmetic and linear programming.

This marks a paradigm shift: formal verification is no longer just for toy examples but can handle the most complex human proofs.

5. New Advances in the P vs. NP Problem: A New Separation for Exponential Time

While P vs. NP remains unresolved, a team of researchers at the University of Copenhagen and IIT Kanpur proved a new separation: EXP ≠ NEXP under a plausible derandomization assumption. More importantly, they introduced a novel technique called quantum circuit lower bounds via local Hamiltonian complexity, which shows that certain quantum circuits cannot be simulated by classical circuits of subexponential size. This has implications for both complexity theory and quantum computing.

# Pseudo-code for the separation proof
if (quantum_circuit has low-entanglement) then
    NEXP != P

6. A Breakthrough in the Collatz Conjecture: A Billion-Case Verification

While not a full proof, the Collatz conjecture received a major boost when a new algorithm based on automated theorem proving and GPU acceleration verified the conjecture for all numbers up to 2^70 (about 1.18 × 10^21). The verification used a novel technique called modular arithmetic pruning that reduces the search space by 99.999%. The results, published in Mathematics of Computation, provide strong evidence for the conjecture and have inspired new approaches using dynamical systems.

7. A Quantum Algorithm for Solving Differential Equations in Polynomial Time

A team at Caltech and Google Quantum AI unveiled a quantum algorithm that solves a large class of nonlinear partial differential equations (PDEs) in polynomial time, whereas classical algorithms require exponential time. The algorithm leverages quantum linear algebra and a new encoding of PDE solutions as quantum states. This has already been applied to model fluid turbulence in a simulation that would have taken a classical supercomputer 1,000 years—now done in 2 minutes on a 100-qubit machine.

# Quantum algorithm sketch
from qiskit import QuantumCircuit
qc = QuantumCircuit(10)
# encode initial conditions
qc.initialize(...)
# apply quantum PDE solver
qc.append(QPDE_solver, range(10))

8. A New Proof of the Twin Prime Conjecture (finite distance bound)

In 2013, Yitang Zhang proved that there are infinitely many prime pairs within a finite distance. In 2026, a team led by a young mathematician at Princeton improved the result to a distance of 2—the full twin prime conjecture—but under the assumption of the Generalized Riemann Hypothesis. While conditional, this is seen as a massive step. The proof introduces a new sieve method based on additive combinatorics and non-trivial bounds on exponential sums.

9. The Development of "Catastrophe Theory 2.0" for Machine Learning

Building on the classic catastrophe theory, a new mathematical framework called Catastrophe Learning has been introduced to explain the sharp phase transitions in neural network training. The theory, developed by a collaboration of mathematicians and AI researchers, uses singularity theory to analyze the loss landscape. It provides a rigorous explanation for the "grokking" phenomenon and the sudden generalization in transformer models. This has led to new training algorithms that avoid catastrophic forgetting by using topological data analysis.

10. The Rise of "Formalized Mathematics" in Mainstream Publishing

While not a single breakthrough, the cumulative effect of formal verification tools (Lean, Coq, Isabell) has reached a tipping point. In 2026, the top three mathematics journals now require formalization for any proof that relies on heavy computation. This has led to a massive collaboration: the Formal Math Project has formalized over 500,000 theorems, including the entire curriculum for abstract algebra. The project has even proposed a "mathematical proof" but is now a standard for rigor.

Conclusion

These ten advances represent a new era where mathematics and computer science are not just partners but are fused. AI is no longer a tool; it is a co-author. Formal proof is becoming the gold standard. And the boundaries between continuous and discrete, between quantum and classical, are blurring. For the Hacker News crowd, this is the frontier. The future is not just about faster CPUs—it's about deeper logic.

As we look ahead, one thing is certain: the next breakthrough is just around the corner, and it will likely be discovered by a human-AI collaboration, exactly as these were.

Your Secrets Need a VDP, Not Just a Bug Bounty

Bug bounty programs are valuable -- until they replace disclosure policies. Learn how unreasonable PoC demands or scope exclusions create security blind spots when it comes to leaked secrets.

By Gaetan Ferry • 6 Feb 2026 • 8 min read

In recent years, more and more companies have launched bug bounty programs as proof of their commitment to security and as a way to implement continuous monitoring of their corporate attack surface. Those programs sometimes offer generous payouts to vulnerability reporters, and often partner with dedicated platforms that offer various services such as:

• Payment and billing management
• Triaging as a Service
• Investigation assistance

Platforms rely on a "hacker community", a group of people who hack on the programs to discover vulnerabilities and earn bounty money. Most of those "hackers" are self-employed in a way that allows them to comply with local applicable tax laws.

Bug bounty programs are a great way to have a corporate perimeter or set of applications audited by a large set of people, nearly continuously. They can be a great addition to a company's security policy. In fact, GitGuardian has been running a bug bounty program for multiple years, as a complement to our periodic audits and overall security strategy.

Bug Bounty Done Wrong

The problem with bug bounty programs starts when they try to substitute for a proper Vulnerability Disclosure Policy. When they do, they no longer improve your security posture; they undermine it.

Bug bounties, by design, are selective. From a "hacker" perspective, they come with limited scopes, opaque triage processes, gatekeeping platforms, or even eligibility requirements. As a result, valid, good-faith vulnerability reports can get ignored, rejected, or buried -- not because they lack accuracy or merit, but because they fall outside of the boundaries of the programs' terms or the opaque decision of a third-party triager. Payout levels also undermine this testing model, turning continuous monitoring into a blind spot shaped by market incentives; why search for or report vulnerabilities when they pay little or nothing?

Using a bug bounty platform as the only possible communication channel for vulnerability disclosure creates unnecessary friction:

• Mandatory registration forces researchers to trade their privacy for participation.
• Non-disclosure clauses can silence conversation about systemic risks, and more generally hinder information sharing.
• Platform gatekeeping can discourage reporters.
• Worse: out-of-scope dismissals allow serious vulnerability reports to be voided, and never reported to security teams

These blind spots don't make an organization more secure. They make it easier to overestimate the security posture, thinking that fewer reports mean fewer problems.

A good Vulnerability Disclosure Policy (VDP) should promote openness. It should be a clear and accessible way for anyone -- a professional researcher, a student, or a concerned user -- to report a security issue safely, privately, and without process complexity. A good disclosure policy should enable communication rather than controlling it.

One particular issue that highlights how bug bounty can fail as a disclosure channel lies in how they handle secret leak reports.

GitGuardian's experience

One of the core foundations of GitGuardian is the detection and remediation of secrets leaked in public spaces. Over the course of the past year, while working on improving our understanding of the secret sprawl issue, we performed responsible disclosures to hundreds of companies.

GitGuardian's cybersecurity research team is not a bug bounty crew. We do not seek any reward for reporting incidents. For this reason, we usually attempt to contact affected companies directly, preferably via email, and sometimes through online forms dedicated to security incident reporting. We only fallback to the bug bounty program channel as a last resort, or when directly prompted to do so.

While working with platforms, we experienced a variety of situations and answers that illustrate how bug bounty can fail as a disclosure channel.

400 PoC or GTFO

As a result of a large-scale research project, we recently reported leaked private keys related to valid X.509 certificates. The risk of such incidents can generally be considered high, as a leaked key can be used to set up Man-In-The-Middle attacks against the company's public assets. Some of our reports had to go through bug bounty platforms, which already create friction. As much as we can automate the sending of hundreds of e-mails, filling bug bounty reports at scale is challenging.

In all our reports, the triagers asked for a proof of concept exploitation.

HackerOne response asking for a proof of concept after private key leak

BugCrowd response asking for a proof of concept after valid credential leak

First, proving a credential's impact has a clear ethical boundary: demonstrate the potential for harm without causing actual harm. This means verifying credentials are valid, confirming what resources they access, and documenting their privilege level, but without reading production data, modifying systems, or performing harmful actions. This is not always possible, depending on the credential type. In the case of leaked X.509 certificate private keys, creating such a proof-of-concept would have required decrypting real traffic or impersonating production services -- crossing from validation into active attack -- which could have severe legal consequences.

Then, the main question is: what happens after the report gets closed as informative? There is a chance that no action will be taken. In some cases, the issue might never pass the triaging filter and reach the corporate security team.

In our case, most reports were actually closed as informative, and none of the related certificates were revoked. Worst of all, some GitHub repositories containing leaked private keys have never been deleted. We later contacted the related certificates' issuer authorities to have the keys black listed and certificates revoked.

403 Private Program

Bug bounty programs can either be public or private. Public programs can be viewed, accessed, and interacted with by anyone. On the other hand, private programs are invite-only, so only selected members of the platform's community can report vulnerabilities.

In that case, obviously, the program can not be considered a proper disclosure channel. However, there is a reporting flow that overlooks this issue:

• You discover a vulnerability and attempt to report it through standard channels (security@, contact forms).
• You receive a response: 'Please submit via our Bug Bounty Program.'
• You navigate to the platform, only to find it's private and invitation-required.
• Without an invitation, you hit a dead end with no alternative channel.

Our team has faced this situation once, making the reporting process painful and highlighting how companies often lack awareness about vulnerability disclosure practices.

Similarly, a documented program can have expired or been decommissioned. In this case, the communication channel is effectively nonexistent. This was the case when we reported a leaked API key to xAI in 2025.

404 Secret Not Found In Scope

The scope of a program includes the list of assets that are authorized to be worked on. It also includes the list of vulnerabilities that are accepted in reports. The purpose of this restriction is to limit the number of low-quality reports or reports for vulnerabilities that are widely recognized as lacking real-world impact.

However, if the scope of a program is too restricted, valid and severe issues might get discarded by the triaging team without further notice. In that spirit, we faced bug bounty programs that explicitly marked leaked credentials as out of scope. The platforms sometimes even encourage their customers to ban secrets. The reason behind this is tied to the origin of the credentials, as we discussed with a platform representative:

We strongly advise our clients to exclude leaked secrets from their bug bounty program scope. The reality is that compromised credentials frequently originate from illicit sources. There's a thriving underground market for stolen credentials, and by offering bounties for leaked secrets, we risk inadvertently incentivizing and legitimizing a secondary marketplace for compromised authentication data.

While this concern is understandable, excluding leaked secrets creates a dangerous blind spot. Valid credentials represent immediate security risks: unauthorized access, data breaches, or compromised systems.

The solution isn't to ban secret reports -- it's to require source transparency. Researchers should disclose where the credentials were found. This approach enables security teams to investigate the leak's origin and take appropriate remediation action, while distinguishing legitimate research from illicit activity.

500 Triager error

Triager gatekeeping can also be an issue in case of a misunderstanding about a security issue. While misunderstandings can occur with corporate security teams, triagers can close the communication channel when they deem an issue uninteresting. While it is often possible to ask to reopen closed reports or ask for mediation, this can prevent legitimate reports from reaching the corporate teams and create unnecessary friction.

In the above case, the triager closed the issue while the affected credentials were still valid. Such behaviors create frustration, discourage reporters and, again, prevent secrets from being reported.

302 Redirect To Bug Bounty

Even when a direct communication channel with corporate security teams exists, it happens that those teams redirect mailed reports to a bug bounty platform. The rationale is understandable: centralizing all vulnerability reports in one place simplifies triaging and tracking.

Doing so not only slows the remediation process down, but also creates a dangerous bottleneck as the submission will likely have to comply with the bug bounty rules and scope definition, with the same pitfall as issues directly reported on platforms.

It also goes against the potential privacy requirements of the reporter, who would have to create an account on the bug bounty platform and sometimes even fill out tax regulation documents.

We received such a response when we contacted xAI for a leaked token last year. In that case, the corporate team also fixed the issue in the background, even before we could submit it to their program, demonstrating a clear lack of transparency.

Dear Gaëtan,
Thank you for your email.
For us to analyze and also for you to receive proper credit, if applicable, would you please submit this to xAI's Bug Bounty Program on HackerOne?
https://hackerone.com/x?type=team
Thanks!
xAI Team

Vulnerability Disclosure Policy done right

Writing a clear Vulnerability Disclosure Policy that provides an open and transparent communication channel is of prime importance to ensure your company receives vulnerability reports properly. As we explained above, such a policy should promote openness, transparency, and reporters' safety. Privacy is also a core concept of any proper VDP and should be emphasized, as is explained in documents from the US Cybersecurity & Infrastructure Security Agency:

How should my agency treat vulnerability reports from anonymous sources?
These reports should be treated the same as all other reports: like a gift. Knowing the source of a report can be a real benefit because it allows for rapport to develop. However, if the person who submits a report isn't known, the claim should simply be evaluated on its merits -- like every other report.

When bug bounty platforms are your only security communication channel, such privacy can not be appropriately granted to vulnerability reporters.

In fact, CISA published a complete template for Vulnerability Disclosure Policy that emphasizes those openness and transparency concepts. The document is meant to be a regulatory requirement for government agencies, but it can be used as a basis to write the VDP of any company.

At GitGuardian, we are not against bug bounty programs, as we think they can be a great addition to a company's security policy. However, it is of prime importance to understand the limits and blind spots created by those platforms.

Most importantly, bug bounty programs must complement -- not replace -- a public Vulnerability Disclosure Policy. Private, invitation-only programs create insurmountable barriers for new researchers and should never be the sole disclosure channel. Companies should maintain accessible public VDPs alongside any BBP, with clear escalation paths that allow critical reports to bypass platform restrictions when necessary. Direct reports to security@ should remain direct -- triaged by internal teams who understand the full context of their infrastructure, not filtered through external platform scopes that may dismiss legitimate threats on technicalities.

Especially, if you manage a bug bounty program, make sure to include leaked credentials in its scope. Credentials-based attacks have become the number one cyber threat in the modern world, so those incidents should not be disregarded. Asking and verifying the source of the leaks will allow better investigation of the leak issue while reducing the risk of buying stolen credentials from the black market.

To conclude, whatever communication channel you choose for your vulnerability reports, make sure to promote it and make it as visible as possible, for example, with an RFC 9116 security.txt file. There is nothing worse than a communication channel no one knows about.

When running code reviews with local LLMs, a single model can either hallucinate non-existent bugs or generate generic advice you end up ignoring.

To make local AI code review more useful, I built a closed Reviewer vs. Verifier loop for local Ollama workflows.

The Architecture: Two Local Agents, One Loop

Instead of trusting one model's output, the workflow splits the job into two roles:

1. Agent 1 (Reviewer): Reads the git diff or file changes. It searches specifically for logical flaws, security vulnerabilities, edge cases, or missing unit tests.
2. Agent 2 (Verifier): Takes the Reviewer's list of findings and actively challenges them. If a finding is weak or unsupported, the Verifier pushes it out of the action list. If it holds up, the next step stays visible.

The goal is not to make the model "always right". The goal is to make weak claims easier to catch before you act on them.

Why Local-First?

Many agent workflows eventually ask you to move private workspace context into somebody else's control plane.

I packaged this workflow into HAICHI, a desktop workspace for Windows and Linux that connects to local Ollama models and keeps the workflow state inspectable.

Key features:

• Local-first workflow: Run Reviewer and Verifier style loops around local models.
• Visible evidence trail: Keep task, review, challenge, and result in one workspace instead of scattered chat tabs.
• Scoped execution: Keep actions bounded to the workflow you explicitly run.
• Practical limits: Control how much concurrent agent work runs on your machine.

Try it on your own code

HAICHI Personal is free to try.

• Website: https://haichi.app
• Supported OS: Windows 10/11, Linux (Ubuntu/Debian/Arch)

If you're already using Ollama for real development work, test the Reviewer vs. Verifier loop on one change and let me know where it helps, where it is too noisy, and what your local setup looks like.

A few months back I was running Sales Navigator searches for a client project — filtering down to "VP Sales, fintech, based in Italy or Spain" type lists — and the results were genuinely good. 60, 80 leads that actually matched. Then I hit the part nobody warns you about: there's no button on that page that says "save this."

So I did what everyone does. Opened a spreadsheet, alt-tabbed back and forth, typed names and job titles by hand. Around profile 40 I gave up and went looking for a better way. This is what I found, roughly in the order I found it, including the tool I ended up building because none of the existing options quite fit what I needed.

First: the export LinkedIn actually gives you

LinkedIn has a real, built-in data export, and most people don't realize how narrow it is. It's under your profile photo → Settings & Privacy → Data Privacy → Get a copy of your data. From there you either tick specific categories (that email usually lands within minutes) or request the full archive, which takes closer to a day and sometimes arrives in two batches. Either way you get a download link that expires after 72 hours — and it's desktop only, the mobile app won't let you request one.

What you get back is genuinely thorough: connections, messages, your own profile history, activity, even the ad-targeting data LinkedIn holds on you. A couple of quirks worth knowing before you rely on it: some connections' email addresses will just be missing, because sharing an email on download is something each person opts into individually, and you won't get a list of who viewed your profile or any "People You May Know" data. If you're in the EU, EEA, or Switzerland, LinkedIn also runs a separate API for pulling your data on a schedule rather than as a one-off request.

Here's what this export is not built for, though: it has no idea what you searched for yesterday. It's an archive of your own account, not a way to capture a live search. Run a Sales Navigator query and pull 80 leads, and this tool won't touch them — those results aren't "your data," they're a page LinkedIn rendered for you a minute ago. If you want a yearly backup of your own connections and messages, or you're about to deactivate and want a copy first, start here and you're done. If you're trying to get a search result out of the browser, keep reading.

Second: the manual way, which is what most people actually do

Copy the name. Copy the title. Copy the company. Paste into a column. Repeat.

It's fine for five profiles before a call. It's genuinely miserable past fifteen — you lose track of who you've already copied, columns drift out of alignment, and an hour later you've got a spreadsheet that looks like it survived a fall down some stairs. I don't think anyone picks this method so much as ends up in it by default, since it's the only option that needs zero setup.

If you only do this occasionally, don't overthink it. A blank spreadsheet and fifteen minutes beats installing anything. It only turns into a real problem once you're doing it every week.

Third: browser extensions, which read what's already on the page

Once you're pulling data regularly, the next step people reach for is a browser extension, and it's worth understanding what these actually do under the hood — "LinkedIn tool" covers a wide range of behavior, and the range matters.

The category I trust reads the DOM of the page you're already looking at, the same rendered HTML your browser downloaded to show you the search results, and turns the visible fields into rows in a file. It doesn't call a private API, doesn't need anything beyond the session you're already logged into, and doesn't do anything you didn't ask it to.

The category I don't trust is the one that also automates actions on your behalf: auto-sending connection requests, auto-messaging, "warming up" a profile with likes. That's a fundamentally different product, and it's the kind of behavior that gets accounts restricted, because LinkedIn's abuse detection is watching for exactly that pattern — a lot of actions, very fast, in a rhythm no human clicks in. Reading a page you're already viewing and writing what you see to a CSV is a much smaller ask than pretending to be a human sending 200 connection requests an hour.

What I ended up building

I looked for something that just read search results — Profile, Company, Jobs, and Posts on regular LinkedIn, plus Lead and Account search on Sales Navigator — and either couldn't find it or found it bundled with a dozen automation features I didn't want anywhere near my account. So I built the Mastros LinkedIn & Sales Navigator exporter.

It's read-only, on purpose. You run a search, the extension recognizes the page and shows you every field it found before you export anything, so you know what you're getting instead of finding out after. Set a limit, hit export, and it drops a CSV, JSON, or JSONL file. CSV opens straight in Excel or Sheets and imports cleanly into a CRM — something like:

full_name,job_title,company,location
Marco Bianchi,Head of Partnerships,Nordic Robotics,Turin
Sara Klein,VP Marketing,Fjord & Co,Copenhagen
Tomás Silva,Founder,Casa Verde,Lisbon

A few decisions I made on purpose, mostly because they were the things that annoyed me about other tools:

• Nothing leaves your machine. Extraction runs in your browser; the data never touches a Mastros server. We don't see the names or profiles you save, only that a save happened.
• No email guessing. It doesn't derive or buy anyone's email address. What's on the page is what you get.
• Only new records. Turn this on and it skips anything you've already exported, so re-running a search doesn't just duplicate last week's file.
• Safety pacing. There's an hourly cap that's separate from your monthly plan quota, specifically so a big export doesn't turn into the kind of rapid-fire activity that flags an account. Same reasoning as the automation point above: reading slower, on purpose.
• No actions, ever. It doesn't send invites, messages, or InMails, and it doesn't like, follow, or apply to anything. You trigger every export yourself; it never acts on your behalf.

It's free for 250 records a month across all six search types, no card required. Pro is $9/month for 10,000 records with rollover on unused ones, and Scale is $18/month with no record cap from our side — LinkedIn's own rate limits still apply, because claiming otherwise would just be a lie.

Picking one

• Backing up your own connections and messages, or prepping to deactivate → LinkedIn's own export. It's free, official, and already good at this.
• A handful of profiles before a call, once in a while → copy-paste. Don't install anything for five rows.
• Recurring prospecting, recruiting pipelines, or keeping a CRM fed from live searches → an extension built specifically to read search results, with pacing and dedup baked in. That's the gap the LinkedIn exporter is built to fill.

One last thing, easy to skip past: whichever method you use, the data is still about real people who didn't sign up to end up in your spreadsheet. Export what you're actually allowed to see, follow LinkedIn's terms, and don't turn a clean CSV into a cold-email blast nobody asked for. That's not a legal disclaimer, it's just the difference between doing research and being the reason someone locks down their privacy settings next week.

If you want to try it: it's a free Chrome install, 250 records a month, no card needed.

After working on enterprise applications and distributed microservices, I have realized that the biggest challenges rarely come from writing business logic. They come from handling production traffic, failures, concurrency, and unexpected edge cases.

Here are seven lessons that every Spring Boot developer should know before calling themselves a senior engineer.

1. Never Assume an API Will Be Called Only Once

One of the most common mistakes is assuming a client sends exactly one request.

In reality:

• Users refresh the page.
• Mobile apps retry automatically.
• API gateways retry requests.
• Kafka consumers may reprocess events.
• Network failures cause duplicate submissions.

If your endpoint creates an order, payment, or booking every time it receives a request, duplicates are almost guaranteed.

Better Approach

Design APIs to be idempotent.

For example:

• Use an Idempotency-Key.
• Store processed request IDs.
• Ignore duplicate requests safely.

Production systems should always expect duplicate requests.

2. Database Transactions Are Not Enough

Many developers believe this solves everything:

@Transactional
public void createOrder() {
    ...
}

It doesn't.

A transaction protects changes inside a single database.

It does not protect:

• Kafka publishing
• Email sending
• External REST APIs
• Redis updates
• File uploads

If your database commits successfully but Kafka publishing fails, your system is already inconsistent.

Better Approach

Use patterns such as:

• Transactional Outbox
• Saga Pattern
• Event-driven architecture
• Retry with dead-letter queues

3. Don't Trust External APIs

Every external service will eventually fail.

Your payment provider.

Your authentication service.

Your notification service.

Even your own internal microservices.

Never assume another service is always available.

Add Protection

• Timeouts
• Retries
• Circuit Breakers
• Fallback logic
• Monitoring

Failing fast is usually better than waiting forever.

4. Logging Is More Valuable Than You Think

When production goes down, nobody asks:

"Was the code clean?"

Everyone asks:

"What happened?"

Poor logging turns a five-minute issue into a five-hour investigation.

Good Logs Include

• Correlation ID
• Request ID
• User ID (where appropriate)
• Service name
• Execution time
• Error details

Avoid logging entire request bodies or sensitive information.

Logs should help you debug—not create new security problems.

5. Performance Problems Usually Start in the Database

Most slow APIs aren't caused by Java.

They're caused by:

• Missing indexes
• N+1 queries
• Loading unnecessary data
• Multiple database calls inside loops

Before optimizing Java code:

• Check SQL execution plans.
• Measure database latency.
• Cache frequently used data.
• Fetch only what you need.

Always measure before optimizing.

6. Handle Concurrency Explicitly

Concurrency bugs are among the hardest to reproduce.

Imagine two requests arriving at exactly the same time:

Request A
Request B

Both check:
Balance = ₹100

Both withdraw ₹100

Final Balance = -₹100

Everything worked correctly from each request's perspective.

Together, they corrupted the data.

Solutions

• Optimistic Locking
• Pessimistic Locking
• Distributed Locks
• Atomic database updates
• Idempotent operations

Concurrency isn't a rare edge case.

It's a daily production reality.

7. Monitoring Is Part of the Application

If you can't observe your application, you can't operate it.

Every production service should expose:

• Health checks
• Metrics
• Request latency
• Error rates
• JVM metrics
• Database latency
• Kafka consumer lag

Modern observability tools include:

• Micrometer
• Prometheus
• Grafana
• OpenTelemetry
• ELK Stack

The best production incidents are the ones users never notice because your monitoring detected them first.

Final Thoughts

Being a senior Spring Boot developer isn't about memorizing annotations or frameworks.

It's about designing systems that continue to work when networks fail, traffic spikes, duplicate requests arrive, and dependencies become unavailable.

Production engineering is less about writing more code and more about building software that remains reliable under real world conditions.

If you're just starting your backend journey, focus on these concepts early. They'll have a much bigger impact on your career than learning another framework.

Java #SpringBoot #Microservices #Backend #SoftwareEngineering #SystemDesign #DistributedSystems #Kafka #Programming #DevOps

Una discusión sobre un archivo digital casi nunca se pierde por lo que el archivo
dice. Se pierde una pregunta antes:

¿Cómo sabemos que ese es el archivo que usted recibió, y no el que editó anoche?

Si la respuesta es "confíe en mí", ya perdiste. Y da igual cuánta razón tengas en
el fondo.

Este problema no es exclusivo de un juzgado. Lo tiene el auditor que recibe un
volcado de logs, el equipo que documenta un incidente, quien conserva la copia de
un contrato firmado por correo. En todos los casos hace falta lo mismo: poder
demostrar que un conjunto de bytes no cambió desde un momento determinado, y que
lo demuestre alguien que no seas tú.

Para eso escribí Tunjo: una
herramienta en Rust que recorre un material en solo lectura, calcula su huella y
firma un acta verificable por cualquiera.

Por qué un árbol y no un hash

Lo obvio sería concatenar todo y sacar un SHA-256. Funciona, y es inútil en la
práctica.

Cuando alguien discute un archivo —un correo concreto entre cuatro mil— con
un hash único solo puedes ofrecer dos cosas: o entregas el conjunto completo para
que se recalcule, o pides que te crean. La primera opción expone material que no
tiene por qué exponerse; la segunda no es una prueba.

Un árbol de Merkle resuelve exactamente eso. Cada archivo es una hoja, cada par
de nodos se combina hacia arriba y queda una raíz. Para demostrar que una hoja
pertenece a esa raíz basta con exhibir esa hoja y el camino de hashes hasta
arriba: unos pocos kilobytes. El resto del conjunto no se toca.

Dos detalles del árbol que no son opcionales:

// Separación de dominio: una hoja nunca puede hacerse pasar por nodo interno.
h.update([0x00]);          // hoja
h.update([0x01]);          // nodo interno

// Y la raíz ata el número de hojas.
h.update([0x02]);
h.update(n.to_be_bytes());

Sin lo primero, un hash de hoja podría presentarse como si fuera un nodo del
árbol. Sin lo segundo aparece la ambigüedad clásica de los árboles con número
impar de hojas: dos conjuntos distintos pueden producir la misma raíz. Es un
error viejo y conocido, y sigue apareciendo en implementaciones nuevas.

La huella cubre el estado, no solo el contenido

La hoja no es el hash del archivo: es el hash del elemento completo —ruta,
tamaño, fecha, estado y hash del contenido—.

La diferencia importa. Si la huella fuera solo del contenido, mover un archivo de
carpeta, renombrarlo o sustituirlo por un enlace que apunta al mismo contenido
dejaría la raíz intacta. Y esos tres movimientos cambian lo que el conjunto
significa: dónde estaba un documento es parte del hecho que se documenta, no un
detalle de presentación.

Firmar para dentro de diez años

El acta se firma con la firma triple-híbrida de
Quipu: Ed25519 + ML-DSA-87 (FIPS 204)

• SLH-DSA-SHA2-256s (FIPS 205), y las tres deben validar.

No es coleccionismo de algoritmos. Es que la vida útil de esto no se mide en
meses: un expediente puede tardar años en resolverse, y la firma tiene que seguir
verificándose al final. Las tres piezas fallan por motivos distintos —Ed25519
frente a un ordenador cuántico; ML-DSA por ser reciente y basada en retículos;
SLH-DSA solo si se rompe la función hash— y hacen falta las tres a la vez para
que el sello valga. Que caiga una no tumba el acta.

El coste es honesto: la firma pesa unos 34 KB. Para sellar un conjunto de
archivos, es ruido.

Verificar la firma no basta

Este es el error que más fácil se comete al implementar algo así. La firma cubre
el JSON completo del acta, incluida la raíz de integridad. Si al verificar te
limitas a comprobar la firma, das por buena una raíz que nadie recalculó: alguien
con la clave podría firmar un acta cuya raíz no corresponde a los elementos que
lista, y pasaría el control.

Por eso la verificación recalcula el árbol siempre, y solo después mira la firma.
Hay una prueba dedicada a ese caso exacto: firma auténtica sobre raíz mentirosa
debe fallar.

$ tunjo verificar acta.json --origen ./evidencia
SELLO VÁLIDO
  contenido:  4 elementos, 3 con contenido verificable
  raíz:       d9f6f68f591c6af087838dc27049a4194ab70525c350b79ec22446f9c12f9e33

1 DISCREPANCIA(S) contra evidencia:

ALTERADO   adjuntos/c.pdf
           acta: 3fdbaf9c795e22f14e16974c37b62ed381b9c8c4ac7bcbe1a01f13d08ec46643
           disco: 9af5d94042eafbf2c335aa874085b263ff0201aee5e5033fd4c432e92de0093d

Ante la ausencia de un dato, ruido

Una herramienta de integridad que disimula sus fallos es peor que no tenerla,
porque produce confianza sin respaldo. Tres decisiones al respecto:

Un archivo ilegible detiene el sellado. No se salta en silencio. Si de verdad
es ilegible, hay que pedirlo explícitamente y entonces el acta lo registra como
error: de ese elemento consta que existía y que la lectura falló, y nada más.

Del reloj se dice la verdad. El acta pide declarar cómo se contrastó con una
fuente externa. Si no se declara, escribe "NO VERIFICADO" en lugar de callarlo.
Sin sello de tiempo de un tercero, esto prueba orden relativo, no fecha cierta —y
también lo dice.

Los enlaces simbólicos no se siguen. Se registra a dónde apuntan. Seguirlos
sacaría la adquisición del material que se recibió.

Lo que deliberadamente no hace

No detecta intrusiones, no atribuye autoría y no concluye nada. Podría añadirle
heurísticas que dijeran "aquí hubo un ataque", y sería un error: quien firma un
informe tiene que poder defender cada afirmación línea por línea, y nadie defiende
una heurística que no escribió. Cuando esa afirmación se cae, arrastra al resto
del informe.

Tampoco prueba el pasado. Acredita desde el instante de la adquisición: si el
material ya venía alterado, el sello certifica fielmente material alterado. Está
escrito en el acta que genera, no en la letra pequeña.

El verificador es público, y no por generosidad

Si el único que puede comprobar un sello es quien lo emitió, no es una prueba: es
una afirmación con formato técnico. Por eso el verificador es software libre y su
código está publicado.

Lo comprobé de la única forma que vale: cloné el repositorio público en una
máquina limpia, lo compilé desde cero y con ese binario verifiqué un acta
sellada por otro. Válida. Después alteré un byte de un adjunto y el mismo binario
señaló ese archivo y solo ese.

git clone https://github.com/isazajuancarlos/tunjo
cd tunjo && cargo build --release
./target/release/tunjo verificar acta.json --origen ./evidencia

Rust, AGPL-3.0, y las pruebas incluyen una simulación de 240 contrastes: se altera
un byte de cada uno de 120 archivos y se exige que señale ese y solo ese, y que al
restaurarlo no queden falsos positivos. Detectar es fácil; discriminar es el
trabajo.

Canonical URL: https://blog.1001020.xyz/

Suggested cover image: use a recent image from https://blog.1001020.xyz/gallery

I have been building a small publishing system called 1001020, a serverless blog and AI gallery running on Cloudflare Workers.

The live site is here: 1001020 — AI Gallery & Cloudflare Experiments

The goal was not to build another static blog generator. I wanted something that could publish articles, serve an image gallery, manage uploaded assets, expose structured sitemaps, and stay operational without a traditional server.

The basic architecture

The whole public site runs on Cloudflare Workers. Articles, settings, comments, gallery metadata, and telemetry live in Cloudflare KV. Managed images are stored in R2 and served through a dedicated image domain.

The main pieces are:

• Cloudflare Workers for request routing and rendering
• Cloudflare KV for article and site metadata
• Cloudflare R2 for managed image uploads
• A theme system for different frontend layouts
• XML sitemap and image sitemap generation
• A small local AI drafting tool for preparing and publishing content

The gallery is a first-class part of the site, not just a media folder. You can browse it here: AI Gallery on 1001020

Why Workers instead of a conventional backend?

For this project, Workers are a good fit because the workload is mostly request routing, HTML generation, metadata reads, and small API writes. A conventional server would work, but it would add deployment and maintenance overhead that I did not need.

Cloudflare Workers also make it easy to keep the app close to the edge while still handling dynamic behavior. The blog can render pages server-side, expose APIs, and support admin operations without a separate Node or container deployment.

KV as the content store

The project stores persistent content in KV using explicit keys for articles, gallery records, settings, telemetry, comments, newsletter subscribers, and other small datasets.

This shape works well for a personal publishing system because the access pattern is simple:

• read the article index
• read individual article records
• write admin updates
• render HTML or markdown responses
• regenerate sitemap output from current content

The main tradeoff is that KV is not a relational database. I keep data models small and explicit, and avoid pretending it can do arbitrary query workloads.

R2 for images

Images are uploaded as managed assets and served from R2. Article content can reference those managed image URLs, and the system tracks image references so unused assets can be identified and cleaned up.

That part matters because image-heavy blogs tend to accumulate stale files quickly. Treating image references as part of the content model keeps the gallery and article system easier to maintain.

SEO basics that are built in

The site now ships with the boring but important search plumbing:

• sitemap.xml
• image-sitemap.xml
• robots.txt
• server-rendered article content
• image dimensions for layout stability
• canonical article URLs
• Google Search Console verification token injection through the admin settings page

One article that explains part of the agent workflow direction is here: Agent Harness Loop and Graph Engineering

What I learned

The biggest lesson is that a serverless blog should not be treated as a toy static page. Once publishing, images, metadata, admin operations, analytics, and sitemaps enter the picture, the system starts to look like a small CMS.

Cloudflare Workers can handle that shape well, but only if the storage model stays simple and the routes remain deliberate.

For 1001020, the result is a compact publishing stack that can run globally without a traditional backend server:

• live site: https://blog.1001020.xyz/
• AI gallery: https://blog.1001020.xyz/gallery
• example article: https://blog.1001020.xyz/article/agent-harness-loop-graph-engineering

I am still iterating on the publishing workflow, but the core system is now stable enough to share.

Half the market is arguing about whether RAG or a semantic layer is the right foundation for enterprise AI.

They are not competing. They answer different questions, and most teams need both.

Two shapes of question

Every question an agent receives breaks into one of two forms:

• "What did we say about X?" — lives in contracts, policies, tickets, docs. Unstructured. RAG was built for this.
• "What is true about X?" — lives in your warehouse and governed metrics. Structured. A semantic layer was built for this.

Treating them as rivals is how teams end up with a system that can quote the pricing policy but cannot tell you this quarter's realised price.

Where each one breaks

The permissions row is the one that ends pilots. A retrieval index that ingested everything has, by construction, assembled your most sensitive object — and reconstructing entitlement at query time is guesswork.

The layer that actually decides

Neither a document chunk nor a metric definition is worth much until something compiles it into a governed query and runs it.

That is the piece most architectures are missing: intent → context resolution → constrained planning → governed execution. RAG can feed the first step. It cannot perform the last three.

Point an agent at raw tables and the best models score in the low teens on real enterprise data. Give the same model compiled, governed context and it clears the high nineties. The retrieval quality was never the bottleneck.

The full breakdown — the precise division of labour, why hybrid architectures win, and how compile-time governance closes the gap RAG cannot — is here: