Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX

[BorisTyshkevich]

Summary

Make Dashboard a first-class, independently constructible product module instead of deriving it directly from favorited saved queries and global AppState.

For the v1 product UX, keep the current simple model:

The browser has one current workspace. That workspace contains one ordered query collection and zero or one editable Dashboard. Starring a panel query adds one default tile to that Dashboard; un-starring removes that default tile.

Do not add dashboard collection management, dashboard folders, dashboard CRUD screens, or multi-dashboard authoring UX in this issue.

At the architecture and format level

[BorisTyshkevich]

Normative additions: canonical output, resource limits, and atomic commands

These requirements are part of the implementation contract for this issue and supersede any earlier examples that imply non-deterministic serialization, unbounded resources, or infallible authoring mutations.

---

1. Canonical output ordering

All codecs, exporters, validators, and import planners must produce deterministic output. Do not rely on incidental JavaScript object insertion order or asynchronous validation completion order.

Dashboard semantic order

dashboard.tiles[] remains authoritative and must be preserved exactly. It defines:

• semantic tile order;
• flow-layout order;
• DOM and keyboard traversal order;
• default execution planning order;
• print/export order;
• drag/keyboard reorder results.

Query order for one Dashboard dependency closure

When exporting or materializing one Dashboard dependency closure:

1. Traverse dashboard.tiles[] in semantic order.
2. Emit each tile queryId at its first occurrence.
3. Traverse dashboard.filters[] in filter-definition order.
4. Emit each sourceQueryId not already emitted.
5. Emit every query at most once.
6. Dashboard v1 emits no Setup execution dependencies because Setup is unsupported.

Example:

Tiles:   q3, q1, q3
Filters: q8, q1
Output:  q3, q1, q8

Full current-workspace export

For a full current-workspace export:

• emit the current Dashboard when present;
• preserve workspace query catalog order in queries[];
• do not reorder the complete query collection according to Dashboard references.

The full workspace export represents authoring state, while a Dashboard-only export represents a dependency closure.

Multi-Dashboard portable output

The Portable Bundle schema may carry multiple Dashboards even though the v1 Workbench manages one.

For canonical output generated by codecs/tools:

1. sort Dashboards lexicographically by normalized Dashboard ID;
2. emit referenced queries by first reference across that canonical Dashboard order;
3. within each Dashboard, use tile order followed by filter order;
4. append unreferenced queries in their existing catalog/input order;
5. emit each query once.

Do not assign product meaning to incidental dashboards[] insertion order. If Dashboard catalog order becomes a product requirement later, model it explicitly.

Canonical object serialization

Implement one canonical JSON encoder used by exports, normalized-content comparison, snapshots, and content hashing.

Rules:

• schema-defined object fields use a documented canonical order;
• arrays preserve their semantic order;
• map-like keys such as layout.items, presentation variant names, and field-column maps are sorted lexicographically;
• open extension/config objects are recursively key-sorted;
• object key order carries no domain semantics;
• do not duplicate ad hoc sorting logic across UI, exporter, and importer code.

Diagnostic ordering

Sort diagnostics before returning or rendering them, even when validation work ran concurrently.

Canonical comparison:

1. severity: error, warning, information;
2. exact path using numeric-aware path-segment comparison;
3. diagnostic code;
4. resource/source ID when present;
5. message as the final tie-breaker.

Numeric-aware ordering must place index 2 before index 10.

Add one shared compareDiagnostics implementation and use it across Dashboard, Portable Bundle, workspace migration, command validation, and import planning.

---

2. Explicit resource limits

Portable documents and Dashboard runtime plans must be bounded. Enforce limits both in generated JSON Schema where possible and in codecs/runtime where byte size, depth, or dependency closure cannot be expressed reliably by JSON Schema.

Initial v1 limits:

const PORTABLE_LIMITS = {
  maxDecodedJsonBytes: 10 * 1024 * 1024,
  maxJsonDepth: 64,

  maxQueries: 1000,
  maxDashboards: 32,

  maxTilesPerDashboard: 100,
  maxFiltersPerDashboard: 32,
  maxLayoutItemsPerDashboard: 100,
  maxSetupReferencesPerDashboard: 0,

  maxVariantsPerQuery: 32,

  maxIdLength: 256,
  maxNameLength: 512,
  maxTitleLength: 512,
  maxDescriptionLength: 16 * 1024,

  maxSqlLength: 1024 * 1024,
  maxSerializedQuerySpecBytes: 1024 * 1024,
  maxSerializedLayoutConfigBytes: 256 * 1024,
  maxSerializedFilterDefaultBytes: 64 * 1024,
} as const;

The exact constants may be revised during implementation only with an explicit rationale in the PR. Do not leave limits unspecified.

Schema-enforced limits

Use JSON Schema for:

• array maxItems;
• object maxProperties;
• string maxLength;
• ID/title/description bounds;
• tile/filter/Dashboard counts;
• layout item counts;
• presentation variant counts.

Codec/runtime limits

Enforce outside JSON Schema:

• UTF-8 input bytes before parsing where the source API permits it;
• decoded/normalized serialized byte size;
• nesting depth;
• byte size of open extension objects;
• Dashboard dependency-closure size;
• layout.items count not exceeding both the configured maximum and the actual tile count;
• important limits again before runtime session construction.

