Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Developer
Experience + OSHUN Security + Platform SRE + OSHUN Data/Analytics Engineering
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0048-oshun-studio-sdk-and-documentation-integration.mddocs/releases/v1/specs/studio-sdk-and-documentation-integration-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio SDK and documentation integration workflows.
This document is the execution artifact for OST-00283.
Personas#
- Integration Engineer
- SDK Maintainer
- Documentation Maintainer
- Security Reviewer
- Compliance Auditor
- Release Manager
Journey Principles#
- Contract authority must drive SDK and documentation artifacts.
- SDK and docs publication must be versioned, traceable, and reversible.
- Example snippets must be validated against active contract versions.
- Sensitive production publication paths require role/tier/approval controls.
1. Primary Journeys#
J1. Promote Contract Version and Initialize Integration Pipeline#
Goal: Promote a validated contract version that triggers synchronized SDK and documentation generation workflows.
Entry: SDK/documentation integration workspace
Steps:
- Select domain/service contract candidate.
- Validate contract digest, schema compatibility, and migration notes.
- Promote contract to active lifecycle state.
- Trigger SDK and docs generation pipelines.
- Emit contract-promotion governance audit event.
Success State:
- Active contract version is registered and downstream generation workflows are initialized.
J2. Generate and Publish Versioned SDK Artifact#
Goal: Produce a deterministic SDK artifact for target language/runtime.
Entry: Contract promotion completion
Steps:
- Select target SDK language/package profile.
- Generate typed client from active contract source.
- Run SDK validation suite (typing, smoke tests, compatibility checks).
- Publish artifact to scoped package channel.
- Emit SDK publication telemetry and audit evidence.
Success State:
- SDK package is published with contract-linked metadata and validation evidence.
J3. Assemble and Publish Documentation Release#
Goal: Publish API reference, guides, and code samples synchronized with SDK and contract versions.
Entry: SDK generation success
Steps:
- Assemble reference docs and migration notes from contract metadata.
- Generate/update language-specific SDK usage examples.
- Validate samples against generated SDK and active contract.
- Publish docs to target channel (preview/staging/production).
- Emit documentation publication and validation audit evidence.
Success State:
- Documentation release is published with contract-aligned API/reference/sample integrity.
J4. Decide Sensitive Publication or Rollback Action#
Goal: Govern production publish/rollback actions with explicit policy controls.
Entry: Production publish request or Incident-driven rollback request
Steps:
- Evaluate actor role, tier, and release-channel scope.
- Validate approval prerequisites for production actions.
- Allow or deny action with reason code.
- Persist decision evidence for compliance.
- Emit policy decision telemetry and audit event.
Success State:
- Sensitive publication actions are governed, reason-coded, and compliance-ready.
J5. Recover SDK/Documentation Drift and Close Incident#
Goal: Resolve doc/sdk/contract drift and safely restore healthy release state.
Entry: Open integration consistency incident
Steps:
- Correlate drift signals (contract mismatch, sample failures, package skew).
- Apply mitigation (republish, rollback, cache invalidation, patch release).
- Re-run SDK/doc validation suite.
- Confirm telemetry and audit continuity restoration.
- Close incident with post-recovery evidence.
Success State:
- Integration consistency is restored and incident closure is evidence-backed.
2. Critical Edge Cases#
E1. Contract Promotion Missing Digest#
- Trigger: promotion request omits contract digest/identity.
- Required behavior: hard deny with contract-validation reason code.
E2. Breaking Contract Without Migration Notes#
- Trigger: breaking schema change has no migration guidance.
- Required behavior: block promotion and require migration artifact.
E3. SDK Generation Completes With Type Errors#
- Trigger: generated client compile/type checks fail.
- Required behavior: mark generation as failed and block publication.
E4. SDK Publish Version Conflict#
- Trigger: package version already exists in target channel.
- Required behavior: deny publish and require explicit version bump.
E5. Documentation Release Missing API Reference Section#
- Trigger: docs bundle excludes required API reference artifacts.
- Required behavior: fail publication and require complete bundle.
E6. Code Sample Contract Drift#
- Trigger: sample execution fails against active contract or SDK version.
- Required behavior: block docs promotion and require sample remediation.
E7. Production Publish Without CAB/Approval Ticket#
- Trigger: production publish requested without required approval evidence.
- Required behavior: hard deny and emit policy-denial audit event.
E8. Unauthorized Restricted-Tier Rollback Request#
- Trigger: actor without restricted permissions requests rollback.
- Required behavior: deny action and preserve current release state.
E9. Artifact Repository Degradation#
- Trigger: package/docs registry unavailable during publication.
- Required behavior: mark degraded-release state and pause promotions.
E10. Telemetry or Audit Sink Failure#
- Trigger: publish succeeds but telemetry/audit evidence cannot persist.
- Required behavior: flag degraded observability and block production promotion.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Promote Contract and Initialize Pipeline | Contract governance panel | Schema registry + migration policy validators |
| J2 Generate and Publish SDK Artifact | SDK generation panel | Build/test pipelines + package registry |
| J3 Assemble and Publish Documentation | Documentation release panel | Docs assembler + sample validation harness |
| J4 Decide Sensitive Publish/Rollback | Publication policy panel | RBAC/tier engine + approval governance |
| J5 Recover SDK/Docs Drift | Incident recovery panel | Telemetry dashboards + rollback/republish orchestration |
4. Instrumentation Requirements#
Required events:
sdk_docs_integration.journey.startedsdk_docs_integration.journey.step.completedsdk_docs_integration.journey.blockedsdk_docs_integration.journey.validation_failedsdk_docs_integration.journey.recoveredsdk_docs_integration.journey.completed
Required dimensions:
contractId,contractVersion,contractDigest,domain,serviceartifactId,artifactType,packageName,packageVersion,docVersiongenerationId,publicationId,sampleId,validationStatusactorId,actorRole,permissionTier,releaseChannel,approvalTicketjourneyId,stepId,outcome,reasonCode,latencyMs
5. Acceptance Criteria (OST-00283)#
OST-00283 is complete only when:
- At least five SDK/documentation integration journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.