fix(sdk-generator): distinguish nullable values

[calvin-archastro]

Review on ArchCode

What changed

OpenAPI nullable values now have a distinct SDK-generator AST representation instead of reusing the representation for an omitted object key. This keeps requiredness and nullability independent across the TypeScript, Python, Swift, and Go backends.

For TypeScript, required nullable properties now emit T | null with Zod .nullable(). Optional nullable properties retain both states as T | null | undefined with .nullable().optional(). The cross-language emitters and contract-value generators preserve their native equivalents, including recursive references, auth token discovery, required channel payloads, query serialization, and Go pointer depth.

Generated TypeScript and Python contract harnesses now start Prism in static mode. Dynamic generation is not needed for these shape contracts and triggers a nondeterministic json-schema-faker crash on the valid nested oneOf structure in ActivityFeed responses.

Scope

Tooling/backend-only. This changes generated SDK source and generated contract-test harnesses; it does not modify the platform API or product UI.

Risk

Medium. TypeRef is shared by four language backends, so the blast radius extends beyond the TypeScript failure that exposed the defect. Focused tests cover every affected backend and an independent audit checked wrapper traversal, required nullable payloads, query encoding, recursive Swift models, Python auth discovery, and Go contract pointer depth.

User impact

SDK consumers receive correct required-nullable types instead of properties that are incorrectly optional. Generated contract tests become deterministic for complex valid response schemas.

Testing

• npm run build in packages/sdk-generator — passes on generator 0.8.0.
• npm test in packages/sdk-generator — 339 tests pass.
• Canonical focused proof: packages/sdk-generator/__tests__/backends/typescript.test.ts, keeps nullability separate from whether an object key is required. It parses a minimal OpenAPI document through the real frontend and emits the TypeScript interface and Zod validator, asserting required-nullable and optional-nullable output together.
• Prism regression proofs: uses deterministic Prism responses for generated shape contracts in the TypeScript and Python backend test files asserts the generated process configuration does not enable dynamic faker responses.
• Cross-language edge cases: Swift and Go tests cover nullable recursive references, explicit JSON null channel payloads, nullable queries, and Go contract-call pointer depth. The Python client test covers nullable auth response references.
• Manual downstream proof: regenerated ArchAstro/archastro-js PR 44 from its bundled platform spec using this generator, then ran the SDK build, TypeDoc, and the generated contract suite. Build and TypeDoc passed; all 1,095 contract tests passed, including custom-object REST and channel coverage.
• Retry evidence: rerunning the original PR 44 Contract Tests job failed again with the same json-schema-faker@0.5.8 ActivityFeed crash. Isolated dynamic requests failed roughly 60–66% of the time; static Prism responses succeeded consistently.

The repository does not contain an honest end-to-end test that crosses the published npm package and downstream archastro-js workflow boundary. The manual downstream regeneration above covers that boundary for this change; publishing the next generator version and regenerating archastro-js is the follow-up that makes it permanent.

Follow-ups and known issues

• Publish a new @archastro/sdk-generator version after merge.
• Regenerate archastro-js from the refreshed OpenAPI spec with that version, replacing the currently failing generated artifact in PR 44.
• No platform OpenAPI contract changes are required for CustomObjectJoinResponse; its required + nullable schema is valid.