Versionado de la API

Al construir sobre cmssy importan dos versiones, y solo una está en tu lockfile. "@cmssy/core": "16.9.0" fija el cliente. La API de entrega a la que llama es un servicio alojado que se despliega a su propio ritmo, y no hay ningún segmento de versión que puedas fijar en su lugar.

Esta página dice sin rodeos qué implica eso, incluida la parte que todavía no garantizamos.

Qué cubre la versión del paquete

Semver normal, y solo sobre este paquete: sus exports, sus firmas, su comportamiento. Un major significa que tu código puede necesitar cambios. No dice nada del esquema del otro lado: un campo eliminado del esquema de entrega ha desaparecido para @cmssy/core@16.9.0 exactamente igual que para la siguiente versión.

Qué te protege hoy

• La superficie de entrega es una lista de permitidos. El endpoint bajo /public/{org}/{workspace}/graphql sirve un subconjunto elegido a propósito del esquema, no todo lo que ve la API de administración. Un campo está ahí porque alguien lo puso ahí.
• Un cambio rompedor no puede fusionarse en silencio. Cada cambio del esquema se compara en CI con el anterior. Una eliminación o un estrechamiento hace fallar la barrera, y enviarlo de todos modos exige una aprobación explícita y registrada.
• Las operaciones publicadas se validan. Las consultas del propio SDK, las del servidor MCP y las de la tienda de referencia se ejecutan contra el esquema propuesto antes de poder fusionarlo.
• Las eliminaciones se marcan primero. Un campo que pensamos retirar se marca @deprecated en el esquema, y eso aparece en la salida de tu codegen y en tu editor.

Qué no existe todavía

Dicho, en lugar de insinuado:

• No hay ninguna versión de API con fecha que fijar. El endpoint de entrega no tiene segmento de versión.
• No hay ninguna ventana de deprecación garantizada. @deprecated marca una intención; no promete que el campo sobreviva un número fijo de días.
• No hay ningún preaviso mínimo ni lista de anuncios a la que suscribirse.

Preferimos escribirlo a dejar que un número de versión insinúe una promesa que el servidor no cumple.

Qué hacer al respecto

Genera tus tipos desde el endpoint de entrega, no desde el esquema de administración. Es más estrecho, y tipar contra él hace que tu build falle en un campo que nunca tuviste permiso para leer:

// codegen.ts
schema: `${process.env.CMSSY_API_URL}/public/${org}/${workspace}/graphql`,
documents: ["app/**/*.tsx", "lib/**/*.ts"],

Ejecuta codegen en tu propia CI, no solo en tu máquina. Si un campo que seleccionas desaparece, codegen falla ahí, y ese es el momento más temprano en que alguien de fuera de cmssy puede enterarse.

Fija el SDK y actualiza de forma deliberada. No te protege de los cambios de esquema, pero evita que el comportamiento del propio cliente se mueva bajo tus pies al mismo tiempo.