variant-docs.json

{
  "$comment": [
    "Discriminated-union variant → hand-written doc ledger. See scripts/check-variant-docs.mts.",
    "",
    "`key` is the union's identity: '<discriminator>:<variants sorted, pipe-joined>'. It is",
    "deliberately NOT a source path — a union is reachable by several paths and the walk order",
    "decides which one you see, so a path would churn. Keying on the variant set instead means",
    "adding or removing a variant CHANGES THE KEY, which fails the ratchet and forces the author",
    "back through this file — and therefore back to the doc. That is the whole point.",
    "",
    "Each entry either binds `docs` (governed: every variant must appear in at least one of them)",
    "or declares `exempt` with a reason. Two exemption classes are in use:",
    "  generated-reference-only — the type is documented solely under content/docs/references/,",
    "      which build-docs.ts generates FROM these schemas. Generated docs cannot drift.",
    "  not-authorable — wire protocol, engine RPC, or a runtime-derived discriminator. Nobody",
    "      hand-writes the variant, so no hand-written doc owes it a mention.",
    "",
    "AUDIT NOTE (#4001 follow-up). `generated-reference-only` is the weaker of the two: it",
    "does not say the variant is un-authorable, only that nobody has written a guide for it.",
    "Every such entry was re-checked against the docs tree, which moved four of the original",
    "seven:",
    "  - widget implementation became GOVERNED. protocol/objectui/widget-contract.mdx has",
    "    documented all three variants in a `Widget Source` section the whole time; the gate",
    "    could not see them because its matcher was blind to YAML. Fixed in the matcher.",
    "    (Since RETIRED: #5055 removed `WidgetSourceSchema` under ADR-0049 — no carrier key,",
    "    nothing ever parsed it — so the union is gone and its entry went with it, in the same",
    "    PR. An entry whose union has left the source is a STALE ledger row, which is the",
    "    #5552 failure mode; `pnpm check:variant-docs` is the gate that says so.)",
    "  - tenant isolation and settings-manifest handler became NOT-AUTHORABLE. Both reasons",
    "    already said the words (`operator-set`, `consumed by Setup/Studio`); the label just",
    "    disagreed with them.",
    "  - the remaining exemptions now state the gap plainly instead of pointing at the",
    "    generated page as if it settled the question. Connector authentication is the one",
    "    worth acting on: it is tenant-authored (ADR-0097 declarative `connectors:`) and the",
    "    repo has no hand-written connector guide at all. (Since closed: #4289 wrote",
    "    content/docs/automation/connectors.mdx and both connector-auth entries are governed.)"
  ],
  "entries": [
    {
      "key": "type:action|component|dashboard|group|object|page|report|separator|url",
      "label": "app navigation item",
      "docs": [
        "content/docs/ui/apps.mdx"
      ],
      "note": "The gate's founding case: apps.mdx claimed eight types and omitted `separator` (#4165)."
    },
    {
      "key": "provider:api|object|schema|value",
      "label": "view data provider",
      "docs": [
        "content/docs/ui/views.mdx",
        "content/docs/ui/forms.mdx",
        "content/docs/data-modeling/fields.mdx"
      ]
    },
    {
      "key": "type:conditional|cross_field|format|json_schema|script|state_machine",
      "label": "validation rule",
      "docs": [
        "content/docs/data-modeling/validation-rules.mdx",
        "content/docs/data-modeling/validation.mdx"
      ]
    },
    {
      "key": "language:expression|js",
      "label": "hook body language",
      "docs": [
        "content/docs/automation/hook-bodies.mdx"
      ]
    },
    {
      "key": "kind:file|http|object",
      "label": "knowledge source kind",
      "docs": [
        "content/docs/protocol/knowledge.mdx"
      ]
    },
    {
      "key": "type:cron|interval|once",
      "label": "job schedule",
      "exempt": "generated-reference-only",
      "reason": "No hand-written guide covers the Job type; content/docs/references/system/job.mdx is generated from JobSchema. Note that automation/flows.mdx's `schedule: { type: 'cron' }` is a DIFFERENT surface — a flow start node's own config (flow.zod.ts tombstones a top-level `schedule`) — so it neither documents nor governs this union."
    },
    {
      "key": "type:api-key|basic|bearer|none|oauth2",
      "label": "connector authentication",
      "docs": [
        "content/docs/automation/connectors.mdx"
      ],
      "note": "The runtime auth shape (ConnectorAuthConfigSchema) — five variants including the enterprise-tier `oauth2`. Was exempt generated-reference-only while no hand-written connector page existed; #4289 wrote the guide and bound it, per the old exemption's own instruction."
    },
    {
      "key": "type:api-key|basic|bearer|none",
      "label": "connector auth (environment-artifact projection)",
      "docs": [
        "content/docs/automation/connectors.mdx"
      ],
      "note": "The declarative connector-instance auth shape (ADR-0097), reached via EnvironmentArtifactSchema.metadata.connectors[].auth: `credentialRef` references only, and `oauth2` deliberately absent (enterprise tier, ADR-0015) — the guide states that absence explicitly so authors don't read it as an omission."
    },
    {
      "key": "strategy:isolated_db|isolated_schema|shared_schema",
      "label": "tenant isolation strategy",
      "exempt": "not-authorable",
      "reason": "Chosen by the operator when a tenant is provisioned, not written into any tenant's metadata — so no hand-written authoring page owes it a mention. (Was labelled generated-reference-only, though its own reason already said `operator-set`; the generated page at content/docs/references/system/tenant.mdx remains the reference.)"
    },
    {
      "key": "kind:action|http|navigate",
      "label": "settings-manifest handler",
      "exempt": "not-authorable",
      "reason": "Declared by a settings manifest that Setup/Studio ships and consumes; it is not part of the metadata a tenant authors. (Was labelled generated-reference-only, though its own reason already said so.)"
    },
    {
      "key": "viewKind:form|list",
      "label": "view item kind",
      "exempt": "not-authorable",
      "reason": "Loader-derived. Authors write the `list` / `listViews` / `formViews` containers; the loader expands them and stamps `viewKind`. No author ever types it."
    },
    {
      "key": "type:ack|cursor|edit|error|event|ping|pong|presence|subscribe|unsubscribe",
      "label": "websocket message",
      "exempt": "not-authorable",
      "reason": "Wire protocol between client and gateway."
    },
    {
      "key": "status:approved|expired|pending",
      "label": "device-token response status",
      "exempt": "not-authorable",
      "reason": "API response envelope, not authored metadata."
    },
    {
      "key": "method:aggregate|count|delete|execute|find|findOne|insert|update|vectorFind",
      "label": "data-engine request",
      "exempt": "not-authorable",
      "reason": "Engine RPC contract. Two entries collapsed into this one when #4618 retired `IDataEngine.batch?`: the outer union carried a `batch` variant, and a second entry described the inner union inside `DataEngineBatchRequestSchema.requests` — this same member set minus `batch`. That inner union is gone with the schema, and the outer one narrowed to exactly this set."
    },
    {
      "key": "type:delete|insert|retain",
      "label": "collaboration op component",
      "exempt": "not-authorable",
      "reason": "CRDT operation encoding."
    },
    {
      "key": "type:g-counter|lww-register|or-set|pn-counter|text",
      "label": "CRDT merge state",
      "exempt": "not-authorable",
      "reason": "CRDT internal state encoding."
    },
    {
      "key": "type:add_field|create_object|delete_object|execute_sql|modify_field|remove_field|rename_object",
      "label": "migration changeset operation",
      "exempt": "not-authorable",
      "reason": "Emitted by the diff engine, not hand-written."
    },
    {
      "key": "kind:continue|next-record|redirect|thank-you",
      "label": "form submit behavior",
      "docs": [
        "content/docs/ui/forms.mdx"
      ],
      "note": "Newly VISIBLE to this gate at #4001 批 18, not newly authorable: the four variants were always authored on `FormView.submitBehavior`, but the shape was a plain `z.union`, which this walk cannot recognise as discriminated. Batch 18 made it `z.discriminatedUnion('kind')` so a bad key inside one arm reports `unrecognized_keys` at the key's own path instead of an `invalid_union` whose prescription the renderers flatten away (#5014) — and that turned an already-authorable vocabulary into a governed one. GOVERNED rather than exempt: ui/forms.mdx names all four (line 20 lists them together, and the `thank-you` and `redirect` shapes have worked examples)."
    }
  ]
}