outcome-receipts

New here? Run the five-minute demo. It uses synthetic data, makes no network calls, and ends with the grounding gate refusing an invented number.

Draft funder outcome reports where every reported figure is a receipt. The tool reads a nonprofit's own service data, computes each required figure with a deterministic query, and attaches to that figure a receipt: the exact query, the count of rows it drew from, a content hash of that data slice, and a timestamp. It then drafts a narrative around the receipted figures and runs fail-closed grounding gates before and after suppression. Export is refused if any number in the drafted narrative, or in a chart, comparison, or reconciliation claim, does not trace to a receipt.

The gate reads those narrative and structured claims. It does not read every numeral in an exported file: the receipts section, the provenance block, and the trace page also print timestamps, row counts, slice hashes, and the text of each query, and those are receipt metadata rather than reported figures. Running the gate over a whole exported report.md reports them as unbound, which is the scope working as specified and not a gate failure.

Status: Beta. This tree declares 0.2.2, prepared for release and not yet tagged. The two versions before it stopped in different places and are worth keeping apart: v0.2.0 is a published GitHub release whose PyPI upload was never approved, and v0.2.1 is a signed tag with no release at all — the commit it names still declares 0.2.0, so it was never coherent, and it is left in place rather than moved. The newest version installable from PyPI is therefore 0.1.0; the newest GitHub release is v0.2.0. What remains is the maintainer's alone and is recorded in docs/RELEASING.md. The default path is deterministic, offline, and tested end to end. The release includes the completed privacy, verification, mapping, localization, multi-template, reconciliation, and optional Bedrock-drafting roadmap work. The v1 implementation package adds container self-hosting, stable report and artifact contracts, and six bounded evidence workflows; the v1 tag remains gated on real-organization, cross-release, and manual assistive-technology evidence. Bedrock is off by default and requires two explicit opt-ins. A committed eval (eval/report.md) scores the grounding gate. See CHANGELOG.md and SECURITY.md.

Last verified: 2026-09-13 · Recheck cadence: quarterly

Start here: run the five-minute synthetic demo, inspect the current evaluation, or bring an anonymized schema-mapping question.

Quickstart

Prerequisites: Python 3.12+, uv, GNU Make. This runs on synthetic data and makes no network calls:

git clone https://github.com/ChelseaKR/outcome-receipts.git
cd outcome-receipts
make install
.venv/bin/receipts run \
  --config examples/housing-demo/report.toml \
  --out out/demo \
  --approved-by "Demo reviewer"

A successful run prints grounding gate: PASS and writes the approved report, its receipts manifest, and a funder-facing trace view under out/demo/. The five-minute demo walkthrough continues from here — verifying the receipts and watching the gate fail closed on an invented number — and Usage covers the full CLI.

Try it, review it, or contribute

• Try it: complete the synthetic demo and report where it passed or stopped.
• Review it: inspect the trace view, suppression behavior, and verification command, then ask a question in Discussions.
• Contribute: choose a bounded open issue or follow CONTRIBUTING.md. Documentation, accessibility review, and practitioner feedback are useful contributions.

The problem

Funders are starting to reject reports that are "substantially AI-developed," because a language model that writes plausible outcome numbers is a liability, not a help. The fix is not to ban the model; it is to make the numbers come from the data and prove it. The verify-or-flag idea is published, and one commercial tool markets deterministic record-cited reporting. The contribution here is the open, offline chain — compute with a receipt, draft, fail-closed grounding gate, export with a receipts manifest — plus a fail-closed review queue for mapping explicit requirements onto schema-variant exports, and a privacy posture (aggregate, small-cell-aware) a human-services org can defend.

How it works

compute → draft → ground → suppress → re-draft/re-ground → approve → export

