git.stella-ops.org/docs/contracts/api-governance-baseline.md

CONTRACT-API-GOVERNANCE-BASELINE-012: Aggregate OpenAPI Spec & SDK Generation

Status: Published Version: 1.0.0 Published: 2025-12-05 Owners: API Governance Guild, SDK Generator Guild Unblocks: SDKGEN-63-001, SDKGEN-63-002, SDKGEN-63-003, SDKGEN-63-004, SDKGEN-64-001, SDKGEN-64-002

Overview

This contract defines the aggregate OpenAPI specification freeze process, versioning rules, and SHA256 commitment mechanism that enables deterministic SDK generation across TypeScript, Python, Go, and Java targets.

Aggregate Specification

Source Location

src/Api/StellaOps.Api.OpenApi/stella.yaml

Composition Process

The aggregate spec is generated by compose.mjs from per-service specs:

Service	Source Spec	Tag Prefix
Authority	authority/openapi.yaml	authority.*
Export Center	export-center/openapi.yaml	export.*
Graph	graph/openapi.yaml	graph.*
Orchestrator	orchestrator/openapi.yaml	orchestrator.*
Policy	policy/openapi.yaml	policy.*
Scheduler	scheduler/openapi.yaml	scheduler.*

Current Version

openapi: 3.1.0
info:
  title: StellaOps Aggregate API
  version: 0.0.1

---

Freeze Process

1. Version Tagging

When freezing for SDK generation:

# Compute SHA256 of aggregate spec
sha256sum src/Api/StellaOps.Api.OpenApi/stella.yaml > stella.yaml.sha256

# Tag the commit
git tag -a api/v0.1.0-alpha -m "API freeze for SDK Wave B generation"

2. SHA256 Commitment

SDK generators must validate the spec hash before generation:

# Environment variable for hash guard
export STELLA_OAS_EXPECTED_SHA256="<sha256-hash>"

# Generator validates before running
if [ "$(sha256sum stella.yaml | cut -d' ' -f1)" != "$STELLA_OAS_EXPECTED_SHA256" ]; then
  echo "ERROR: Spec hash mismatch - regenerate after spec freeze"
  exit 1
fi

3. Published Artifacts

On freeze, publish:

Artifact	Location	Purpose
Tagged spec	api/v{version} git tag	Version reference
SHA256 file	stella.yaml.sha256	Hash verification
Changelog	CHANGELOG-api.md	Breaking changes

---

SDK Generation Contract

Generator Configuration

Language	Config	Output
TypeScript	ts/config.yaml	ESM/CJS with typed errors
Python	python/config.yaml	sync/async clients, type hints
Go	go/config.yaml	context-first API
Java	java/config.yaml	builder pattern, OkHttp

Toolchain Lock

# toolchain.lock.yaml
openapi-generator-cli: 7.4.0
jdk: 21.0.1
node: 22.x
python: 3.11+
go: 1.21+

Hash Guard Implementation

Each generator emits .oas.sha256 for provenance:

# Example: TypeScript generation
echo "$STELLA_OAS_EXPECTED_SHA256  stella.yaml" > dist/.oas.sha256

---

Versioning Rules

Semantic Versioning

MAJOR.MINOR.PATCH[-PRERELEASE]

- MAJOR: Breaking API changes
- MINOR: New endpoints/fields (backwards compatible)
- PATCH: Bug fixes, documentation
- PRERELEASE: alpha, beta, rc

Breaking Change Detection

# Run API compatibility check
npm run api:compat -- --old scripts/__fixtures__/api-compat/old.yaml \
                      --new src/Api/StellaOps.Api.OpenApi/stella.yaml

Version Matrix

API Version	SDK Versions	Status
0.0.1	-	Current (unfrozen)
0.1.0-alpha	TS/Py/Go/Java alpha	Target freeze

---

Freeze Checklist

Before SDK generation can proceed:

• All per-service specs pass npm run api:lint
• Aggregate composition succeeds (node compose.mjs)
• Breaking change review completed
• SHA256 computed and committed
• Git tag created (api/v{version})
• Changelog entry added
• SDK generator configs updated with hash

---

Current Freeze Status

Pending Actions

Action	Owner	Due	Status
Compute SHA256 for stella.yaml	API Governance Guild	2025-12-06	TODO
Create api/v0.1.0-alpha tag	API Governance Guild	2025-12-06	TODO
Update SDKGEN configs with hash	SDK Generator Guild	2025-12-06	TODO

Immediate Unblock Path

To immediately unblock SDK generation:

# 1. Compute current spec hash
cd src/Api/StellaOps.Api.OpenApi
SHA=$(sha256sum stella.yaml | cut -d' ' -f1)
echo "Current SHA256: $SHA"

# 2. Create hash file
echo "$SHA  stella.yaml" > stella.yaml.sha256

# 3. Tag for SDK generation
git add stella.yaml.sha256
git commit -m "chore(api): freeze aggregate spec for SDK Wave B"
git tag -a api/v0.1.0-alpha -m "API freeze for SDK generation"

# 4. Set environment for generators
export STELLA_OAS_EXPECTED_SHA256="$SHA"

---

SDK Generation Commands

Once freeze is complete:

# TypeScript
cd src/Sdk/StellaOps.Sdk.Generator/ts
./generate-ts.sh

# Python
cd ../python
./generate-python.sh

# Go
cd ../go
./generate-go.sh

# Java
cd ../java
./generate-java.sh

# Run all smoke tests
npm run sdk:smoke

---

Governance

Change Process

1. Propose: Open PR with spec changes
2. Review: API Governance Guild reviews for breaking changes
3. Test: Run api:lint and api:compat
4. Merge: Merge to main
5. Freeze: Tag and compute SHA256 when ready for SDK

Stakeholders

• API Governance Guild: Spec ownership, breaking change review
• SDK Generator Guild: Generation toolchain, language packs
• Platform Security: Signing key provisioning (SDKREL-63-001)

---

Signing Keys

Development Key (Available Now)

A development signing key is available for staging/testing:

File	Purpose
tools/cosign/cosign.dev.key	Private key (password: stellaops-dev)
tools/cosign/cosign.dev.pub	Public key for verification

Usage for SDK staging:

# Set environment for SDK signing
export COSIGN_KEY_FILE=tools/cosign/cosign.dev.key
export COSIGN_PASSWORD=stellaops-dev
export COSIGN_ALLOW_DEV_KEY=1

# Or use CI workflow with allow_dev_key=1

Production Keys (Pending)

Production signing requires:

• Sovereign crypto key provisioning (Action #7)
• COSIGN_PRIVATE_KEY_B64 CI secret
• Optional COSIGN_PASSWORD for encrypted keys

Key Resolution Order

1. COSIGN_KEY_FILE environment variable
2. COSIGN_PRIVATE_KEY_B64 (decoded to temp file)
3. tools/cosign/cosign.key (production drop-in)
4. tools/cosign/cosign.dev.key (only if COSIGN_ALLOW_DEV_KEY=1)

---

Reference

• Aggregate spec: src/Api/StellaOps.Api.OpenApi/stella.yaml
• Composition script: src/Api/StellaOps.Api.OpenApi/compose.mjs
• Toolchain lock: src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md
• SDK generators: src/Sdk/StellaOps.Sdk.Generator/{ts,python,go,java}/

---

Changelog

Version	Date	Author	Changes
1.0.0	2025-12-05	API Governance Guild	Initial contract