Dashboard v1 phase 1 (#280): contracts, codecs, canonical encoding, resource limits

[BorisTyshkevich]

Part of #280 (Dashboard as a first-class module). Phase 1 of 6. The normative spec lives in #280 — this issue tracks scope, order, and the decisions this phase must settle.

Goal

All new contracts exist as canonical JSON Schemas with generated types/validators, a canonical deterministic encoder, sorted diagnostics, and enforced resource limits — before any persistence or UI work begins.

Scope (from #280 "Phase 1: contracts and codecs")

• Schemas via the existing manifest pipeline (build/schema-manifest.mjs → generated types + Ajv-compiled validators): stored-workspace-v1, dashboard-v1, portable-bundle-v1, plus filter definition, presentation patch, flow@1, and layout fallback.
• Canonical encoder (one encoder for export, persistence snapshots, hashing, equality, snapshot tests) implementing Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 "Canonical output ordering": semantic array order, documented field order, lexicographic map keys, recursive key-sort of open config objects.
• Deterministic diagnostic sorter (severity → numeric-aware path → code → resource ID → message).
• Resource-limit enforcement (PORTABLE_LIMITS in Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280): schema-level bounds where expressible, codec-level UTF-8 byte size / depth / normalized-size checks, runtime re-checks.
• Whole-workspace semantic validation (cross-resource rules in Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 "Cross-resource semantic validation").

Decisions to settle in this phase

• query-spec-v1 extension for QueryDashboardPresentationV1 (variants, defaultVariant, sizeHints; existing dashboard.role from Dashboard: multi-filter option bundles, shared preview, and role-aware result selector #160 maps into it). Decide: in-place additive revision of query-spec-v1.schema.json vs a new version — fields are optional/additive, so a revision is the likely answer, but make it explicit and cover Spec-editor completion/validation.
• Limit consistency with the storage mechanism chosen in Phase 2: maxDecodedJsonBytes = 10 MiB exceeds typical localStorage origin quota (~5 MB). Either the Phase 2 repository is IndexedDB-backed or these limits come down; the schema constants must match that decision.

Dependencies

None on #276 — this is pure src/core/ + schemas/ + build/ work and can start while #276 finishes.

Tests

Per #280 "Required tests → Schemas, codecs, and limits": valid/invalid documents for every schema, every limit at boundary and boundary+1, deterministic encoding from differently-ordered equivalent inputs, deterministic numeric-aware diagnostic ordering, legacy-format conversion failures without partial import. 100% per-file coverage (core layer).

Acceptance

• All schemas land in the manifest; npm run generate:schemas output committed.
• One canonical encoder + diagnostic sorter used by all Phase-1 call sites.
• All Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 resource limits enforced with precise diagnostics.
• The two decisions above recorded in this issue and reflected in Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280.

[BorisTyshkevich]

Decision record (phase-1 pins, /ship-phase 2026-07-17)

query-spec-v1 extension for QueryDashboardPresentationV1: in-place additive revision. All new fields (dashboard.defaultVariant, dashboard.variants, dashboard.sizeHints; existing dashboard.role maps in unchanged) are optional and additive, so no new schema version — exactly the "likely answer" already recorded in this issue. Spec-editor completion/validation follows automatically from the schema-driven pipeline (#221) and is covered by tests in this phase.

Limit ↔ storage consistency: maxDecodedJsonBytes stays 10 MiB. Pinned jointly with the #284 storage decision: the Phase-2 WorkspaceRepository is IndexedDB-backed (IndexedDB is already required by Phase 6's one-time token handoff, and gives real atomicity + quota headroom that a single localStorage key cannot). The PORTABLE_LIMITS constants therefore land verbatim from #280.

Both to be reflected in #280 when the phase PR opens.