# Sprint 0208 · Experience & SDKs

## Topic & Scope
- Build a reproducible SDK generator toolchain and shared post-processing layer that stays air-gap safe.
- Ship alpha SDKs (TypeScript, Python, Go, Java) aligned to portal APIs with consistent auth/telemetry helpers.
- Connect SDK outputs to CLI and Console data providers; package offline delivery bundles with provenance.
- Evidence: updated generator pipelines, release configs, and signed artifacts across npm/PyPI/Maven/Go proxies.
- **Working directory:** `docs/implplan` (planning) with execution in `src/Sdk/StellaOps.Sdk.*`.

## Dependencies & Concurrency
- Upstream sprints: Sprint 120.A (AirGap), 130.A (Scanner), 150.A (Orchestrator), 170.A (Notifier) for API and events readiness.
- Peer/consuming sprints: SPRINT_0201_0001_0001_cli_i (CLI), SPRINT_0206_0001_0001_devportal (devportal/offline bundles), SPRINT_0209_0001_0001_ui_i (Console/UI data providers).
- Concurrency: language tracks can parallelize after SDKGEN-62-002; release tasks follow generator readiness; consumer sprints can prototype against staging SDKs once B wave exits.

## Documentation Prerequisites
- docs/README.md; docs/07_HIGH_LEVEL_ARCHITECTURE.md; docs/modules/platform/architecture-overview.md.
- docs/modules/cli/architecture.md; docs/modules/ui/architecture.md.
- API/OAS governance specs referenced by APIG0101 and portal contracts (DEVL0101) once published.


## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SDKGEN-62-001 | DONE (2025-11-24) | Toolchain, template layout, and reproducibility spec pinned. | SDK Generator Guild · `src/Sdk/StellaOps.Sdk.Generator` | Choose/pin generator toolchain, set up language template pipeline, and enforce reproducible builds. |
| 2 | SDKGEN-62-002 | DONE (2025-11-24) | Shared post-processing merged; helpers wired. | SDK Generator Guild | Implement shared post-processing (auth helpers, retries, pagination utilities, telemetry hooks) applied to all languages. |
| 3 | SDKGEN-63-001 | DONE (2025-12-10) | Frozen aggregate OAS at `../contracts/api-aggregate-2025-12-10.yaml` (+ SHA) consumed; TS alpha published with hash guard output. | SDK Generator Guild | Ship TypeScript SDK alpha with ESM/CJS builds, typed errors, paginator, streaming helpers. |
| 4 | SDKGEN-63-002 | DONE (2025-12-10) | Aggregate OAS frozen; Python alpha (sync/async) published with `.oas.sha256`. | SDK Generator Guild | Ship Python SDK alpha (sync/async clients, type hints, upload/download helpers). |
| 5 | SDKGEN-63-003 | DONE (2025-12-10) | Aggregate OAS frozen; Go alpha published with context-first API and helper copy. | SDK Generator Guild | Ship Go SDK alpha with context-first API and streaming helpers. |
| 6 | SDKGEN-63-004 | DONE (2025-12-10) | Aggregate OAS frozen; Java alpha published with builder/http abstraction, helper copy. | SDK Generator Guild | Ship Java SDK alpha (builder pattern, HTTP client abstraction). |
| 7 | SDKGEN-64-001 | DONE (2025-12-10) | CLI switched to TS SDK; parity against Go stub verified using Wave B artifacts. | SDK Generator Guild · CLI Guild | Switch CLI to consume TS or Go SDK; ensure parity once Wave B artifacts land. |
| 8 | SDKGEN-64-002 | DONE (2025-12-10) | Console data providers wired to TS/Go SDKs; parity matrix signed off. | SDK Generator Guild · Console Guild | Integrate SDKs into Console data providers where feasible. |
| 9 | SDKREL-63-001 | DONE (2025-12-10) | Sovereign signing keys provisioned; staging/prod release pipelines green across npm/PyPI/Maven/Go. | SDK Release Guild · `src/Sdk/StellaOps.Sdk.Release` | Configure CI pipelines for npm, PyPI, Maven Central staging, and Go proxies with signing and provenance attestations. |
| 10 | SDKREL-63-002 | DONE (2025-12-10) | Changelog automation wired to OAS diffs + generator metadata; publishes alongside releases. | SDK Release Guild · API Governance Guild | Integrate changelog automation pulling from OAS diffs and generator metadata. |
| 11 | SDKREL-64-001 | DONE (2025-12-10) | Notifications Studio hooks live; staged releases emit scoped announcements + RSS/Atom feeds. | SDK Release Guild · Notifications Guild | Hook SDK releases into Notifications Studio with scoped announcements and RSS/Atom feeds. |
| 12 | SDKREL-64-002 | DONE (2025-12-10) | Offline bundle job using manifest at `docs/modules/export-center/devportal-offline-manifest.md` emitted devportal kit with SDK artifacts/specs. | SDK Release Guild · Export Center Guild | Add `devportal --offline` bundle job packaging docs, specs, SDK artifacts for air-gapped users. |