1. Compute with receipts. Author-declared data checks run first. Service data is then loaded into an in-memory SQLite database and every metric is computed by SQL. Each figure carries the query, row count, slice hash, value, definition, and timestamp that produced it.
2. Draft and ground the raw result. The deterministic drafter fills {metric_id} placeholders. If the optional Bedrock drafter is enabled, it may rewrite the prose but receives no source rows, identifiers, SQL, hashes, or paths. Every numeric span must match a receipted display exactly.
3. Apply the privacy boundary. Counts from 1 through 10 are suppressed under the CMS-modeled default. Complementary, delta, and percentage controls prevent straightforward arithmetic recovery; true zeros remain visible. Every publishable surface is rebuilt from the redacted figures.
4. Ground again and approve. The redacted narrative, charts, comparison, and reconciliation views pass the same fail-closed gate. A named human then signs off on the final artifact.
5. Export and seal. The report, receipts manifest, trace view, charts, bundle manifest, and hash-chained ledger entry are written. Optional keyed signing seals the bundle; verification commands detect later drift or tampering.

The load-bearing invariant is unchanged: numbers never come from a model. A model may write prose only when explicitly enabled, and any numeric invention or alteration blocks export.

Usage

Prerequisites: Python 3.12, uv, GNU Make, and a clone of this repository. Docker with a running daemon is also required for the full contributor verification gate and container path, but not for ordinary Python CLI use. Install the locked development environment and activate it:

make install
source .venv/bin/activate

make install creates .venv, installs the locked Node/browser dependencies, and installs the checksum-verified security scanners consumed by make verify. It does not modify the parent shell's PATH; you can use .venv/bin/receipts instead of activating it. make install-smoke runs the same install and then asserts that the complete verification toolchain exists.

Run the bundled demo:

receipts run --config examples/housing-demo/report.toml --out out --approved-by "A. Reviewer"

Or run the same deterministic demo in the locked-down container:

make container-demo

See container self-hosting for an organization-owned spec and the mount, identity, and backup boundaries.

loaded examples/housing-demo/services.csv: 12 rows, 5 columns, digest b8b5e05adefaa26f
figures computed: 4
chart and comparison numbers: 0 (bound 0, unbound 0)
numbers in 'report' narrative: 1 (bound 1, unbound 0)
suppression policy: applied (threshold 11; hidden 3)

grounding gate: PASS
  approved: A. Reviewer
  report:   out/report.md
  receipts: out/receipts.json
  trace:    out/trace.html
  bundle:   out/bundle.json (digests-only)
  ledger:   export-ledger.jsonl (entry 0, hash …)

It writes out/report.md (the narrative, provenance, and receipts appendix), out/receipts.json (machine-readable receipts and provenance), out/trace.html (a funder-facing trace view), and out/bundle.json (digests for the complete export). Runs also append to export-ledger.jsonl by default. Specs with charts add accessible SVG files under out/charts/.

A spec may also bind the funder's requirement document. Then the export must account for every requirement in it — answered by a metric, withheld because small-cell suppression hid the cell, or declared unanswerable with a blocker receipts map actually reproduces and a reason a person wrote — or it names the requirement, writes nothing, and exits 4. See Proving the report answered the requirement set.

An export also needs a named human sign-off. --approved-by NAME records the approver non-interactively; without it, an interactive run prompts you to type your name after the grounding gate passes, and a non-interactive run aborts with exit code 3 and writes nothing. The approver and the approval time are recorded in the provenance statement of the report and in the receipts manifest (provenance.approved_by, provenance.approved_at; approved_by is null when nothing was approved, which no export should ever carry).

Requiring more than one signature

Boards and contracts often require two people, a program lead and a finance lead. A spec can say so, and then the requirement travels with the report definition rather than with the flag whoever ran the export happened to type:

[approval]
required = ["program", "finance"]

receipts run --config report.toml --out out \
  --approve program:"A. Lee" --approve finance:"B. Cruz"

A run missing a required role writes nothing and exits 3 naming the role. The same person cannot fill two roles; the comparison folds case and internal whitespace, so A. Lee and a. lee are one person. --approved-by is refused against a role policy, because a policy a different flag can satisfy is not a policy. An interactive run prompts once per unfilled role.

