openapi: split api/openapi.yaml into multiple files (~3,800 lines, 60 paths)

[LKSNDRTMLKV]

Summary

api/openapi.yaml is a single hand-authored file, currently ~3,800 lines / 60 paths / 18 tags. It already took real care to navigate during the recent doc-completeness pass (#91) — every new route or tag change was a diff against the same monolith. This only gets worse: each new lifecycle action, sector, or service surface adds more lines to one file, in exactly the place several PRs are already touching concurrently.

Proposed approach

Author multi-file, ship single-file — the pattern Redocly CLI (already the tool behind #86's lint recipe and #89's nullable fixes) is built around:

• redocly split api/openapi.yaml turns the current file into a tree of paths/*.yaml + components/schemas/*.yaml, wired together with $ref, with a thin root openapi.yaml holding just info/servers/tags/security schemes.
• redocly bundle reverses it at build time, producing one canonical file again — the same shape every consumer (Scalar in dpp-web, redocly lint, any future SDK codegen) still needs.

Proposed layout

Split along the boundary that already exists — the four service crates — then by tag within each:

api/
  openapi.yaml
  paths/
    vault/
      dpp-management.yaml
      dpp-lifecycle.yaml
      scan-telemetry.yaml
      evidence-dossiers.yaml
      facilities.yaml
      operator-identifiers.yaml
      api-keys.yaml
      webhooks.yaml
      operator.yaml
      plugins.yaml
      node.yaml
      public.yaml
      credential.yaml
      internal.yaml
    identity/{public,internal}.yaml
    integrator/*.yaml
    resolver/*.yaml
  components/
    schemas/{passport,evidence,transfer,eol,registry-identity,scan-telemetry}.yaml
    responses/errors.yaml

Why bundle rather than let a consumer resolve multi-file directly

Scalar (dpp-web's renderer) has an emerging in-browser $ref-resolution engine, but it's new and plugin-based. Bundling explicitly at build time is the boring, tool-agnostic choice, and produces the one file every other consumer already expects.

Where this plugs into existing work

• chore: add an openapi lint recipe with a baseline #86 already wires redocly lint into a just openapi-check recipe — bundle is the same toolchain, one more recipe alongside it.
• dpp-web currently vendors a manually-synced public/openapi.yaml for its Scalar reference. Once this lands, that pipeline should point at the bundled output of a pinned release tag rather than a hand-copied single file — separate follow-up, not this issue.

Sequencing note

Deliberately filed rather than started: this is a repo-structure change that should land after the current wave of spec-touching work (#86, #89, #92, #91) settles, not underneath it — splitting now would conflict with all four.

Not in scope here

• The lint recipe and nullable-syntax fixes (chore: add an openapi lint recipe with a baseline #86, openapi: 37 uses of 3.0 nullable in a 3.1 spec #87, fix(api): use 3.1 type unions instead of 3.0 nullable #89) — separate, already in flight.
• Any change to dpp-web's sync mechanism — separate follow-up once this lands.