save checkpoint: save features

docs/features/checked/sdk/sdk-generator-toolchain.md

@@ -0,0 +1,58 @@
+# SDK Generator Toolchain (Multi-Language)
+
+## Module
+Sdk
+
+## Status
+VERIFIED
+
+## Description
+Multi-language SDK generator toolchain producing typed API clients in TypeScript, Python, Go, and Java from OpenAPI specifications, with postprocessing, release pipelines, and offline bundle support.
+
+## Implementation Details
+- **Go Generator**: `src/Sdk/StellaOps.Sdk.Generator/go/` -- Go SDK generation configuration and scripts. Key files: `config.yaml` (OpenAPI Generator config for Go), `generate-go.sh` (generation script), `test_generate_go.sh` (test script).
+- **Java Generator**: `src/Sdk/StellaOps.Sdk.Generator/java/` -- Java SDK generation. Key files: `config.yaml`, `generate-java.sh`, `test_generate_java.sh`.
+- **Python Generator**: `src/Sdk/StellaOps.Sdk.Generator/python/` -- Python SDK generation. Key files: `config.yaml`, `generate-python.sh`, `test_generate_python.sh`.
+- **Postprocessing Pipeline**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/` -- post-generation processing adding hooks, error handling, and SDK-specific customizations. Key files: `postprocess.sh` (orchestrator), `README.md` (documentation).
+- **Postprocessing Templates**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/templates/` -- language-specific hook templates: `go/hooks.go`, `java/src/main/java/org/stellaops/sdk/Hooks.java`, `python/sdk_hooks.py`, `typescript/sdk-hooks.ts`, `typescript/sdk-error.ts`, `typescript/package.json`, `typescript/tsconfig.*.json`.
+- **Toolchain Lock**: `src/Sdk/StellaOps.Sdk.Generator/toolchain.lock.yaml` -- pinned versions of generator tools for reproducible builds.
+- **Toolchain Documentation**: `src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md` -- documentation of the toolchain, versions, and upgrade process.
+- **Vendored Tools**: `src/Sdk/StellaOps.Sdk.Generator/tools/openapi-generator-cli-7.4.0.jar` (OpenAPI Generator), `tools/jdk-21.0.1.tar.gz` (JDK for Java generation).
+- **Postprocessing Tests**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/tests/test_postprocess.sh` -- tests for postprocessing pipeline.
+
+## E2E Test Plan
+- [x] Run the Go SDK generation script (`generate-go.sh`) against the OpenAPI spec and verify it produces a compilable Go client package
+- [x] Run the Java SDK generation script and verify the output compiles with the vendored JDK
+- [x] Run the Python SDK generation script and verify the output is a valid Python package with correct module structure
+- [x] Run the postprocessing pipeline on a generated TypeScript SDK and verify hooks, error handling, and package.json are correctly injected
+- [x] Verify toolchain pinning inputs are present (`toolchain.lock.yaml`, vendored generator jar, vendored JDK tarball) and consumed by generator smoke workflows
+- [x] Run all test scripts (`test_generate_ts.sh`, `test_generate_go.sh`, `test_generate_java.sh`, `test_generate_python.sh`, `test_postprocess.sh`) and verify they pass
+- [x] Verify offline-capable generation path uses local fixture spec and vendored generator artifacts
+
+## Verification
+- **Run ID**: run-002
+- **Date**: 2026-02-11
+- **Method**: Tier 0 source verification + Tier 1/Tier 2 shell-based generator smoke replay
+- **Build/Test**: PASS (5/5 script-based generator/postprocess smoke checks)
+- **Tier 0 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier0-source-check.json`
+- **Tier 1 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier1-build-check.json`
+- **Tier 2 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier2-integration-check.json`
+- **Command Output Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/evidence/`
+
+## Recheck Notes
+- Initial replay attempt (`_run-001_capture`) exposed a host-shell interoperability bug: Go/Java scripts were CRLF, causing `set -euo pipefail` parsing failures in Bash.
+- Fix applied: normalized LF endings for:
+  - `src/Sdk/StellaOps.Sdk.Generator/go/test_generate_go.sh`
+  - `src/Sdk/StellaOps.Sdk.Generator/java/test_generate_java.sh`
+  - `src/Sdk/StellaOps.Sdk.Generator/go/generate-go.sh`
+  - `src/Sdk/StellaOps.Sdk.Generator/java/generate-java.sh`
+- Retest (`run-002`) passed all generator/postprocess smoke checks with fresh evidence.
+
+## Recheck (Run-003)
+- **Verified**: 2026-02-11
+- **Method**: Strict Tier 2 shell-based behavioral replay with vendored JDK setup and explicit negative-path coverage.
+- **Build/Test**: PASS (7/7 script smokes): `test_line_endings.sh`, `test_generate_ts.sh`, `test_generate_go.sh`, `test_generate_java.sh`, `test_generate_python.sh`, `test_postprocess.sh`, `test_generate_ts_hash_mismatch.sh`.
+- **Tier 0 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier0-source-check.json
+- **Tier 1 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier1-build-check.json
+- **Tier 2 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier2-integration-check.json
+- **Outcome**: Recheck remained green with new regression guards for LF line endings and TS spec-hash mismatch handling.