## Wave Coordination
- Single wave covering generator and release work; language tracks branch after SDKGEN-62-002.

## Wave Detail Snapshots
| Wave | Window (UTC) | Scope | Exit criteria | Owners | Status |
| --- | --- | --- | --- | --- | --- |
| A: Generator foundation | 2025-11-25 → 2025-12-02 | SDKGEN-62-001..002 (toolchain pin, shared post-processing) | Toolchain pinned; reproducibility spec approved; shared layer merged. | SDK Generator Guild | Delivered (2025-12-10) |
| B: Language alphas | 2025-12-03 → 2025-12-22 | SDKGEN-63-001..004 (TS, Python, Go, Java alphas) | All four alphas published to staging registries with parity matrix signed off. | SDK Generator Guild | Delivered (2025-12-10) |
| C: Release & offline | 2025-12-08 → 2025-12-29 | SDKREL-63-001..64-002 (CI, changelog, notifications, offline bundle) | CI pipelines green in staging; changelog automation live; notifications wired; offline bundle produced; manifest template in `docs/modules/export-center/devportal-offline-manifest.md` adopted. | SDK Release Guild · Export Center Guild | Delivered (2025-12-10) |

## Interlocks
- API governance: Aggregate OAS snapshot + SHA published at `docs/contracts/api-aggregate-2025-12-10.yaml` + `.sha256`; APIG0101 freeze satisfied.
- Portal contracts: DEVL0101 auth/session inputs consumed in shared post-processing.
- Devportal/offline: Manifest format delivered via `docs/modules/export-center/devportal-offline-manifest.md`; offline bundle job emitted.
- CLI adoption: SPRINT_0201_0001_0001_cli_i aligned; CLI switched to TS SDK (Wave B artifacts delivered).
- Console data providers: SPRINT_0209_0001_0001_ui_i unblocked via parity matrix and SDK drops.
- Notifications/Export: Notifications Studio + Export Center pipelines live; release notifications wired and offline bundle produced.
- Aggregate OAS freeze: Completed with tagged snapshot + SHA (Action #6 closed 2025-12-10).
- Signing keys: Sovereign signing keys provisioned for npm/PyPI/Maven/Go; staging/prod releases validated (Action #7 closed 2025-12-10).

## Upcoming Checkpoints
- 2025-12-05: TS alpha staging drop (SDKGEN-63-001) - delivered 2025-12-10 using frozen aggregate OAS + hash guard.
- 2025-12-15: Multi-language alpha readiness check (SDKGEN-63-002..004) - delivered 2025-12-10; parity matrix signed off.
- 2025-12-16: Delivered parity matrix and SDK drop to UI/Console data providers on 2025-12-10 (Wave B).
- 2025-12-22: Release automation demo - delivered 2025-12-10 with signed staging/prod publishes and offline bundle.

## Action Tracker
| # | Action | Owner | Due (UTC) | Status |
| --- | --- | --- | --- | --- |
| 1 | Confirm registry signing keys and provenance workflow per language | SDK Release Guild | 2025-11-29 | DONE (2025-12-10) |
| 2 | Publish SDK language support matrix to CLI/UI guilds. Evidence: `docs/modules/sdk/language-support-matrix.md`. | SDK Generator Guild | 2025-12-03 | DONE (2025-11-26) |
| 3 | Align CLI adoption scope with SPRINT_0201_0001_0001_cli_i and schedule SDK drop integration | SDK Generator Guild · CLI Guild | 2025-12-10 | DONE (2025-12-10) |
| 4 | Define devportal offline bundle manifest with Export Center per SPRINT_0206_0001_0001_devportal. Evidence: `docs/modules/export-center/devportal-offline-manifest.md`. | SDK Release Guild · Export Center Guild | 2025-12-12 | DONE (2025-11-26) |
| 5 | Deliver parity matrix and SDK drop to UI data providers per SPRINT_0209_0001_0001_ui_i | SDK Generator Guild · UI Guild | 2025-12-16 | DONE (2025-12-10) |
| 6 | Request tagged aggregate OpenAPI snapshot + SHA from APIG0101 to unblock Wave B generation | API Governance Guild · SDK Generator Guild | 2025-12-02 | DONE (2025-12-10) |
| 7 | Escalate sovereign crypto key provisioning for npm/PyPI/Maven/Go signing to unblock SDKREL-63-001 | SDK Release Guild · Platform Security | 2025-12-02 | DONE (2025-12-10) |

## Decisions & Risks
- Toolchain pinned (OpenAPI Generator 7.4.0, JDK 21) and recorded in `TOOLCHAIN.md`/`toolchain.lock.yaml`; downstream tracks must honor lock for determinism.
- Aggregate OAS frozen at `docs/contracts/api-aggregate-2025-12-10.yaml` with SHA in `.sha256`; generators enforce hash guard and emit `.oas.sha256`.
- Signing/provenance pipeline validated: sovereign keys provisioned for npm/PyPI/Maven/Go; staging+prod releases signed with attestations.
- Offline bundle job (SDKREL-64-002) delivered using `docs/modules/export-center/devportal-offline-manifest.md`; devportal kit published with SDK artifacts/specs.
- Shared postprocess helpers copy only when CI sets `STELLA_POSTPROCESS_ROOT` and `STELLA_POSTPROCESS_LANG`; generation jobs continue exporting these to keep helpers present.
- CLI/UI data providers unblocked: parity matrix and Wave B artifacts delivered to consuming guilds (CLI/UI/DevPortal).

### Risk Register
| Risk | Impact | Mitigation | Owner | Status |
| --- | --- | --- | --- | --- |
| Upstream APIs change after generator pin | Rework across four SDKs | Snapshot hash guard + tagged OAS `api-aggregate-2025-12-10` locked; parity matrix published; rerun generation only on intentional bumps. | SDK Generator Guild | Closed (2025-12-10) |
| Aggregate OpenAPI freeze delayed | Wave B and downstream adoption blocked | Freeze delivered at `docs/contracts/api-aggregate-2025-12-10.yaml` + `.sha256`; generators enforce SHA via `STELLA_OAS_EXPECTED_SHA256`. | SDK Generator Guild | Closed (2025-12-10) |
| Registry signing not provisioned | Cannot ship to npm/PyPI/Maven/Go | Sovereign signing keys provisioned; staging/prod release pipelines green with attestations. | SDK Release Guild | Closed (2025-12-10) |
| Offline bundle inputs unavailable | Air-gapped delivery slips | Offline bundle job produced devportal kit with SDK artifacts/specs using manifest contract; rerun on future SDK drops. | SDK Release Guild | Closed (2025-12-10) |

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-11-22 | Normalised sprint to standard template; renamed file to `SPRINT_0208_0001_0001_sdk.md`; no status changes. | PM |
| 2025-11-22 | Added wave plan and dated checkpoints for generator, language alphas, and release/offline tracks. | PM |
| 2025-11-22 | Added explicit interlocks to CLI/UI/Devportal sprints and new alignment actions. | PM |
| 2025-11-22 | Added UI parity-matrix delivery action to keep data provider integration on track. | PM |
| 2025-11-24 | Pinned generator toolchain (OpenAPI Generator CLI 7.4.0, JDK 21), template layout, and reproducibility rules; captured in `src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md` + `toolchain.lock.yaml`. | SDK Generator Guild |
| 2025-11-24 | Started SDKGEN-62-002: added shared post-process scaffold (`postprocess/`), LF/whitespace normalizer script, and README for language hooks. | SDK Generator Guild |
| 2025-11-24 | Completed SDKGEN-62-002: postprocess now copies auth/retry/pagination/telemetry helpers for TS/Python/Go/Java, wires TS/Python exports, and adds smoke tests. | SDK Generator Guild |
| 2025-11-24 | Began SDKGEN-63-001: added TypeScript generator config (`ts/config.yaml`), deterministic driver script (`ts/generate-ts.sh`), and README; waiting on frozen OAS spec to produce alpha artifact. | SDK Generator Guild |
| 2025-11-26 | Published SDK language support matrix for CLI/UI consumers at `docs/modules/sdk/language-support-matrix.md`; Action #2 closed. | SDK Generator Guild |
| 2025-11-26 | Ran TS generator smoke locally with vendored JDK/jar (`ts/test_generate_ts.sh`); pass. Blocked until aggregate OpenAPI spec is frozen/published to generate Wave B alpha artifact. | SDK Generator Guild |
| 2025-11-26 | Closed Action 4: drafted DevPortal offline bundle manifest at `docs/modules/export-center/devportal-offline-manifest.md` to align SDKREL-64-002 with SPRINT_0206. | SDK Release Guild |
| 2025-11-26 | Added spec hash guard to TS/Python generators (`STELLA_OAS_EXPECTED_SHA256`) and emit `.oas.sha256` for provenance; updated smoke tests and READMEs. | SDK Generator Guild |
| 2025-11-26 | Scaffolded Go generator (config/script/smoke), enabled hash guard + helper copy via postprocess, and added `.oas.sha256` emission; waiting on frozen OAS for Wave B alpha. | SDK Generator Guild |
| 2025-11-26 | Scaffolded Java generator (config/script/smoke), added postprocess hook copy into `org.stellaops.sdk`, hash guard + `.oas.sha256`, and vendored-JDK fallback; waiting on frozen OAS for Wave B alpha. | SDK Generator Guild |
| 2025-11-26 | Marked SDKGEN-63-003/004 BLOCKED pending frozen aggregate OAS digest; scaffolds and smoke tests are ready. | SDK Generator Guild |
| 2025-11-26 | Added unified SDK smoke npm scripts (`sdk:smoke:*`, `sdk:smoke`) covering TS/Python/Go/Java to keep pre-alpha checks consistent. | SDK Generator Guild |
| 2025-11-26 | Added CI workflow `.gitea/workflows/sdk-generator.yml` to run `npm run sdk:smoke` on SDK generator changes (TS/Python/Go/Java). | SDK Generator Guild |
| 2025-11-27 | Marked SDKGEN-63-001/002 BLOCKED pending frozen aggregate OAS digest; scaffolds and smokes remain ready. | SDK Generator Guild |
| 2025-11-30 | Marked SDKGEN-64-001 and SDKGEN-64-002 BLOCKED pending Wave B (SDKGEN-63-004) OAS freeze/Java alpha; CLI/UI adoption cannot proceed without generated SDK artifacts. | Project Mgmt |
| 2025-11-30 | Status audit: set SDKGEN-63-001..004 to BLOCKED per aggregate OAS freeze; flagged registry signing key action overdue; added OAS-freeze risk entry. | PM |
| 2025-11-30 | Added Actions #6–#7 to chase aggregate OAS snapshot (APIG0101) and sovereign signing key provisioning by 2025-12-02. | PM |
| 2025-11-30 | Set SDKREL-63-001..64-002 to BLOCKED pending signing keys and downstream artifacts; clarified blockers in Delivery Tracker. | PM |
| 2025-12-01 | Sprint-wide pause: all Delivery Tracker items blocked on OAS snapshot + signing keys; Wave B checkpoints will slip if Actions #6–#7 miss 2025-12-02. | PM |
| 2025-11-24 | Added fixture OpenAPI (`ts/fixtures/ping.yaml`) and smoke test (`ts/test_generate_ts.sh`) to validate TypeScript pipeline locally; skips if generator jar absent. | SDK Generator Guild |
| 2025-11-24 | Vendored `tools/openapi-generator-cli-7.4.0.jar` and `tools/jdk-21.0.1.tar.gz` with SHA recorded in `toolchain.lock.yaml`; adjusted TS script to ensure helper copy post-run and verified generation against fixture. | SDK Generator Guild |
| 2025-11-24 | Ran `ts/test_generate_ts.sh` with vendored JDK/JAR and fixture spec; smoke test passes (helpers present). | SDK Generator Guild |
| 2025-11-24 | Added deterministic TS packaging templates (package.json, tsconfig base/cjs/esm, README, sdk-error) copied via postprocess; updated helper exports and lock hash. | SDK Generator Guild |
| 2025-11-24 | Began SDKGEN-63-002: added Python generator config/script/README + smoke test (reuses ping fixture); awaiting frozen OAS to emit alpha. | SDK Generator Guild |
| 2025-11-27 | Began SDKGEN-63-003: added Go SDK generator scaffold with config (`go/config.yaml`), driver script (`go/generate-go.sh`), smoke test (`go/test_generate_go.sh`), and README; context-first API design documented; awaiting frozen OAS to generate alpha. | SDK Generator Guild |
| 2025-11-27 | Began SDKGEN-63-004: added Java SDK generator scaffold with config (`java/config.yaml`), driver script (`java/generate-java.sh`), smoke test (`java/test_generate_java.sh`), and README; OkHttp + Gson selected as HTTP client/serialization; builder pattern documented; awaiting frozen OAS to generate alpha. | SDK Generator Guild |
| 2025-12-10 | Published aggregate OAS snapshot + SHA (`docs/contracts/api-aggregate-2025-12-10.yaml` + `.sha256`); Actions #6/#7 closed; hash guard enforced for generators. | API Governance Guild / SDK Generator Guild |
| 2025-12-10 | Generated TS/Python/Go/Java alphas, emitted parity matrix, and delivered Wave B artifacts to CLI/UI/DevPortal; SDKGEN-63/64 tasks marked DONE. | SDK Generator Guild |
| 2025-12-10 | Provisioned sovereign signing keys, validated release pipelines across npm/PyPI/Maven/Go with attestations, and shipped offline devportal bundle; SDKREL-63/64 tasks marked DONE. | SDK Release Guild |
| 2025-12-10 | Sprint closed and archived after Wave A/B/C deliverables shipped (SDKGEN/SDKREL complete). | PM |