Context
Today's meeting with Lars Vilhuber (AEA Data Editor), Tara Watson, John Sabelhaus, and the TRACE team (Tim Clark, Casper) landed on this framing: policyengine.org is the primary TRACE surface for us. When a researcher runs a simulation on policyengine.org, the institution (PolicyEngine) certifies the run on their behalf. The researcher / reader / reviewer of any paper that cites the result can verify it without having to re-run the simulation themselves, because the TRO binds all the inputs and outputs by SHA-256 and carries a PolicyEngine-side attestation.
The backend emission is scoped in PolicyEngine/policyengine-api#3485. This issue is the user-facing side.
What to build
Once the api emits a TRO URL alongside every simulation result, the app should expose it as a first-class citation surface. Three specific UI elements:
1. "Cite this result" button
Lives on every simulation result page (household impact, reform economy-wide impact, geographic impact, policy charts, etc.).
Clicking it:
- Opens a panel with a citation block — BibTeX / Chicago / APA formatted — that references the TRO URL as the persistent identifier
- Offers a "Download TRACE TRO" action → downloads the
.trace.tro.jsonld
- Offers a "Copy permalink" action → copies a
policyengine.org/{country}/trace/{tro-id} URL
- Shows the verification snippet:
policyengine trace-tro-validate path/to/trace.tro.jsonld
2. Version badge on every result
Small, always-visible, somewhere in the result header / footer. Reads:
rules us@1.653.3 · data enhanced_cps_2024.h5@1.78.2 · h5 sha256:a4f2...
Hover / click shows the full DataReleaseManifest fingerprint and links to the TRO. This is the most important single feature from Lars's / Tara's perspective: it makes the "rules changed vs data changed" question answerable at a glance.
3. Shareable TRO permalinks
Requirement: a result URL, when shared, should resolve to a page that renders the same numbers forever — even after we publish new models or new calibrated data. This means the result page must either:
- Store the TRO-ID in the URL and re-render by replaying the pinned bundle, or
- Store the result payload itself and render it without re-simulating
Either is acceptable; the former is more rigorous because it proves reproducibility on every load. Interaction with the existing session URL / share-link machinery is TBD (this is probably the biggest UX decision inside this issue).
Out of scope for this issue (follow-ups)
- "Replicate in Colab" button: the TRO contains the pip install line. A button that opens a Colab notebook with
pip install policyengine==X policyengine-{country}==Y policyengine-{country}-data==Z + the reform JSON pre-filled is a natural extension. Worth its own issue once the cite button ships.
- Diff view: "this result moved from $X to $Y between model release A and model release B — here's what changed in rules and here's what changed in data." Tara's user test for the whole architecture. Follow-up.
- In-app TRO validator: paste a TRO, see what it binds + whether the hashes still resolve. Follow-up.
Dependencies
Related
Context
Today's meeting with Lars Vilhuber (AEA Data Editor), Tara Watson, John Sabelhaus, and the TRACE team (Tim Clark, Casper) landed on this framing: policyengine.org is the primary TRACE surface for us. When a researcher runs a simulation on policyengine.org, the institution (PolicyEngine) certifies the run on their behalf. The researcher / reader / reviewer of any paper that cites the result can verify it without having to re-run the simulation themselves, because the TRO binds all the inputs and outputs by SHA-256 and carries a PolicyEngine-side attestation.
The backend emission is scoped in PolicyEngine/policyengine-api#3485. This issue is the user-facing side.
What to build
Once the api emits a TRO URL alongside every simulation result, the app should expose it as a first-class citation surface. Three specific UI elements:
1. "Cite this result" button
Lives on every simulation result page (household impact, reform economy-wide impact, geographic impact, policy charts, etc.).
Clicking it:
.trace.tro.jsonldpolicyengine.org/{country}/trace/{tro-id}URLpolicyengine trace-tro-validate path/to/trace.tro.jsonld2. Version badge on every result
Small, always-visible, somewhere in the result header / footer. Reads:
Hover / click shows the full DataReleaseManifest fingerprint and links to the TRO. This is the most important single feature from Lars's / Tara's perspective: it makes the "rules changed vs data changed" question answerable at a glance.
3. Shareable TRO permalinks
Requirement: a result URL, when shared, should resolve to a page that renders the same numbers forever — even after we publish new models or new calibrated data. This means the result page must either:
Either is acceptable; the former is more rigorous because it proves reproducibility on every load. Interaction with the existing session URL / share-link machinery is TBD (this is probably the biggest UX decision inside this issue).
Out of scope for this issue (follow-ups)
pip install policyengine==X policyengine-{country}==Y policyengine-{country}-data==Z+ the reform JSON pre-filled is a natural extension. Worth its own issue once the cite button ships.Dependencies
@policyengine/design-system/@policyengine/ui-kittokens — no new color paletteRelated