Repository navigation
Accountability Rules
Matching a promise to a press release sounds easy until you meet real public spending. Contracts get cancelled after the good news was published, budgets get quietly amended mid-year, the work turns out to belong to a different public body, and a pothole repair gets counted as climate adaptation. This page covers the rules Paper Trail uses so it doesn't fall for that. It starts with four guarantees the system never breaks, then goes through six audit rules, explaining for each one what it protects against, how it works and where it stops working.
If you're a reviewer, this is where a warning's meaning gets explained. If you're a journalist, it tells you what the output can and can't back up. And if you're changing the rules, it's the spec.
These hold for every row, all the time, and a change that weakens any of them won't be merged (Contributing).
The first and biggest one is that nothing enters the public record without a human click. The pipeline only ever suggests things: candidates, links, relationships, asset owners. A commitment exists only because a person confirmed a candidate, and evidence only counts because a person accepted a link. In the code, the review service is the only thing that writes decisions. In the database, the worker's login simply doesn't have permission to accept a candidate, accept a link or create a commitment, and the worker checks this when it starts and refuses to run if it's been given a more powerful login (Database).
That rule only works if people can check what they're clicking on, which is where the second guarantee comes in: receipts or nothing. Every candidate carries a page and a verbatim quote that Paper Trail found on that page itself, and a candidate without a verified receipt can't be confirmed. Every piece of evidence likewise carries its URL and the exact passage.
Third, reviewed rows are final. Re-running a search never rewrites evidence or links a person has already decided on. The search skips sources that have already been decided for that commitment, database triggers reject any worker update to a reviewed link or its evidence, and maintenance reset only deletes machine output.
And fourth, status comes from the text. If the trail says "completed", that's because an accepted source says so. Paper Trail never infers progress from a deadline passing, and it only takes status from evidence a person accepted as direct implementation.
Put together, the flow of power looks like this:
flowchart LR
W["Worker<br/>machine output"] -->|"may insert"| S["candidates, evidence,<br/>links (unreviewed), money"]
S --> H{"Person with<br/>the review key"}
H -->|"only path"| R["commitments,<br/>accepted links"]
W -.->|"database refuses"| R
The six rules below all behave the same way. They're deterministic, meaning they're built from word lists and regular expressions rather than a model, so when one gets something wrong you can see why and fix it. They only read the matched passage, never the whole document, because a 100-page annual report contains every cue word somewhere. And they only ever hint: they can add a warning, lower the machine's suggested relationship or add a finding to the trail, but none of them can accept or reject anything. A reviewer is always free to accept a flagged passage.
The cue words themselves aren't in the code. They live in the language profile in the database (ml/lang.py defines the shape, and maintenance profile import loads one), and the examples on this page come from the Hungarian profile. The rules are in ml/accountability.py (PassageAuditor and FinancialAuditor) and services/gazetteer.py (PlaceResolver).
Real procurement rarely maps one promise to one document. A single framework contract might cover 45 streets, or a project might be chopped into small contracts to stay under the procurement thresholds, and a one-promise-to-one-document matcher misses both cases.
So every passage is scanned for official ids using the profile's patterns: Hungarian public procurement numbers (EKR followed by 9 to 12 digits) and EU programme codes (VEKOP-…, KEHOP-…, TOP-…, GINOP-… and others). Each id becomes one implementation artifact, and every passage that names it gets attached to it in the artifact_evidence table. That way one contract can connect to many commitments, and one commitment to many contracts. Because search works on passages, a street name buried in a 200-page framework annex can still be found.
In the workspace, these ids show up as grey chips on a match card.
Once contracts are tracked as artifacts, the next problem is contracts that die. A project gets budgeted and tendered, and months later the contract is cancelled or substantially changed, while the old evidence keeps cheerfully saying "under way".
To catch that, every passage gets a polarity:
| Polarity | Hungarian cues (examples) | Meaning |
|---|---|---|
| affirmative | none of the below | the passage describes the work |
| amendment | szerződésmódosítás (contract amendment), határidő-módosítás (deadline change) | the work was changed |
| termination | meghiúsult (fell through), eredménytelen (unsuccessful tender), felmondta (terminated) | the work was cancelled |
Termination beats amendment, so something amended and then cancelled counts as cancelled. An amendment or termination also escalates the status of every artifact the passage names, from active to amended to terminated, and it never goes back.
That escalation then spreads to everything else connected to the contract. Every other passage naming the same artifact gets a "Later amended or cancelled" warning, and because that's worked out when the evidence is read, it even reaches evidence a reviewer accepted before the cancellation turned up. Flagged passages never get a machine suggestion above "related, but indirect". Accepted direct-implementation evidence carrying the warning stops moving the commitment's status, and the trail lists an audit finding that names it. A termination passage itself is never read as progress either, and its status hint is just "unclear".
Money has its own tricks. A planned appropriation gets reported as money spent while mid-year amendments have quietly removed it, or a number from a press release stands in for audited accounts.
To deal with that, each money figure in a passage is parsed exactly, with regular expressions rather than a model, so "2,5 millió Ft" becomes exactly 2,500,000 HUF. Then it's given one budget state based on the cue words in its sentence:
| State | In the UI | Typical source |
|---|---|---|
estimated_cost |
estimated cost | the strategy itself |
initial_appropriation |
budget appropriation | the budget decree (költségvetési rendelet), grant awards |
amended_appropriation |
amended appropriation | mid-year budget amendments (módosított előirányzat) |
contracted_price |
contracted price | the signed contract |
actual_expenditure |
spent (final accounts) | the final accounts decree (zárszámadás) |
reported_expenditure |
reported spending, unverified | a report says it was paid, but it wasn't audited |
States are never summed or merged, and currencies stay separate too, so EUR is never converted into HUF. Small local amounts below the profile's floor (10,000 HUF for Hungarian) get ignored as noise.
The bar for calling something financially executed is high on purpose. A commitment only counts as executed if there's an accepted actual_expenditure figure or a signed technical handover record (műszaki átadás-átvételi jegyzőkönyv). Anything short of that shows up as a finding on the trail, like "Spending is only reported, not confirmed by the final accounts.", "Money was appropriated but no final accounts figure or completion certificate confirms it was spent." or "2023: 12 000 000 HUF of the appropriation was not spent (38 000 000 of 50 000 000)." That last kind compares the latest appropriation with the final accounts, and only within the same year and currency.
Some false gaps come from looking in the wrong place altogether. A district doesn't own the water mains, the district heating network or the main roads, so if you only search the district's websites you end up concluding "the district never did it" when the utility actually did.
That's why each commitment has an asset owner: district_municipality, metropolitan_municipality, public_utility_water, public_utility_heating or national_government. It's suggested from the wording when the commitment is confirmed, using cues like vízmű (waterworks), távhő (district heating), fővárosi (of the capital) or minisztérium (ministry), with the district as the fallback. The reviewer can change it with the Asset owner picker.
The evidence search then covers the registry sources with no owner (the municipality's own sites, which get searched for everything) plus the sources registered for that owner, and it adds the owner's name to the queries it sends to the owner's sites. Which domains belong to which owner is data in the official_sources table, not code, so adding a utility looks like this:
python -m paper_trail.maintenance source add https://www.vizmuvek.hu/hu/beruhazasok \
--publisher "Fővárosi Vízművek" --jurisdiction public_utility_water
python -m paper_trail.maintenance source listEven with the right owner, documents don't always name places the same way. The strategy says "Kálvária tér", while contracts and land records say "36542/1 hrsz.", which is a land-registry parcel number, and semantic search has no way to know they're the same place.
The fix is a local gazetteer, the places table, which holds the district's streets, squares and parks from OpenStreetMap (ODbL). You seed it once with scripts/ops/seed_gazetteer.py. When a passage contains a parcel number, a known parcel resolves to its street. An unknown one gets recorded as unconfirmed, along with the first street named in the same passage, so a person can check it later. Resolved street names are added to the passage's places, which the matcher then compares with the commitment's places.
Hungarian parcel registers aren't open data, so the parcel side of the gazetteer grows from the documents the pipeline reads. The worker can only add unconfirmed places, never confirm one.
The last trick is the most mundane: pothole repairs or burst-pipe fixes being counted as climate adaptation. If a passage uses maintenance wording (hibaelhárítás (fault repair), csőtörés (burst pipe), kátyúzás (pothole filling), javítás (repair)) without any upgrade wording (rekonstrukció, korszerűsítés (modernisation), felújítás (renovation), hőszigetelés (insulation)), it gets flagged "Maybe routine maintenance" and the machine's suggestion is capped at "related, but indirect".
One more rule doesn't fit the list but matters a lot in practice. A source published before the strategy's baseline year can only be background, because any "done" talk in it describes work from before the promise was even made. The baseline is BASELINE_YEAR, or if that's unset, it's guessed from the earliest /YYYY/MM/ in a document URL. The link's reasons spell it out, for example "published 2019 — predates the strategy, so it can only be context".
The rules don't understand meaning. A cancellation worded in a way that isn't on the list goes unflagged, and that's exactly why a person reviews every link. They also can't see documents the search never found, so a gap means "no accepted evidence on the official sources we searched", not "proven not done". And they're only as good as the language profile behind them, which means a new country needs its own cue lists and id patterns before any of this works there.
To see how these warnings and findings look to a reviewer, go to Reviewing. To see where these rows live and who's allowed to write them, go to Database.
Repository · GPL-3.0 · Nothing reaches the record without a human click · Something wrong here? Fix this wiki
Tutorial
How-to guides
Explanation
Reference