# Version the Dashboard collector boundary

## Traceability

- Spec ID: `2026-09-02-dashboard-collector-contract`
- Status: Implemented

## Intent

Make the private Harness Dashboard fail clearly when its out-of-process local
collector returns an unsupported or malformed document. The collector output
must identify its own contract version, and the server must validate that
contract before caching or projecting it into the UI.

## Acceptance Scenarios

- **AC-1 — Versioned collector document:** every successful local Dashboard
  collection emits `better-harness.dashboard-input` schema version 1 while
  preserving the existing workspace, evidence, usage, asset, and delivery
  projections.
- **AC-2 — Runtime boundary validation:** the server validates parsed collector
  stdout before it enters the project cache. Invalid JSON, an unsupported
  kind/version, missing or unknown top-level fields, incompatible nested source
  versions, and misaligned dated series fail collection instead of reaching the
  renderer through a TypeScript assertion.
- **AC-3 — Public capability composition:** the Dashboard collector imports
  Session Analysis and Agent Customize through their public `index.mjs`
  surfaces. Capability-private adapter registries are not imported directly.
- **AC-4 — Existing Dashboard behavior remains stable:** project isolation,
  refresh caching, current metrics, responsive rendering, and the local-only
  upload flow retain their current behavior.

## Non-goals

- Persisting, digesting, signing, or remotely uploading Dashboard snapshots.
- Defining cross-machine project, member, machine, or publisher identities.
- Making Harness Studio consume the Dashboard projection or introducing a new
  collector package.
- Adding cost, retry, intervention, or inferred Task-to-Session fields.
- Changing Dashboard hierarchy, charts, drill-down behavior, or visual design.

## Plan and Tasks

1. Add a capability-local JavaScript contract module that owns the Dashboard
   input kind/version and validates its bounded projection shape.
2. Emit the envelope from `collect-local-data.mjs` and validate parsed stdout in
   `local-data.server.ts` before caching it.
3. Export the required host/provider metadata and usage-summary builder through
   the existing Session Analysis and Agent Customize public surfaces, then
   route Dashboard imports through those surfaces.
4. Add focused contract tests and run the complete Harness UI test and build
   gates.

## Test and Review Evidence

- **AC-1, AC-2:** focused contract coverage validates the script-shaped empty
  aggregation plus rejection of invalid JSON, unknown versions, top-level
  drift, incompatible nested versions, and dated-series length mismatches. A
  live `codex` collection bounded to one Session passed the V1 validator.
- **AC-3:** the production build and complete test run resolve Session Analysis
  and Agent Customize through their public capability indexes; the Dashboard
  collector no longer imports their analyzer or provider registry paths. Three
  focused public-surface suites pass 108 Session Analysis and Agent Customize
  tests.
- **AC-4:** `npm test -w @qoder-ai/harness-ui` passes 46 tests across six files,
  including TypeScript validation. `npm run build -w @qoder-ai/harness-ui`
  succeeds with the existing 13 dynamic-filesystem tracing warnings.
- **Documentation:** the Better Harness routing graph remains at 39 files and
  56 links; `test/skills-docs/doc-link-graph.test.mjs` passes all eight tests.
- **Risk:** a strict boundary can expose previously tolerated fixture or source
  drift. The validator therefore owns only the Dashboard projection contract;
  capability-specific semantic validation remains with its existing producer.