@appinternalleads/ui 0.2.0

package/spec/output.schema.json

@@ -0,0 +1,1380 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "output/1",
+  "title": "Output block",
+  "description": "The output-widget wire contract. O1 (tasks/OUTPUT-WIDGETS.md, docs/HANDOFF-CONFLICTS.md §4c): `widget` is DECLARED by the producer, the renderer dispatches on it, and `chip` is a free label that never changes which component draws — the same declared-not-inferred shape `question/1`'s `type`+`control` pair already uses.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "slug",
+    "widget",
+    "title",
+    "payload"
+  ],
+  "properties": {
+    "schema": {
+      "const": "output/1"
+    },
+    "slug": {
+      "$ref": "#/$defs/slug"
+    },
+    "widget": {
+      "description": "The declared renderer. `stats`/`keyvalue` are engineering-complete; `delta`/`comparison`/`sequence`/`artifact`/`text`/`status`/`ranked`/`deck`/`diff`/`findings` are all implemented as of the Phase 27 pass (`tasks/OUTPUT-WIDGETS.md`). `quote` is NOT a separate widget — it is `payload.treatment: \"quote\"` on a `text` document. `list` (X7) is the first query-backed renderer: its payload is CONFIG, not rows — the rows come from a host `DataAdapter` (`docs/output-type-sheets/list.md`).",
+      "enum": [
+        "stats",
+        "keyvalue",
+        "delta",
+        "comparison",
+        "sequence",
+        "artifact",
+        "text",
+        "status",
+        "ranked",
+        "deck",
+        "diff",
+        "findings",
+        "list"
+      ]
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "chip": {
+      "type": "string",
+      "description": "A label override. Defaults to `widget`. Never changes dispatch — see the schema's own description."
+    },
+    "meta": {
+      "type": "string"
+    },
+    "mount": {
+      "enum": [
+        "read",
+        "write"
+      ],
+      "description": "`comparison`'s own read/write axis. `keyvalue` carries its own `mount: \"canvas\"|\"dashboard\"` inside its payload instead — see `keyValuePayload`, and `KeyValuePayload` in document.ts for why the two widgets don't share one vocabulary."
+    },
+    "phase": {
+      "enum": [
+        "loading",
+        "partial",
+        "settled"
+      ],
+      "default": "settled"
+    },
+    "payload": {
+      "type": "object"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "stats"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/statsPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "keyvalue"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/keyValuePayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "delta"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/deltaPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "comparison"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/comparisonPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "sequence"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/sequencePayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "artifact"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/artifactPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "text"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/textPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "status"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/statusPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "ranked"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/rankedPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "deck"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/deckPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "diff"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/diffPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "findings"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/findingsPayload"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "widget": {
+            "const": "list"
+          }
+        },
+        "required": [
+          "widget"
+        ]
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "$ref": "#/$defs/listPayload"
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case, the same rule question/1 uses."
+    },
+    "statsTrend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tone"
+      ],
+      "properties": {
+        "tone": {
+          "enum": [
+            "up",
+            "down",
+            "flat"
+          ]
+        },
+        "magnitude": {
+          "type": "string",
+          "description": "No arrow, no sign — \"18%\", \"2\". Omit for a flat trend with nothing to show."
+        },
+        "noBaseline": {
+          "type": "boolean",
+          "description": "D3 — the wire's explicit null baseline. Distinct from flat: no prior period at all."
+        }
+      }
+    },
+    "statsMetric": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable — keys the entrance animation. Never the array index."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Omit the key entirely while resolving (never send `null` for that). Explicit `null` once resolved to genuinely nothing — never `0`."
+        },
+        "trend": {
+          "$ref": "#/$defs/statsTrend"
+        },
+        "error": {
+          "type": "string"
+        },
+        "href": {
+          "type": "string",
+          "description": "Drillable only."
+        }
+      }
+    },
+    "statsPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "metrics"
+      ],
+      "properties": {
+        "metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/statsMetric"
+          }
+        },
+        "behaviour": {
+          "enum": [
+            "inert",
+            "drillable",
+            "trend"
+          ],
+          "default": "inert"
+        },
+        "heroId": {
+          "type": "string",
+          "description": "The metric id that leads as a hero tile spanning both columns (O9's recommended default)."
+        },
+        "loadingCount": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Skeleton tile count while `phase: \"loading\"` and `metrics` is empty."
+        },
+        "selected": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Drillable only."
+        }
+      }
+    },
+    "keyValueSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "locator",
+        "excerpt"
+      ],
+      "properties": {
+        "locator": {
+          "type": "string",
+          "minLength": 1,
+          "description": "e.g. \"page 2, line 18\"."
+        },
+        "excerpt": {
+          "type": "string"
+        },
+        "span": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "Character offsets into `excerpt`, highlighted on the evidence sheet."
+        }
+      }
+    },
+    "keyValueField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label",
+        "value"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable — keys the entrance animation."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "`null` = the document didn't contain it (\"Not found\"). `''` = present but blank (\"—\")."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Absent → read-only (O11) unless `editable: true`."
+        },
+        "editable": {
+          "type": "boolean"
+        },
+        "source": {
+          "$ref": "#/$defs/keyValueSource"
+        }
+      }
+    },
+    "keyValueThresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "flag": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "loud": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        }
+      }
+    },
+    "keyValuePayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fields"
+      ],
+      "properties": {
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/keyValueField"
+          }
+        },
+        "mount": {
+          "enum": [
+            "canvas",
+            "dashboard"
+          ],
+          "description": "Gates mutation entirely. Distinct from the top-level `mount`, which this widget doesn't use — see `KeyValuePayload` in document.ts."
+        },
+        "thresholds": {
+          "$ref": "#/$defs/keyValueThresholds"
+        }
+      }
+    },
+    "deltaRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "slug",
+        "label",
+        "value",
+        "tone"
+      ],
+      "properties": {
+        "slug": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {
+          "type": "string"
+        },
+        "magnitude": {
+          "type": "string",
+          "description": "A true minus (\"−38m\"), not a hyphen. Omit for `flat`."
+        },
+        "tone": {
+          "enum": [
+            "improvement",
+            "regression",
+            "flat"
+          ]
+        }
+      }
+    },
+    "deltaPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rows"
+      ],
+      "properties": {
+        "rows": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/deltaRow"
+          }
+        },
+        "loadingCount": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "comparisonOption": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label",
+        "attributes"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "winner": {
+          "type": "boolean"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Variation A: per-option, not a shared table — attributes do not line up across cards."
+        },
+        "error": {
+          "type": "boolean",
+          "description": "This option failed to evaluate — interim apricot treatment."
+        }
+      }
+    },
+    "comparisonPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "options"
+      ],
+      "properties": {
+        "options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/comparisonOption"
+          }
+        },
+        "selected": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "`mount: \"write\"` only."
+        }
+      }
+    },
+    "sequenceStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "body"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Producer-supplied, including its own numbering if any — the renderer never generates a number."
+        },
+        "body": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "`null` while the active step's content is still resolving."
+        },
+        "error": {
+          "type": "boolean"
+        }
+      }
+    },
+    "sequencePayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "steps"
+      ],
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/sequenceStep"
+          }
+        },
+        "activeIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Widget-local starting position, not a result."
+        }
+      }
+    },
+    "artifactRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label",
+        "value"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {
+          "type": "string"
+        }
+      }
+    },
+    "artifactPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rows"
+      ],
+      "properties": {
+        "rows": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/$defs/artifactRow"
+          },
+          "description": "`null` = unavailable, distinct from `[]` (a genuinely empty but resolved document)."
+        }
+      }
+    },
+    "textPoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "body"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string"
+        },
+        "body": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "textPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "points"
+      ],
+      "properties": {
+        "points": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/textPoint"
+          }
+        },
+        "treatment": {
+          "enum": [
+            "insight",
+            "plain",
+            "quote"
+          ],
+          "description": "Only consulted when `points.length === 1` and no point carries its own `title` — see docs/output-type-sheets/text.md's routing rule."
+        },
+        "attribution": {
+          "type": "string",
+          "description": "`treatment: \"quote\"` only."
+        }
+      }
+    },
+    "statusChip": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "primary": {
+          "type": "boolean"
+        }
+      }
+    },
+    "statusPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "outcome",
+        "action",
+        "density"
+      ],
+      "properties": {
+        "outcome": {
+          "enum": [
+            "success",
+            "neutral",
+            "needs-attention",
+            "failure"
+          ]
+        },
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "density": {
+          "enum": [
+            "bare",
+            "receipt",
+            "actions"
+          ]
+        },
+        "meta": {
+          "type": "string"
+        },
+        "chips": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/statusChip"
+          }
+        }
+      }
+    },
+    "rankedItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rank": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Explicit rank; falls back to payload order (1-indexed) when absent."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "note": {
+          "type": "string"
+        },
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Never colour-coded by the renderer — a score the producer may have made up."
+        }
+      }
+    },
+    "rankedPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/rankedItem"
+          }
+        },
+        "loadingCount": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "deckAttribute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "label"
+      ],
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "notable": {
+          "type": "boolean"
+        }
+      }
+    },
+    "deckItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "note": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/deckAttribute"
+          }
+        }
+      }
+    },
+    "deckPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items",
+        "density"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/deckItem"
+          }
+        },
+        "density": {
+          "enum": [
+            "compact",
+            "default",
+            "expanded"
+          ]
+        },
+        "decided": {
+          "type": "object",
+          "additionalProperties": {
+            "enum": [
+              "kept",
+              "passed"
+            ]
+          },
+          "description": "Write-mode decisions so far, keyed by item id — echoed back the same way comparison.selected round-trips."
+        }
+      }
+    },
+    "diffField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label",
+        "before",
+        "after"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "before": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "after": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "rule": {
+          "type": "string",
+          "description": "The rule that produced the change — enables the \"with the rule applied\" (C) anatomy."
+        }
+      }
+    },
+    "diffPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/diffField"
+          }
+        },
+        "before": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Variation A only — used when `fields` is absent."
+        },
+        "after": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "severity",
+        "text"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "severity": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ]
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "locator": {
+          "type": "string",
+          "description": "e.g. \"p2, line 18\"."
+        }
+      }
+    },
+    "findingsPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "findings"
+      ],
+      "properties": {
+        "findings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/finding"
+          }
+        }
+      }
+    },
+    "listColumn": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "searchable": {
+          "type": "boolean"
+        },
+        "detail": {
+          "type": "boolean",
+          "description": "Shown in the select → detail `keyvalue`. Default true."
+        },
+        "filterable": {
+          "type": "boolean",
+          "description": "The filterable columns ARE the filter vocabulary (N1): user-configured and agent-added filters may only name these."
+        }
+      }
+    },
+    "listPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "resource",
+        "noun",
+        "titleColumn",
+        "columns",
+        "copy"
+      ],
+      "description": "CONFIG authored once and frozen for the instance's life. Anything that changes on interaction is runtime state and never appears here. Filters are schema-driven (N1): they name `filterable` columns of `columns`, and an agent may add filters only from those same columns.",
+      "properties": {
+        "resource": {
+          "type": "string",
+          "minLength": 1
+        },
+        "noun": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Plural, for counters and empty states — \"suppliers\"."
+        },
+        "titleColumn": {
+          "type": "string",
+          "minLength": 1
+        },
+        "descriptionColumn": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metaColumn": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One trailing value only."
+        },
+        "columns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/listColumn"
+          }
+        },
+        "filters": {
+          "type": "array",
+          "description": "User/builder-exposed filters. Each names a `filterable` column (validated by validateListConfig). `chips` draws a value per option; `letters` is the A–Z facet — one rendering of a column-derived filter (N5).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "column"
+            ],
+            "properties": {
+              "column": {
+                "type": "string",
+                "minLength": 1
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1
+              },
+              "control": {
+                "enum": [
+                  "chips",
+                  "letters"
+                ]
+              },
+              "options": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "value",
+                    "label"
+                  ],
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            },
+            "if": {
+              "not": {
+                "properties": {
+                  "control": {
+                    "const": "letters"
+                  }
+                },
+                "required": [
+                  "control"
+                ]
+              }
+            },
+            "then": {
+              "required": [
+                "options"
+              ]
+            }
+          }
+        },
+        "search": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "placeholder": {
+              "type": "string"
+            }
+          }
+        },
+        "sort": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "options"
+          ],
+          "properties": {
+            "options": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "column",
+                  "dir",
+                  "label"
+                ],
+                "properties": {
+                  "column": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "dir": {
+                    "enum": [
+                      "asc",
+                      "desc"
+                    ]
+                  },
+                  "label": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          }
+        },
+        "pageSize": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "selection": {
+          "enum": [
+            "none",
+            "single"
+          ],
+          "description": "`none` → rows are inert and not focusable (B3 off)."
+        },
+        "copy": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "emptyLabel",
+            "consequenceLine"
+          ],
+          "properties": {
+            "emptyLabel": {
+              "type": "string",
+              "minLength": 1
+            },
+            "consequenceLine": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "description": "Not optional — no renderer can generate a consequence line from a schema."
+        },
+        "mock": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "records"
+          ],
+          "description": "Fixture/Storybook/Playground only — a deterministic in-memory source so a document with no host adapter still runs the real query engine. Never a backend.",
+          "properties": {
+            "records": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "id",
+                  "data"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "data": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            },
+            "scenario": {
+              "enum": [
+                "default",
+                "empty",
+                "error",
+                "partial",
+                "noSort",
+                "noSearch",
+                "noFilter",
+                "noTotal",
+                "failAfterFirst"
+              ]
+            },
+            "latencyMs": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "initial": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Seeds the runtime `query`; user interaction mutates it afterward.",
+          "properties": {
+            "filters": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "column",
+                  "value"
+                ],
+                "properties": {
+                  "column": {
+                    "type": "string"
+                  },
+                  "value": {
+                    "type": "string"
+                  },
+                  "op": {
+                    "enum": [
+                      "eq",
+                      "startsWith"
+                    ]
+                  },
+                  "author": {
+                    "enum": [
+                      "user",
+                      "agent"
+                    ],
+                    "description": "Who authored the seed. The same primitive either way (N1)."
+                  }
+                }
+              }
+            },
+            "search": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}