feat(sdk): generate from committed API contract

[jiashuoz]

Summary

• replace the production-fetched specification with AgentDrive's committed handler-generated contract from merged source commit 190b558bf1a6e1c33fcef9f3a5f2816d4b57badb
• record source path, commit, SHA-256, and generator image in sdk/openapi.provenance.json
• pin OpenAPI Generator to openapitools/openapi-generator-cli:v7.24.0
• make generation deterministic and reproducible across Python, TypeScript, and Go
• add exact operation-coverage and provenance checks
• change CI from scheduled live-production fetching/auto-commit to read-only regeneration and freshness checks
• document the coordinated API/SDK workflow and this one-time contract migration

No package is published by this PR.

Contract migration

The old SDK input was derived from the production document and included browser/UI routes. The committed AgentDrive contract contains:

• 86 paths (previously 159)
• 110 operations (previously 185)
• 128 schemas (previously 123)
• a real BearerAuth scheme
• zero browser/UI operations (previously 45)

The generated diff is intentionally large because all three clients are regenerated from the corrected public machine API in one reproducible migration.

Reproducibility details

• the canonical sdk/openapi.json is never rewritten by codegen preparation
• language-specific projections exist only in a temporary directory and work around known OpenAPI Generator 3.1 union limitations
• the TypeScript lockfile is preserved and verified with npm ci
• generation removes only the three explicit generated-language roots and normalizes deterministic trailing whitespace/EOF
• CI regenerates, requires a clean Git diff, and verifies exact canonical-operation coverage

Verification

• helper tests: 21 passed
• generated Python tests: 237 passed
• TypeScript npm ci and npm run build: passed
• Go go test ./...: passed
• exact operation coverage: passed
• contract/source digest and generator-pin provenance: passed
• untracked generated-file freshness sentinel: correctly rejected
• generation from outside the repository root: passed; traversal/symlink escapes are rejected before cleanup
• pinned regeneration after staging: zero working-tree diff
• custom scripts/tests Ruff: passed
• git diff --cached --check: passed before commit

Coordination

This PR is coordinated with
tokencanopy/agentdrive#373.
Future SDK updates should be generated only from a reviewed committed
AgentDrive golden contract, with the provenance source commit updated in the
same change.

AgentDrive #373 has now merged. This PR is pinned to its durable main commit
190b558bf1a6e1c33fcef9f3a5f2816d4b57badb; the reviewed contract digest is
unchanged.