Each approval is recorded in the manifest under provenance.approvals with its role, approver and timestamp, and provenance.approved_by names every approver so a reader that only knows that field still reads a complete answer. receipts verify --bundle re-reads the policy from the spec, so a bundle stops verifying if the policy later gains a role or an approval is edited out of the manifest. restate, contract-check and equity-review honour the same policy. A spec with no [approval] section behaves exactly as it did before.

Minimal report specification

A report spec identifies the CSV, narrative template, and deterministic query for each placeholder. Paths resolve relative to the TOML file.

schema_version = "1.0"

[data]
path = "services.csv"

[report]
title = "Housing outcome report"
template = "We served {clients_served} clients."

[metrics.clients_served]
description = "Unduplicated clients served"
definition = "Distinct clients with an enrollment in the reporting export."
kind = "output"
unit = "count"
value_sql = "SELECT COUNT(DISTINCT client_id) FROM data"
slice_sql = "SELECT client_id FROM data"

See examples/housing-demo/report.toml for a complete spec and receipts init --data services.csv --out report.toml for a fail-loud starter containing the source-column inventory. The public spec and manifest compatibility rules are in Specification and manifest stability.

Privacy defaults

Exports are structurally aggregate-only: source client rows never enter a report renderer. The default suppression policy is modeled on CMS guidance: count cells from 1 through 10 are redacted, true zeros are preserved, and complementary suppression closes arithmetic recovery paths through totals, deltas, and percentages. HUD requires anonymous aggregate publication but does not prescribe this numeric floor, so the policy governing a particular report remains the operator's responsibility. See the data card, the DPIA findings, and the historic suppression ADRs in docs/decisions. The default is calibrated against real, non-synthetic data: running the engine over HUD's own 2024 CoC Point-in-Time subpopulation counts is findings, gated by a recomputation test.

A withheld cell is never a zero. In receipts.json its receipt carries suppressed: true and null for value, row_count, slice_hash, and column_names; a figure that is genuinely zero carries suppressed: false and a real 0; a figure that does not exist has no receipt at all. Three states, three distinguishable renderings, so a consumer reading the manifest cannot mistake "we cannot report this figure" for "we served nobody". The report appendix and the trace view show [SUPPRESSED] in place of the row count and slice hash for the same reason. See ADR 0009 for the reasoning and Specification and manifest stability for the manifest schema 2.0 change and the field mapping from 1.0.

Check a narrative against the receipts at any time:

receipts audit --config examples/housing-demo/report.toml --narrative some-draft.md

audit grounds against the figures the report may actually publish — the set run exports, after suppression — not against the raw computed figures. So it reports two distinct failures, and exits non-zero on either:

• a number that no figure backs (unbound); and
• a number that is the withheld value of a suppressed cell. That number does trace to a real receipt, which is exactly why grounding against the raw figures used to pass it. Writing it into a report publishes a protected count, so audit names the metric it discloses rather than calling it unbound.

A sentence carrying no numeral is invisible to all of that, so audit and run also check the narrative's comparative claims against the directions the comparison actually computed. "Placements rose" binds only when some declared comparison row's own direction is an increase; a claim every row contradicts is refused and named beside what the receipts say; a claim that agrees only with a row suppression withheld is reported as a disclosure, because writing it publishes a direction the comparison table itself redacts. Four families are detected and can never bind, for the reason a written-out numeral never binds: an evaluative word ("improved") needs a metric polarity no spec declares, a magnitude word ("doubled") needs a ratio nothing here computes, a quantifier ("most") needs a proportion of a total no figure states, and a superlative ("highest") needs a ranking the tool does not model. See ADR 0012, which also records what it deliberately leaves open.

--explain says why each of those numbers missed: which receipted displays are nearest and by how much, whether the miss is a rounding, a magnitude slip, a percentage written as a count, or the thousands/decimal ambiguity ADR 0011 deliberately refuses to resolve. It is advice; the verdict and the exit code are the same with and without it, and run --explain likewise explains a refusal without softening it.

--fixes-out writes that diagnosis as a reviewable JSON plan, and --apply-fixes applies a plan you have read, to a new file:

