accepted

`meta.warnings` stays `string[]`; public contract is the `[code]` bracket prefix

Warnings remain plain strings, but every warning starts with a bracket-prefixed code like `[envelope.no-overlap]`. Codes are public contract; prose may evolve. Consumers can grep codes reliably without a breaking type change.

LineChart warningsapipublic-contract

Context

Before the chart-reference-layers packet, model.meta.warnings was loosely typed as string[] and each component emitted free-form strings like "no series contained any finite (x, y) points". Grep patterns drift as prose evolves. Structured objects (e.g. { code: "envelope.no-overlap", message: "…" }) would be a breaking change across every chart’s warnings array.

Decision

Adopt the [code] bracket prefix convention. Every warning string begins with a bracket-prefixed stable code:

[envelope.no-overlap] envelope "req-pace": overlap interval empty (A [0,37], B [42,90])
[hidden.extends-x-domain] series "equality" extends x-domain to [0, 1] beyond visible series
[band.label-suppressed] band "mid": inside label hidden due to collision with higher-priority band

The code is stable public contract. The prose after the closing ] may evolve (better variable interpolation, clearer wording) without counting as a breaking change. Consumers who want to filter programmatically use regex like /^\[envelope\./ or exact startsWith("[envelope.no-overlap]").

Consequences

  • No type change to meta.warnings. Callers keep reading string[].
  • Every warning emitted by compute (both new and retroactively updated ones like [series.dropped-points]) carries a code.
  • Full warning taxonomy is documented in the chart-reference-layers spec §Warnings table.
  • Future migration to structured objects remains possible — the bracket prefix is a compatible subset. A future meta.warningCodes: WarningCode[] could sit alongside the existing string array without breaking callers.
← All decisions