@ancplua/qyl-api-schema 0.3.0 → 0.4.0

package/VERSIONING.md

@@ -30,14 +30,18 @@ namespace Qyl.Api.Contracts.Domains.AI.GenAi;
 
 enum GenAiVersions {
   v1_27: "1.27.0",
-  v1_28: "1.28.0",
-  v1_29: "1.29.0",
-  v1_37: "1.37.0",
   v1_38: "1.38.0",
-  v1_39: "1.39.0",
   v1_40: "1.40.0",
-  v1_41: "1.41.0",
 }
+```
+
+Keep version enums **minimal**: only the baseline plus versions actually
+referenced by an `@added`/`@removed` annotation. Unreferenced members are
+dead timeline points that rot (an axis with no annotations at all should
+lose `@versioned` entirely — that happened to `HttpVersions`/`DbVersions`
+in 0.4.0).
+
+```tsp
 
 model GenAiSpanAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageInputTokens)

package/common/types.tsp

@@ -16,46 +16,13 @@ using TypeSpec.OpenAPI;
 
 namespace Qyl.Api.Contracts.Common;
 
-// =============================================================================
-// Version Enum - OTel Semantic Convention Versions
-// =============================================================================
-
-@doc("OpenTelemetry semantic-convention versions supported by qyl compatibility models")
-enum OTelVersion {
-  @doc("OTel Semconv v1.27 - Base version")
-  v1_27: "1.27.0",
-
-  @doc("OTel Semconv v1.28 - GenAI additions")
-  v1_28: "1.28.0",
-
-  @doc("OTel Semconv v1.29 - HTTP improvements")
-  v1_29: "1.29.0",
-
-  @doc("OTel Semconv v1.30 - Database updates")
-  v1_30: "1.30.0",
-
-  @doc("OTel Semconv v1.38 - GenAI.Agent support")
-  v1_38: "1.38.0",
-
-  @doc("OTel Semconv v1.39 - RPC metadata consolidation")
-  v1_39: "1.39.0",
-
-  @doc("OTel Semconv v1.40 - Oracle DB split, RPC cleanup, GenAI cache tokens")
-  v1_40: "1.40.0",
-
-  @doc("OTel Semconv v1.41 - GraphQL doc opt-in, RPC server client.* removal")
-  v1_41: "1.41.0",
-
-  @doc("OTel Semconv v1.42 - GenAI conventions moved to the dedicated GenAI registry; k8s/container registry attrs stable")
-  v1_42: "1.42.0",
-
-  @doc("OTel Semconv v1.43 - Current compatibility pin (core; GenAI keys from the GenAI dev registry)")
-  v1_43: "1.43.0",
-}
-
 // =============================================================================
 // Identifier Scalars - Strongly Typed IDs
 // =============================================================================
+// (The former OTelVersion enum — a hand-bumped list of semconv releases with
+// zero consumers — was deleted in 0.4.0. The semconv pin lives in the
+// otel-keys.gen.tsp header and .nuke/parameters.json OtelKeysVersion, both
+// machine-checked; a prose enum of upstream releases only rots.)
 
 @jsonSchema
 @doc("Unique trace identifier (32 lowercase hex characters)")

package/models/db.tsp

@@ -10,28 +10,8 @@ import "../common/types.tsp";
 using TypeSpec.Versioning;
 using Qyl.Api.Contracts.Common;
 
-@versioned(DbVersions)
 namespace Qyl.Api.Contracts.Domains.Data.Db;
 
-// =============================================================================
-// Version History
-// =============================================================================
-
-@doc("Database semantic convention versions")
-enum DbVersions {
-  @doc("Legacy DB semconv")
-  v1_20: "1.20.0",
-
-  @doc("Stable DB semconv with namespace")
-  v1_24: "1.24.0",
-
-  @doc("DB semconv v1.38")
-  v1_38: "1.38.0",
-
-  @doc("Current DB semconv")
-  v1_39: "1.39.0",
-}
-
 // =============================================================================
 // Database Span Attributes
 // =============================================================================
@@ -118,29 +98,6 @@ model DbAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Db.ClientConnectionState)
   connectionState?: DbConnectionState;
 