receipts audit --config report.toml --narrative draft.md --fixes-out fixes.json
receipts audit --config report.toml --narrative draft.md \
  --apply-fixes fixes.json --fixed-out draft.fixed.md

The applier substitutes only exact receipted displays, re-checked against the figure set at the moment it runs, and then re-runs the gate over the bytes it wrote. It refuses the plan whole — never in part — if the narrative has changed since the plan was built, if a replacement is not the current display of a publishable figure, or if a replacement would state a suppressed cell. A span two displays are equally near gets no fix at all: nothing in the text says which, so nothing is chosen for you.

run refuses to export in either case.

Templates, charts, comparison, and reconciliation

A report type is defined entirely by its TOML spec, so adding a report shape means adding a spec. Two more ship alongside the housing demo: a grant report and a board report.

receipts run --config examples/grant-report/report.toml --out out/grant --approved-by "A. Reviewer"
receipts run --config examples/board-report/report.toml --out out/board --approved-by "A. Reviewer"

The same receipted figure set can render into several [[report.templates]] formats for different funders. Optional charts, comparisons, and board reconciliations are held to the same gate as every narrative:

• Charts. A [[charts]] entry names the figures it draws. The chart's bars or points are those figures' values, so a chart has no data of its own; it is a rendering of numbers that already carry receipts. Each chart is written as a standalone SVG and paired with an accessible data table that carries the same numbers as text, so a chart is readable without the image and every number in it traces to a receipt. The SVG is built with the standard library, so no dependency is added. A withheld figure has no value to draw: its bar becomes a hatched, dashed full-height slot rather than a bar of height zero, a line chart breaks rather than interpolating through it, and it takes no part in the axis scale. A bar height is a claim, and the chart does not make one the text refuses to make. See ADR 0010.
• Period comparison. A [comparison] section runs one set of metrics across two periods (for example two quarters) and reports the change. The two period values and the change are each a figure with a receipt; the change is computed by a single SQL query that subtracts one period from the other, not by arithmetic on the page. Direction is reported as a word, so no ungrounded number is shown.
• Board reconciliation. A [reconciliation] section pairs receipted outcome figures with receipted financial lines over the same periods, including a grounded change log. No displayed ratio or delta is computed only on the page.
• Multi-funder output. Each [[report.templates]] entry gets its own output directory, report, manifest, trace, bundle, and ledger entry while reusing the same byte-identical figure set.

receipts run grounds all narrative and structured claims before and after suppression and refuses to export if any number is unbound.

Score the gate on the committed fixtures:

receipts eval --config examples/housing-demo/report.toml

The committed result is in eval/report.md. It scores the exported narrative — drafted and grounded after suppression, so it measures the artifact the pipeline actually writes rather than a pre-suppression draft it would never produce. That narrative grounds 100% of its numbers, so the gate passes. Because suppressed cells render as [SUPPRESSED] and carry no number, the denominator is the count of numbers that survive suppression, which the report states. That the gate catches an injected unverifiable number is shown by the merge-blocking test tests/test_grounding_gate.py.

The authoritative product roadmap has no remaining repository-side implementation items. Evidence gates for a v1 tag and the implemented bounded applications are in the roadmap and evidence use cases.

English and Spanish report output

Public report copy, approval language, reconciliation labels, chart alternative text, receipt metadata labels, and trace-view content are available in English and Spanish. Figures, SQL, hashes, and source data do not change across locales: a figure display is written the same way in every locale, with , grouping thousands and . marking the decimal, so a Spanish-reading funder sees 1,234 for one thousand two hundred and thirty-four.

The grounding gate reads prose in either convention, and its canonicalization preserves magnitude. 12.345,67 and 12,345.67 both bind a display of $12,345.67; 3,5 binds 3.5; NBSP-grouped 1 234 binds 1,234. One shape cannot be resolved from the text and is therefore refused rather than guessed at: a single separator with 1–3 digits before it and exactly 3 after (1.234) is a thousands group under one convention and a decimal point under the other, and the two readings are a factor of a thousand apart. A span in that shape binds only a display written the same way, so a narrative cannot state a number 1,000x its receipt and bind. See ADR 0011.

