# Static dashboard specification

## Release status and language

The checked-in site is a **development preview** built from suppressed
aggregates derived from the private, page-sampled 10,000-vehicle development
cohort. Every value is a sample result, **not a population estimate**. The site
must not present statewide prevalence, county rankings, causal comparisons, or
individual predictions.

Use **Utah Vehicle Health** as the project name and **next-episode first-attempt
non-pass** for the modeled outcome. Non-pass combines fail, reject, and abort.
The dashboard is not a diagnosis, certification, safety assessment,
roadworthiness assessment, or guarantee.

## Implemented four-view prototype

### Overview

- Visibly persistent development-preview warning
- Rounded published support and sample pass/non-pass rates
- Sample first-attempt non-pass trend for approved, pre-2025 periods
- County **feed-coverage** map, with unavailable counties shown as unavailable
  rather than zero
- Sample non-pass pattern by coarsened vehicle-age band
- Plain-language target and limitations callout

County values provide sample/feed context only. They must not be sorted,
headlined, or described as population county performance.

### Sample cohorts

- Search and compare only supported, suppression-cleared make/model cohorts
- Combine documented source abbreviations and trim labels for newly published
  model families before applying the unchanged publication thresholds
- Keep earlier public cohort definitions stable across releases so differences
  cannot expose a formerly suppressed slice
- Identify Silverado 1500, Ram 1500, Elantra, Altima, Outback, 4Runner,
  Corolla, and Tacoma as combined families; identify F150, Accord, Civic, and
  Camry as exact source-label cohorts
- Show observed sample non-pass rates and rounded support
- Default sorting by support rather than risk
- Disable filters or adjusted views that the aggregate bundle cannot support
- Explain that omitted cohorts may be suppressed or unavailable

These are descriptive development-sample cohorts, not reliability ratings,
causal make/model effects, or recommendations.

### Model & benchmark

- Identify calibrated logistic regression as the sole final prototype model.
- Identify calibrated histogram gradient boosting as benchmark-only.
- Show only pre-2025, 2024 calibration-fit diagnostics from the private sample.
- Explain that those same-partition values are calibration checks, not
  independent final-performance or population estimates.
- Keep the opened 2025 holdout comparison in the private report/presentation,
  not in the browser bundle.
- State plainly that the finished prototype has no vehicle-level prediction
  service, personal input form, or row-level output.

### Data & methods

- First-attempt returning-vehicle episode and binary-target definitions
- Point-in-time feature and leakage controls
- Coverage timeline by source era
- Chronological development-sample split and one-time 2025-gate disclosure
- Evidence-governance summary for the logistic final model and tree benchmark
- Known sampling, coverage, label, validation, and interpretation limits
- Private-to-public publication flow

The boosted tree appears only in benchmark context, never as a second final
model. The dashboard never requests a VIN, plate, ZIP, exact address, station,
technician, free text, or current-test diagnostic.

## Public data contract

| Asset | Allowed content |
| --- | --- |
| `data_manifest.json` | Release ID, model versions, scope flags, definitions, and suppression settings |
| `overview_period_county.json` | Suppressed quarter x covered-feed county sample aggregates |
| `cohort_scorecard.json` | Suppressed make/model sample aggregates with rounded support |
| `age_risk_curve.json` | Suppressed sample rates by coarsened vehicle-age band |
| `filter_catalog.json` | Publishable categories and supported periods |
| `model_diagnostics.json` | Train/tune/calibration development metrics only; no 2025 metrics |
| `coverage_quality.json` | Source-era availability by year |
| `sha256_manifest.json` | Checksums for the approved bundle |

Every JSON asset must declare `development_preview=true` and
`population_estimate_allowed=false`. The public manifest must declare
`locked_test_metrics_published=false`. The browser validates the complete bundle
and shows no estimates if any required asset fails its contract.

The browser bundle must never contain raw analytical rows, prediction lookup
rows, hidden unsuppressed chart layers, or values recoverable only through the
developer console.

## Suppression and privacy controls

- Require at least 100 eligible episodes and 100 distinct private vehicles per
  published cell.
- Require at least 10 observations and 10 distinct vehicles in both binary
  outcome classes.
- Apply complementary suppression when a visible total could reveal a hidden
  cell.
- Combine rare categories, coarsen age/year fields, and round support.
- Recheck thresholds for the exact grain of every released asset.
- Omit suppressed rows entirely; do not send them to the browser.
- Publish no VIN, plate, ZIP, exact address, station, technician identifier,
  private token, raw JSON, credential, operational record, free text, or
  row-level prediction.
- Make no browser or hosted-service connection to `countydata`.

## Accessibility and visual behavior

- Use semantic headings, landmarks, labels, status messages, and keyboard-
  reachable navigation.
- Provide text alternatives or accessible labels for charts.
- Do not rely on color alone.
- Use a restrained Utah/desert palette and direct probability/rate encodings;
  avoid gauges and decorative risk scores.
- Preserve the warning banner and fail-closed unavailable state on desktop and
  mobile layouts.

## Demo boundary

The current delivery is a same-network live demo started with
`node dashboard/server.mjs --lan`. The local server resolves files only beneath
`dashboard/` and serves only its explicit shell, JavaScript, stylesheet, and
approved aggregate allowlist. It does not expose `.env`, private `data/`, model
artifacts, SQL, pipeline scripts, or repository history. Stop the server after
the demo; no public hosting step is required.