-  // ---------------------------------------------------------------------------
-  // Deprecated Attributes (for migration)
-  // ---------------------------------------------------------------------------
-
-  @doc("Database name (deprecated - use db.namespace)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Db.Name)
-  @removed(DbVersions.v1_24)
-  dbName?: string;
-
-  @doc("Database statement (deprecated - use db.query.text)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Db.Statement)
-  @removed(DbVersions.v1_24)
-  statement?: string;
-
-  @doc("Database operation (deprecated - use db.operation.name)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Db.Operation)
-  @removed(DbVersions.v1_24)
-  operation?: string;
-
-  @doc("Database user (deprecated)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Db.User)
-  @removed(DbVersions.v1_24)
-  user?: string;
 }
 
 // =============================================================================

package/models/genai.tsp

@@ -22,26 +22,14 @@ namespace Qyl.Api.Contracts.Domains.AI.GenAi;
 // Version History
 // =============================================================================
 
-@doc("GenAI semantic convention versions")
+@doc("GenAI semantic convention versions (only versions referenced by @added/@removed annotations are kept)")
 enum GenAiVersions {
   @doc("Initial GenAI semconv (OTel 1.27)")
   v1_27: "1.27.0",
 
-  @doc("Added agent support (OTel 1.28)")
-  v1_28: "1.28.0",
-
-  @doc("Token type refinements (OTel 1.29)")
-  v1_29: "1.29.0",
-
-  @doc("Deprecated gen_ai.system (OTel 1.37)")
-  v1_37: "1.37.0",
-
   @doc("GenAI.Agent support (OTel 1.38)")
   v1_38: "1.38.0",
 
-  @doc("RPC metadata consolidation (OTel 1.39)")
-  v1_39: "1.39.0",
-
   @doc("Current version (OTel 1.40)")
   v1_40: "1.40.0",
 }
@@ -154,11 +142,6 @@ model GenAiSpanAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageOutputTokens)
   usageOutputTokens?: TokenCount;
 
-  @doc("Total tokens (deprecated - use input + output)")
-  @encodedName("application/json", "gen_ai.usage.total_tokens")
-  @removed(GenAiVersions.v1_38)
-  usageTotalTokens?: TokenCount;
-
   @doc("Number of cached input tokens (prompt caching)")
   @encodedName("application/json", "gen_ai.usage.input_tokens.cached")
   @added(GenAiVersions.v1_38)

package/models/http.tsp

@@ -10,28 +10,8 @@ import "../common/types.tsp";
 using TypeSpec.Versioning;
 using Qyl.Api.Contracts.Common;
 
-@versioned(HttpVersions)
 namespace Qyl.Api.Contracts.Domains.Transport.Http;
 
-// =============================================================================
-// Version History
-// =============================================================================
-
-@doc("HTTP semantic convention versions")
-enum HttpVersions {
-  @doc("Legacy HTTP semconv")
-  v1_20: "1.20.0",
-
-  @doc("Stable HTTP semconv")
-  v1_23: "1.23.0",
-
-  @doc("HTTP semconv v1.38")
-  v1_38: "1.38.0",
-
-  @doc("Current HTTP semconv")
-  v1_39: "1.39.0",
-}
-
 // =============================================================================
 // HTTP Span Attributes
 // =============================================================================
@@ -184,39 +164,6 @@ model HttpAttributes {
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.RequestResendCount)
   requestResendCount?: int32;
 
-  // ---------------------------------------------------------------------------
-  // Deprecated Attributes (for migration)
-  // ---------------------------------------------------------------------------
-
-  @doc("Request target (deprecated - use url.path + url.query)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.Target)
-  @removed(HttpVersions.v1_23)
-  target?: string;
-
-  @doc("Request URL (deprecated - use url.full)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.Url)
-  @removed(HttpVersions.v1_23)
-  url?: UrlString;
-
-  @doc("HTTP method (deprecated - use http.request.method)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.Method)
-  @removed(HttpVersions.v1_23)
-  method?: string;
-
-  @doc("Status code (deprecated - use http.response.status_code)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.StatusCode)
-  @removed(HttpVersions.v1_23)
-  statusCode?: int32;
-
-  @doc("Request content length (deprecated)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.RequestContentLength)
-  @removed(HttpVersions.v1_23)
-  requestContentLengthLegacy?: ByteSize;
-
-  @doc("Response content length (deprecated)")
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Http.ResponseContentLength)
-  @removed(HttpVersions.v1_23)
-  responseContentLengthLegacy?: ByteSize;
 }
 
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
   "license": "Apache-2.0",
   "repository": {