receipts run --config examples/housing-demo/report.toml --out out/es \
  --locale es --approved-by "A. Reviewer"

The CLI's operational messages remain English. See docs/I18N.md.

Optional Claude-on-Bedrock drafting

The deterministic drafter remains the zero-cloud default. Bedrock drafting needs the optional dependency, an enabled [report.drafting] policy with a model ID, and --allow-cloud-drafting on every run:

uv sync --locked --python 3.12 --group dev --extra bedrock
receipts run --config report.toml --out out --allow-cloud-drafting \
  --approved-by "A. Reviewer"

The first model request may contain small aggregate displays even though the published artifact is subsequently suppressed. Organizations must explicitly authorize that transfer and configure their Bedrock logging and retention policy. See docs/drafting.md, the model card, and the data card.

The trace view, the provenance statement, and re-derivation

Three things make the proof legible and checkable for the people who receive a report, none of which puts a model near a number.

• A definition on every metric. A figure is only as fair as its definition, so a metric can carry a plain-language definition (what window, who counts, the deduplication rule). It rides in the receipt and renders next to the figure, so a reviewer can see and contest the choice a query encodes without reading SQL.
• A trace view (out/trace.html). The receipts manifest is JSON, which a grant manager or program officer cannot read. The trace view renders the same receipts as one self-contained, accessible HTML page: a summary table of every figure with its value and definition, then the receipt behind each (the query, the row count, the slice hash, the timestamp). It opens offline and needs no SQL or Python.
• A provenance statement. Every export embeds a short, standard block stating that each figure was computed by a deterministic query, that no figure was written by a model, and that the grounding gate bound every number in the report's claims before export. The same attestation goes into the manifest as a machine-readable record, which separately names the deterministic or Bedrock narrative drafter used.

Re-derive a committed report to confirm it still holds:

receipts run --config examples/grant-report/report.toml --out out/grant --approved-by "A. Reviewer"
receipts verify --config examples/grant-report/report.toml --receipts out/grant/receipts.json

receipts verify recomputes every figure from the spec and the cited data and checks each value, slice hash, row count, and query against the manifest. A mismatch is drift (the data changed, the spec changed, or the manifest was edited); verify reports each drifted receipt and exits non-zero, so a silent divergence cannot pass.

The same check is packaged as a reusable composite GitHub Action so a downstream repo can gate CI on receipt drift with a commit-pinned action ref. See docs/ci-action.md for the workflow snippet and supply-chain pinning guidance.

Command guide

Run receipts <command> --help for the complete option reference. Every command supports --json before or after the subcommand.

The six evidence workflows are documented in implemented use cases. Their artifacts share the versioned workflow artifact schema. Rollup and equity review are experimental for real organizational data until their documented privacy and user-validation gates are complete.

CLI output and exit codes

Every command prints human-readable lines by default. Pass --json to any command to get a single machine-readable JSON object on stdout instead, with the prose suppressed. The JSON is purely presentational; it never changes the exit code.

receipts run --config examples/housing-demo/report.toml --out out --reproducible --approved-by CI --json
receipts verify --config examples/grant-report/report.toml --receipts out/grant/receipts.json --json
receipts map --data examples/housing-demo/services.csv --requirements examples/mapping/requirements.json --out mapping-review.json --json

The run object reports the gate result, figure and narrative tallies, any unbound numbers, the paths it wrote, the export-ledger entry it appended, and the recorded approval. Under --json there is no interactive sign-off prompt, so run needs --approved-by; without it the export aborts with exit code 3 and a null approval in the payload. The audit, verify, verify-bundle, verify-ledger, eval, diff, and cards objects report their own results and details; map reports pending or blocked candidates without executing them; init carries the scaffolded spec and where it was written.

verify reports its counts twice over, because two different things are checked and only one of them is a receipt. receipts_checked, receipts_ok and receipts_drift count receipts re-derived from the data. n_ok and drift are totals that also include the manifest's own descriptors — its declared schema_version and its hash block — which are compared against a constant and re-derived from nothing. Each entry in checks carries a kind of receipt or manifest saying which it is, so a script need not guess from the metric_id. verify-workflow reports every artifact-contract check, and each workflow command returns the artifact it wrote. The --json flag is accepted before or after the subcommand, so receipts --json run ... and receipts run ... --json are equivalent.