maxLength is not a substitute for UTF-8 byte limits.

All limit failures must produce stable, exact-path diagnostics containing the configured limit and actual value where available. Do not partially import, migrate, or execute an oversized document.

Preserve compatibility with existing valid Library v1/v2 inputs: keep the current 1,000-query ceiling and choose generous per-resource bounds intended to reject pathological input rather than normal SQL or Specs.

---

3. Fallible and atomic authoring commands

Earlier method signatures such as:

addQuery(queryId: string): DashboardTileV1;
moveTile(tileId: string, toIndex: number): void;

are illustrative only and must not imply that authoring mutations cannot fail.

Separate draft version from persisted revision

DashboardDocumentV1.revision increments only after a successful workspace persistence commit. Draft commands must not increment or return a new persisted revision.

Maintain a separate monotonic draftVersion for in-memory authoring concurrency.

type DashboardCommandResult<T = void> =
  | {
      ok: true;
      value: T;
      document: DashboardDocumentV1;
      draftVersion: number;
    }
  | {
      ok: false;
      diagnostics: DashboardDiagnostic[];
      draftVersion: number;
    };

Persistence uses a separate result:

type WorkspaceCommitResult =
  | {
      ok: true;
      workspace: StoredWorkspaceV1;
      dashboardRevision: number;
    }
  | {
      ok: false;
      diagnostics: WorkspaceDiagnostic[];
    };

Command model

Prefer typed commands over direct signal/document mutation:

type DashboardCommand =
  | { type: 'add-query'; queryId: string }
  | { type: 'add-query-instance'; queryId: string; variant?: string }
  | { type: 'remove-tile'; tileId: string }
  | { type: 'move-tile'; tileId: string; toIndex: number }
  | { type: 'update-tile'; tileId: string; patch: DashboardTilePatch }
  | { type: 'update-placement'; tileId: string; placement: JsonObject }
  | { type: 'change-layout'; layout: DashboardLayoutDocumentV1 };

interface DashboardAuthoringSession {
  readonly state: ReadonlySignal<DashboardAuthoringState>;

  execute<T = void>(
    command: DashboardCommand,
    options?: { expectedDraftVersion?: number },
  ): Promise<DashboardCommandResult<T>>;

  commit(): Promise<WorkspaceCommitResult>;
  createPortableBundle(): PortableBundleV1;
  destroy(): void;
}

Commands may be asynchronous because layout loading/normalization can require a lazy module.

Atomic command pipeline

Every command must run through one transaction-like pipeline:

current draft
→ clone/build isolated candidate
→ apply command
→ normalize using active layout plugin
→ validate document structure
→ validate query references and roles
→ validate placement and resource limits
→ sort diagnostics canonically
→ replace current draft only when fully valid

On failure:

• return diagnostics;
• leave the previous draft/document unchanged;
• do not partially mutate signals, layout maps, or tile order;
• do not increment draftVersion;
• do not invoke persistence.

On success:

• atomically replace the draft;
• increment draftVersion once;
• mark the authoring session dirty;
• do not increment persisted Dashboard revision until commit() succeeds.

Expected failures

add-query can fail because:

• query does not exist;
• query role is not panel;
• a default tile instance already exists;
• tile/resource limit would be exceeded;
• default presentation variant is invalid;
• no valid placement can be normalized.

Use add-query-instance for an intentional duplicate instance.

move-tile can fail because:

• tile does not exist;
• index is outside 0..tiles.length - 1;
• expected draft version is stale.

Do not silently clamp invalid indexes.

update-placement can fail because:

• tile does not exist;
• placement contains unknown flow@1 fields;
• span/height is invalid;
• selected layout plugin rejects or cannot normalize it;
• placement/config exceeds resource limits.

change-layout can fail because:

• plugin or requested version cannot load;
• fallback is invalid;
• existing placements cannot be normalized;
• normalized output violates the target layout schema.

The previous draft and active layout must remain intact.

Optimistic draft concurrency

Support optional expectedDraftVersion for delayed UI work and future AI/MCP commands.

A stale command returns a stable dashboard-command-stale diagnostic and does not apply.

Persistence failure semantics

A valid draft may remain dirty when persistence fails:

draft changed
commit fails
→ draft remains available for retry
→ committed workspace remains unchanged
→ Dashboard revision remains unchanged

Command atomicity applies to the draft. WorkspaceRepository atomicity applies to durable persistence.

---

Additional acceptance criteria

• Dashboard-only dependency closure uses deterministic first-reference query ordering.
• Full workspace export preserves query catalog order.
• Multi-Dashboard canonical output and object-key serialization are deterministic.
• Diagnostics have one canonical, numeric-aware ordering across all validation paths.
• Schema and runtime enforce concrete resource, string, depth, and byte limits.
• Oversized input cannot partially import, migrate, open, or execute.
• All authoring mutations use fallible typed command results.
• A failed command leaves the previous draft byte-for-byte/structurally unchanged.
• draftVersion is distinct from persisted Dashboard revision.
• Stale expected draft versions fail without mutation.
• Export, validation, and preview never increment Dashboard revision.
• Persistence failure keeps the valid draft dirty and leaves the committed workspace/revision unchanged.
• Unit tests cover canonical ordering, diagnostic sorting, every configured limit boundary, atomic command failure, stale commands, and failed commit retry behavior.