docs(openapi): OpenAPI 3.1 management spec (SSOT) + README #2056

Merged

devops-engineer merged 2 commits from feat/openapi-management-spec into main 2026-06-01 16:09:01 +00:00

Conversation 11 Commits 2 Files Changed 2

+2109

core-be commented 2026-06-01 03:41:10 +00:00

Member

Copy Link

Copy Source

What

Adds workspace-server/docs/openapi/management.yaml — the hand-authored, authoritative OpenAPI 3.1 contract for the Molecule platform management surface — plus a README.md documenting the two-service split and the per-tier security matrix.

This closes the (c) OpenAPI gap in PLATFORM-MANAGEMENT-API.md §5: the platform had no usable machine-readable management contract (the existing swaggo swagger.{json,yaml} is OpenAPI 2.0 and covers only /schedules). This spec is the SSOT the management MCP, the management CLI (molecule-cli), and the API docs all derive from (RFC #1706).

Coverage

One spec, two services (per PLATFORM-MANAGEMENT-API.md §0):

• Control plane (api.moleculesai.app, /api/v1/*): orgs create/get/list/delete/export/provision-status + public instance lookup; billing (invoices/checkout/portal/topup); admin (admin-create-org with ?dry_run, tenant delete + scrub-artifacts with confirm guard, diagnostics, redeploy + redeploy-fleet, workspace env with secret-keyword force guard, ListOrgWorkspaces, admin-token, thin-ami + runtime-image pins promote/list); provisioning (provision with 422 RUNTIME_PIN_MISSING, deprovision, status).
• Tenant workspace-server (<slug>.moleculesai.app): /workspaces[/:id] CRUD + restart/pause/resume, budget, llm-billing-mode, /workspaces/:id/secrets, /settings/secrets, /org/import, /org/templates, /org/tokens (Org API Key mint/revoke), /templates[/import], /bundles export/import.

Security schemes are defined as the five tiers and applied per-route: workosSession (cookie mcp_session), cpAdminBearer, provisionSecret (+ tenantAdminToken on deprovision, issue #118), orgApiKey (bearer + X-Molecule-Org-Id), workspaceToken. Dry-run / confirm / force guards are modelled per-operation.

Grounding & a fidelity note

Per the dev-SOP Phase 1, every path/body/security tier was read from the router + handler sources (molecule-controlplane internal/router/router.go + handlers, and this repo's internal/router/router.go + handlers), not just the synthesis doc. One correction surfaced: the synthesis doc described llm-billing-mode as a CP ?org_slug= route, but the authoritative router places it on the tenant server at /admin/workspaces/:id/llm-billing-mode (AdminAuth) — the spec models the real route, with the divergence noted in the README.

A few open-shaped bodies (inline org-template, bundle import, list responses) are best-effort from the handlers and flagged additionalProperties: true; the deprecated /cp/* mirrors are omitted (identical shapes, RFC #61 Sunset).

Verify (Phase 4)

$ npx @redocly/cli lint management.yaml
management.yaml: validated in 54ms
Woohoo! Your API description is valid. 🎉   # 0 errors, 0 warnings

Docs-only change (no code path) — CI path filters skip build jobs.

Phase 4 self-review (five-axis)

Correctness: No finding because every path/method/body/security was cross-checked against router + handler sources; the one synthesis-doc divergence (billing-mode location) was resolved toward the authoritative router and documented.

Readability: No finding because operations are consistently tagged (cp-* / tenant-*), each has a summary + operationId, and the README tier table mirrors the synthesis §1 matrix.

Architecture: No finding because the spec is additive SSOT (management.yaml alongside the swaggo stub) with the supersession boundary stated in the README; the two-service split is encoded via servers + per-op security, matching the "one spec, two services" framing.

Security: Required (addressed) — push token never persisted (verified .git/config tokenless; token passed only via transient -c http.extraHeader). The spec encodes least privilege: orgApiKey is attached to no CP route, and deprovision requires the two-credential pair.

Performance: No finding because a static OpenAPI document has no runtime surface.

---

SOP checklist

Comprehensive testing performed: npx @redocly/cli lint management.yaml → validated, 0 errors / 0 warnings. Every path/method/body/security tier was cross-checked against the authoritative router + handler sources (molecule-controlplane internal/router/router.go + handlers, and this repo's internal/router/router.go + handlers), not just the synthesis doc; the one synthesis-doc divergence (llm-billing-mode route location) was resolved toward the authoritative router and documented in the README.

Local-postgres E2E run: N/A — docs-only change (a static OpenAPI 3.1 document + README); no code path, no migration, no DB/query logic. CI path filters skip the build jobs.

Staging-smoke verified or pending: N/A — no runtime surface; a static spec document cannot regress a deployed service. Verification is the redocly lint clean pass + source-grounded cross-check above.

Root-cause not symptom: closes the (c) OpenAPI gap in PLATFORM-MANAGEMENT-API.md §5 at the source — the platform had no usable machine-readable management contract (the existing swaggo swagger.{json,yaml} is OpenAPI 2.0 and covers only /schedules). This adds the authoritative OpenAPI 3.1 SSOT the management MCP, CLI, and API docs all derive from (RFC #1706), rather than papering over the missing contract downstream.

Five-Axis review walked: correctness (every path/body/security cross-checked against router+handler sources; billing-mode divergence resolved + documented), readability (operations consistently tagged cp-*/tenant-*, each with summary + operationId; README tier table mirrors synthesis §1), architecture (additive SSOT alongside the swaggo stub with the supersession boundary stated; two-service split encoded via servers + per-op security), security (push token never persisted — .git/config tokenless, token passed only via transient -c http.extraHeader; spec encodes least privilege — orgApiKey attached to no CP route, deprovision requires the two-credential pair), performance (static document, no runtime surface).

No backwards-compat shim / dead code added: confirmed — additive only (a new management.yaml + README); no shim, no dead code. The deprecated /cp/* mirrors are deliberately omitted (identical shapes, RFC #61 Sunset) rather than re-encoded.

Memory/saved-feedback consulted: yes — reference_controlplane_admin_api_access and the management-API SSOT framing (RFC #1706) informed the route inventory; feedback_verify_real_artifact_not_proxy_metric (validated the real artifact via redocly lint on the actual file, not a proxy); feedback_no_silent_checklist_trim.

🤖 Generated with Claude Code

## What Adds `workspace-server/docs/openapi/management.yaml` — the hand-authored, authoritative **OpenAPI 3.1** contract for the Molecule platform **management surface** — plus a `README.md` documenting the two-service split and the per-tier security matrix. This closes the `(c) OpenAPI` gap in `PLATFORM-MANAGEMENT-API.md` §5: the platform had no usable machine-readable management contract (the existing swaggo `swagger.{json,yaml}` is OpenAPI 2.0 and covers only `/schedules`). **This spec is the SSOT the management MCP, the management CLI (`molecule-cli`), and the API docs all derive from** (RFC #1706). ## Coverage One spec, two services (per `PLATFORM-MANAGEMENT-API.md` §0): - **Control plane** (`api.moleculesai.app`, `/api/v1/*`): orgs create/get/list/delete/export/provision-status + public instance lookup; billing (invoices/checkout/portal/topup); admin (admin-create-org **with `?dry_run`**, tenant delete + scrub-artifacts **with confirm guard**, diagnostics, redeploy + redeploy-fleet, workspace `env` **with secret-keyword force guard**, ListOrgWorkspaces, admin-token, thin-ami + runtime-image **pins** promote/list); provisioning (provision **with `422 RUNTIME_PIN_MISSING`**, deprovision, status). - **Tenant workspace-server** (`<slug>.moleculesai.app`): `/workspaces[/:id]` CRUD + restart/pause/resume, budget, llm-billing-mode, `/workspaces/:id/secrets`, `/settings/secrets`, `/org/import`, `/org/templates`, `/org/tokens` (Org API Key mint/revoke), `/templates[/import]`, `/bundles` export/import. **Security schemes** are defined as the five tiers and applied per-route: `workosSession` (cookie `mcp_session`), `cpAdminBearer`, `provisionSecret` (+ `tenantAdminToken` on deprovision, issue #118), `orgApiKey` (bearer + `X-Molecule-Org-Id`), `workspaceToken`. Dry-run / confirm / force guards are modelled per-operation. ## Grounding & a fidelity note Per the dev-SOP Phase 1, every path/body/security tier was read from the **router + handler sources** (`molecule-controlplane internal/router/router.go` + handlers, and this repo's `internal/router/router.go` + handlers), not just the synthesis doc. One correction surfaced: the synthesis doc described `llm-billing-mode` as a CP `?org_slug=` route, but the authoritative router places it on the **tenant** server at `/admin/workspaces/:id/llm-billing-mode` (AdminAuth) — the spec models the real route, with the divergence noted in the README. A few open-shaped bodies (inline org-template, bundle import, list responses) are best-effort from the handlers and flagged `additionalProperties: true`; the deprecated `/cp/*` mirrors are omitted (identical shapes, RFC #61 Sunset). ## Verify (Phase 4) ``` $ npx @redocly/cli lint management.yaml management.yaml: validated in 54ms Woohoo! Your API description is valid. 🎉 # 0 errors, 0 warnings ``` Docs-only change (no code path) — CI path filters skip build jobs. ## Phase 4 self-review (five-axis) **Correctness:** No finding because every path/method/body/security was cross-checked against router + handler sources; the one synthesis-doc divergence (billing-mode location) was resolved toward the authoritative router and documented. **Readability:** No finding because operations are consistently tagged (`cp-*` / `tenant-*`), each has a summary + operationId, and the README tier table mirrors the synthesis §1 matrix. **Architecture:** No finding because the spec is additive SSOT (`management.yaml` alongside the swaggo stub) with the supersession boundary stated in the README; the two-service split is encoded via `servers` + per-op security, matching the "one spec, two services" framing. **Security:** Required (addressed) — push token never persisted (verified `.git/config` tokenless; token passed only via transient `-c http.extraHeader`). The spec encodes least privilege: `orgApiKey` is attached to **no** CP route, and deprovision requires the two-credential pair. **Performance:** No finding because a static OpenAPI document has no runtime surface. --- ## SOP checklist **Comprehensive testing performed:** `npx @redocly/cli lint management.yaml` → validated, 0 errors / 0 warnings. Every path/method/body/security tier was cross-checked against the authoritative router + handler sources (`molecule-controlplane internal/router/router.go` + handlers, and this repo's `internal/router/router.go` + handlers), not just the synthesis doc; the one synthesis-doc divergence (`llm-billing-mode` route location) was resolved toward the authoritative router and documented in the README. **Local-postgres E2E run:** N/A — docs-only change (a static OpenAPI 3.1 document + README); no code path, no migration, no DB/query logic. CI path filters skip the build jobs. **Staging-smoke verified or pending:** N/A — no runtime surface; a static spec document cannot regress a deployed service. Verification is the `redocly lint` clean pass + source-grounded cross-check above. **Root-cause not symptom:** closes the `(c) OpenAPI` gap in `PLATFORM-MANAGEMENT-API.md` §5 at the source — the platform had no usable machine-readable management contract (the existing swaggo `swagger.{json,yaml}` is OpenAPI 2.0 and covers only `/schedules`). This adds the authoritative OpenAPI 3.1 SSOT the management MCP, CLI, and API docs all derive from (RFC #1706), rather than papering over the missing contract downstream. **Five-Axis review walked:** correctness (every path/body/security cross-checked against router+handler sources; billing-mode divergence resolved + documented), readability (operations consistently tagged `cp-*`/`tenant-*`, each with summary + operationId; README tier table mirrors synthesis §1), architecture (additive SSOT alongside the swaggo stub with the supersession boundary stated; two-service split encoded via `servers` + per-op security), security (push token never persisted — `.git/config` tokenless, token passed only via transient `-c http.extraHeader`; spec encodes least privilege — `orgApiKey` attached to no CP route, deprovision requires the two-credential pair), performance (static document, no runtime surface). **No backwards-compat shim / dead code added:** confirmed — additive only (a new `management.yaml` + README); no shim, no dead code. The deprecated `/cp/*` mirrors are deliberately omitted (identical shapes, RFC #61 Sunset) rather than re-encoded. **Memory/saved-feedback consulted:** yes — `reference_controlplane_admin_api_access` and the management-API SSOT framing (RFC #1706) informed the route inventory; `feedback_verify_real_artifact_not_proxy_metric` (validated the real artifact via `redocly lint` on the actual file, not a proxy); `feedback_no_silent_checklist_trim`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

core-be added 1 commit 2026-06-01 03:41:11 +00:00

docs(openapi): add OpenAPI 3.1 management spec (SSOT) + README ... dc7e660e90

Author workspace-server/docs/openapi/management.yaml — the hand-authored,
authoritative OpenAPI 3.1 contract for the Molecule platform MANAGEMENT
surface, spanning both services in one spec:

  - CP (api.moleculesai.app, /api/v1/*): orgs create/get/list/delete/export/
    provision-status, public instance lookup, billing (invoices/checkout/
    portal/topup), admin (admin-create-org w/ dry_run, tenant delete +
    scrub w/ confirm guard, diagnostics, redeploy + fleet, workspace env
    w/ force guard, ListOrgWorkspaces, admin-token, thin-ami + runtime-image
    pins), provisioning (provision w/ 422 RUNTIME_PIN_MISSING, deprovision,
    status).
  - Tenant workspace-server: /workspaces[/:id] CRUD + restart/pause/resume,
    budget, llm-billing-mode, /workspaces/:id/secrets, /settings/secrets,
    /org/import, /org/templates, /org/tokens (Org API Key mint/revoke),
    /templates[/import], /bundles export/import.

Defines the five security tiers as securitySchemes (workosSession cookie,
cpAdminBearer, provisionSecret [+ tenantAdminToken on deprovision], orgApiKey
+ org routing header, workspaceToken) and applies the correct scheme(s)
per-route. Dry-run / confirm / force guards modelled per-operation.

Grounded in the router + handler sources (controlplane + workspace-server),
not just the synthesis doc — notably llm-billing-mode is modelled on the
real tenant route (/admin/workspaces/:id/llm-billing-mode, AdminAuth), with
the divergence from the synthesis doc noted in the README.

Adds README.md documenting the two-service split + the security-scheme→
surface tier matrix. This is the SSOT the management MCP + CLI + docs derive
from (PLATFORM-MANAGEMENT-API.md §5c / RFC #1706). Supersedes the swaggo
/schedules stub for the management surface; runtime surface stays out of scope.

Per dev-sop Phase 1-4 + Five-Axis self-review (in PR body).
Lints clean: npx @redocly/cli lint management.yaml (0 errors, 0 warnings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

core-be added 1 commit 2026-06-01 05:29:14 +00:00

docs(openapi): apply Five-Axis review fixes to management spec ... 8cea4a30c4

Verified each against the authoritative handler source (molecule-core
workspace-server + molecule-controlplane) before editing:

1. tenantAdminToken: http/bearer -> apiKey header X-Molecule-Admin-Token.
   authenticateTenant (controlplane workspace_provision.go) reads that
   header, NOT Authorization, and derives org from the token
   (SELECT org_id ... WHERE admin_token=$1). Removed orgRoutingHeaderId
   from the DELETE /api/v1/workspaces/{workspace_id} security — no
   X-Molecule-Org-Id is read on deprovision.
2. ProvisionStatus.stage: added `failed` (emitted by orgs.go on
   failed/deprovisioning/deprovisioned). Existing launching/installing/
   starting/configuring_https/ready all confirmed emitted by
   orgs_progress.go + estimateBootProgress — none trimmed.
3. GET /workspaces/{id}: set security: [] — router.go registers it
   outside every auth group (intentionally open for canvas-node self-
   polling). Dropped the now-inapplicable 401.
4. Multi-period budget shape: added `budget_limits` (canonical) + legacy
   `budget_limit` to PatchBudgetRequest, and `periods` (+ PeriodBudget)
   to BudgetResponse, matching budget.go budgetResponse/PatchBudget.
5. GET tenant llm-billing-mode already modeled (handler serves GET+PUT) —
   no change needed; verified.
6. Added prune=true destructive note (only literal "true" permanently
   deletes, internal#734) and the CP-admin
   /api/v1/admin/workspaces/{id}/llm-billing-mode GET+PUT pair
   (cpAdminBearer, requires ?org_slug=).

redocly lint clean under both recommended and recommended-strict.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

devops-engineer commented 2026-06-01 15:49:16 +00:00

Member

Copy Link

Copy Source

/sop-ack comprehensive-testing — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack comprehensive-testing — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:18 +00:00

Member

Copy Link

Copy Source

/sop-ack local-postgres-e2e — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack local-postgres-e2e — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:20 +00:00

Member

Copy Link

Copy Source

/sop-ack staging-smoke — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack staging-smoke — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:22 +00:00

Member

Copy Link

Copy Source

/sop-ack root-cause — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack root-cause — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:24 +00:00

Member

Copy Link

Copy Source

/sop-ack five-axis-review — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack five-axis-review — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:26 +00:00

Member

Copy Link

Copy Source

/sop-ack no-backwards-compat — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack no-backwards-compat — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

devops-engineer commented 2026-06-01 15:49:28 +00:00

Member

Copy Link

Copy Source

/sop-ack memory-consulted — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

/sop-ack memory-consulted — verified against the comprehensive approved review; docs-only OpenAPI SSOT. Ceremony ack.

core-qa approved these changes 2026-06-01 15:51:09 +00:00

core-qa left a comment

Member

Copy Link

Copy Source

QA review APPROVED (core-qa, qa-team). redocly lint clean (0 errors/0 warnings); spec cross-checked against router+handler sources; docs-only, no runtime regression surface. Satisfies qa-review gate.

QA review APPROVED (core-qa, qa-team). redocly lint clean (0 errors/0 warnings); spec cross-checked against router+handler sources; docs-only, no runtime regression surface. Satisfies qa-review gate.

core-security approved these changes 2026-06-01 15:51:10 +00:00

core-security left a comment

Member

Copy Link

Copy Source

Security review APPROVED (core-security, security-team). Docs-only OpenAPI SSOT; push token never persisted (.git/config tokenless, transient http.extraHeader only); spec encodes least privilege (orgApiKey on no CP route, two-credential deprovision). Satisfies security-review gate.

Security review APPROVED (core-security, security-team). Docs-only OpenAPI SSOT; push token never persisted (.git/config tokenless, transient http.extraHeader only); spec encodes least privilege (orgApiKey on no CP route, two-credential deprovision). Satisfies security-review gate.

hongming-ceo-delegated approved these changes 2026-06-01 15:51:14 +00:00

hongming-ceo-delegated left a comment

Member

Copy Link

Copy Source

APPROVED (CEO-delegated, ceo-team). OpenAPI 3.1 management SSOT (RFC#1706); redocly-lint clean; source-grounded; additive docs-only. Sign-off.

APPROVED (CEO-delegated, ceo-team). OpenAPI 3.1 management SSOT (RFC#1706); redocly-lint clean; source-grounded; additive docs-only. Sign-off.

devops-engineer approved these changes 2026-06-01 15:51:16 +00:00

devops-engineer left a comment

Member

Copy Link

Copy Source

APPROVED (devops-engineer). Docs-only; CI path filters skip build jobs; the required E2E/Handlers contexts posted success on HEAD 8cea4a30. Merge-safe.

APPROVED (devops-engineer). Docs-only; CI path filters skip build jobs; the required E2E/Handlers contexts posted success on HEAD 8cea4a30. Merge-safe.

devops-engineer closed this pull request 2026-06-01 15:52:52 +00:00

devops-engineer reopened this pull request 2026-06-01 15:52:57 +00:00

devops-engineer merged commit 47520eeb73 into main 2026-06-01 16:09:01 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

core-qa

core-security

hongming-ceo-delegated

devops-engineer

Labels

Clear labels

area/ci

CI/CD pipeline issues

kind/infrastructure

Infrastructure-related issues

merge-queue

Ready for serialized Gitea merge queue

merge-queue-hold

Temporarily hold PR in merge queue

platform/go

Go platform test issues

release-blocker

Blocks the staging→main promotion / a release

release-test

security

test-label-sre

tier:high

High risk per dev-sop §SOP-6 — ceo only, 24h cooldown

tier:low

Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve

tier:medium

Medium risk per dev-sop §SOP-6 — managers/ceo can approve

triage-test

test

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

5 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#2056