The exit code is the contract a script should read. It is stable across the human and JSON forms.

Publishing more than one report

An organization rarely publishes one report. It publishes a grant report, a board report, and a template per funder, each from its own spec. The receipts prove every figure in each one and prove nothing about the set, and an auditor holding five output directories has no page saying which reports exist, which still verify, and whether two of them state the same metric differently.

receipts portfolio \
  --specs examples/grant-report/report.toml examples/board-report/report.toml \
  --out out/portfolio --approved-by "A. Reviewer"
receipts portfolio-verify --dir out/portfolio

The batch takes no shortcut: each spec is exported by run itself, so the grounding gate, the requirement-coverage refusal, suppression and the human sign-off apply exactly as they do to a single report, and a spec's [approval] policy applies too. Every export appends to one shared ledger. The first spec that fails stops the batch, names itself, and returns its own exit code, and no portfolio record is written. Specs run in path order, so the batch is the same whichever order the arguments arrived in.

portfolio-verify re-verifies every bundle from its own spec and writes index.html: per report the gate result, who signed off, the bundle signature and digest, and the ledger entry, followed by the figures more than one report states. That table computes nothing. It compares what each report already published, and it keeps four outcomes apart:

The index is one static, script-free HTML file in EN or ES, held to the same WCAG 2.2 AA gate as the trace view.

Proving the report answered the requirement set

The project proves every published number traces to a receipt. That is one half of the claim. The other is that every required number was published, and it is the half an auditor checks first: a spec that simply omitted a required metric used to run, ground, be approved, and export a report that was fully receipted and silently incomplete.

Bind the spec to the requirement document receipts map already reads, and name the requirement each metric answers:

[requirements]
path = "requirements.json"

[[requirements.unanswerable]]
requirement_id = "R-4"
blocker = "no source column matches logical field 'return_within_180_days'"
reason = "The HMIS export carries no re-entry field. Returns are tracked in the continuum's separate quarterly reconciliation."

[metrics.clients_served]
requirement_id = "R-1"
# ...

Every requirement then lands in one of four states, and only three of them may be exported:

An unanswerable declaration needs both halves and neither is enough alone. A blocker without a reason is a tool's excuse; a reason without a blocker is unfalsifiable. So the declared blocker is re-derived at export by running the mapper over the same data and the same requirement document, and the declaration is refused unless the mapper produces that exact string. A requirement that maps cleanly cannot be declared unanswerable at all.

The coverage table renders in the report appendix in both locales, the requirement document's sha256 rides in receipts.json, and verify --bundle re-derives both — so editing the requirement document after export fails naming the digest, and doctoring the coverage record fails as a mismatch. A spec with no [requirements] binding is unchanged in every byte and its manifest carries no coverage key at all; verify --bundle says not checked, not ok.

receipts run --config examples/requirement-coverage/report.toml --out out --approved-by "Program director"

See ADR 0013 for the reasoning and for the one question it deliberately leaves to the owner.

What it does not do

• It does not let a model invent numbers. Figures come from queries; the gate enforces it.
• It is not a data warehouse or a BI tool. It computes the figures a report needs and proves them, then gets out of the way.
• It does not claim a new verification primitive. The verify-or-flag idea is published; the contribution is the open offline chain, the metric-mapping, and the privacy posture.

Standards conformance

This repo holds itself to the portfolio's shared engineering standards. The project-specific values live in docs/ROADMAP.md and docs/RESPONSIBLE-TECH-AUDITS.md.

License

Apache-2.0.

Project discussion

Use GitHub Discussions for setup and design questions. Use the structured issue forms to report a demo run or describe a mapping question. Never post client-level rows, identifiers, credentials, or real service exports.

Support

This is independent work, published so it can be read and checked rather than taken on trust. If your organization wants help making its outcome reporting traceable, get in touch.