API (OpenAPI Contracts)

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section.

Service wiring (image, database and role, compose profile, bundle presence) is generated in the service inventory; this dossier does not restate it.

Source: src/Api/StellaOps.Api.OpenApi/ Deployable: none. src/Api ships no C# and no service; it is an API-contract repository.

Purpose

src/Api/StellaOps.Api.OpenApi/ holds hand-maintained OpenAPI 3.1 specifications for a subset of Stella Ops services, the shared schema/parameter/response/security components, the aggregate composer compose.mjs, and the composed aggregate stella.yaml.

These files are not the runtime API documents. Each live service publishes its own generated document (usually /openapi/v1.json), and the gateway aggregates those at runtime (see Router OpenAPI aggregation). The specs here are consumed by the OpenAPI conformance tests, the Authority test host, and the Developer Portal spec sync.

Components

Per-service specs — StellaOps.Api.OpenApi/<service>/openapi.yaml

The composer (compose.mjs) treats a spec as a draft stub when its title contains (stub) or its description contains scaffold (isDraftStubSpec). It then marks the aggregate with x-stellaops-contract-status: contains-draft-stubs and lists those services in x-stellaops-draft-services, so consumers can identify the incomplete contracts. With no draft stub present it emits x-stellaops-contract-status: implemented. The committed aggregate lists export-center, graph, jobengine, policy and scheduler as draft services.

The canonical /api/policy/exceptions API is described by the Policy runtime spec, not by the Policy stub here.

Shared components — _shared/

• _shared/schemas/ — common.yaml, deprecation.yaml
• _shared/parameters/ — paging.yaml, tenant.yaml
• _shared/responses/ — defaults.yaml
• _shared/securitySchemes/ — default.yaml (OAuthClientCredentials OAuth 2.1 client credentials, BearerAuth HTTP bearer/JWT)

Aggregate and baseline

• stella.yaml — composed aggregate generated by compose.mjs from every <service>/openapi.yaml. Paths are namespaced as /<service>/<original-path> and each operation carries x-service and x-original-path; owner-local schemas, parameters and responses are namespaced <service>.<ComponentName>. Shared component references are rebased into #/components/.
• baselines/stella-baseline.yaml — baseline aggregate snapshot for compatibility-diff tooling.
• CHANGELOG.md — generated API changelog (last generated 2025-11-24).
• tasks.md — task tracker (OAS-61/62/63, OAS-TRUTH-001).

Aggregate currency (PCD-258, 2026-10-03 UTC): the aggregate is recomposed from the current eight curated owner inputs. It includes their 92 namespaced paths and 101 operations, including the Vulnerabilities binaries/* and symbols/* operations. The three retired attestor.* Authority scopes are absent. compose.mjs --check compares the committed artifact with a fresh in-memory composition without writing it; --self-test proves stale-scope rejection, owner-input drift and preservation of the draft markers. The existing architecture workflow runs both commands with its locked Node/YAML dependencies. This checks curated-source currency; it does not assert that the static paths are served by the live gateway.

Composition also rejects unresolved local references. The PCD-258 reference audit found six unresolved targets in the previous output: omitted Scanner parameters/responses and shared schema references still rooted at #/schemas/. The composer now includes owner parameters and responses, rewrites their references consistently, and rebases shared references. All 166 local reference targets resolve in the recomposed artifact; the self-test includes a missing-component negative control.

Verified against source commit 9c7d205d69596eaabf7b86f8966b413dbeb2b96b; the composition receipt records input hashes, scope/path deltas, commands and validation limits.

The DevPortal’s tracked public/api/stella.yaml copy is refreshed with its existing scripts/sync-spec.mjs and must match the aggregate bytes. The historical baselines/stella-baseline.yaml remains a dated comparison input; regeneration does not rewrite it.

Authority spec: one copy

src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml is the only Authority contract. The Authority service build (StellaOps.Authority.csproj) copies it to OpenApi/authority.yaml, which AuthorityOpenApiDocumentProvider serves at /.well-known/openapi. The OpenAPI conformance pack (AuthorityConformanceFixture), the Authority test host (AuthorityWebApplicationFactory) and the aggregate composer read the same file. AuthorityOpenApiSingleSourceTests in the conformance pack fails if the service build points anywhere else or a second Authority openapi.yaml appears under src/.

Until 2026-09-27 a second copy under src/Authority/StellaOps.Api.OpenApi/ was the one the service served, while the tests read this one. The served copy lacked the /console/admin/identity-providers* paths and several catalog scopes. The copies were merged into this file and the other was deleted. The merge removed three attestor.* scope names that StellaOpsScopes does not define, and added findings:write, packs.* and trust:* from the catalog.

Governance tooling

• Lint ruleset: repo-root .spectral.yaml (Spectral CLI).
• Composer: src/Api/StellaOps.Api.OpenApi/compose.mjs.
• npm scripts in the repo-root package.json: api:lint and api:compose are the only API governance commands.

The governance process is documented in the API governance baseline. Example-coverage checks, compatibility diff and changelog generation are specified in api-contracts.md but have no implementation in the repository.

Usage

# Compose aggregate spec (preserves draft-stub markers)
npm run api:compose
# or directly:
node src/Api/StellaOps.Api.OpenApi/compose.mjs
# Verify currency without rewriting, and prove the detector
node src/Api/StellaOps.Api.OpenApi/compose.mjs --self-test
node src/Api/StellaOps.Api.OpenApi/compose.mjs --check
# Refresh the DevPortal's bundled copy
node src/Tools/StellaOps.DevPortal.Site/scripts/sync-spec.mjs

# Lint OpenAPI specs (Spectral, ruleset at repo-root .spectral.yaml)
npm run api:lint

Related Documentation

• Developer Portal (consumes stella.yaml via src/Tools/StellaOps.DevPortal.Site/scripts/sync-spec.mjs): ../tools/
• Gateway / Router runtime OpenAPI aggregation: ../router/openapi-aggregation.md
• Platform: ../platform/architecture-overview.md
• API contracts contributing guide: docs/dev/contributing/api-contracts.md
• Prose endpoint migration triage (OAPI-059-006 pilot record): migration-triage.md

Evidence