@ancplua/qyl-api-schema 0.2.2 → 0.3.0

package/README.md

@@ -9,11 +9,12 @@ owned by qyl.
 ## Contract pipeline
 
 ```text
-open-telemetry/semantic-conventions @ v1.41.0
+open-telemetry/semantic-conventions @ v1.43.0  +  semantic-conventions-genai (dev registry)
         |
-        | Weaver
+        | Weaver (Qyl.OpenTelemetry.SemanticConventions repo:
+        |   generate.sh -> resolved-registry.json -> emit_typespec_keys.py)
         v
-@ancplua/typespec-otel-semconv
+generated/otel-keys.gen.tsp
         |
         | TypeSpec import / lockstep key projection
         v
@@ -27,10 +28,12 @@ OpenAPI JSON + JSON Schema + Qyl.Api.Contracts + TS contract types
 qyl services, dashboard, tools, and generated clients
 ```
 
-The generic OpenTelemetry key projection lives in
-`@ancplua/typespec-otel-semconv` under
-`ANcpLua.OpenTelemetry.SemanticConventions.Keys.*`. This repo defines qyl domain
-models, routes, and response contracts under `Qyl.Api.Contracts.*`.
+The generic OpenTelemetry key projection is the checked-in
+`generated/otel-keys.gen.tsp` under
+`ANcpLua.OpenTelemetry.SemanticConventions.Keys.*`, regenerated by the
+`Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline.
+This repo defines qyl domain models, routes, and response contracts under
+`Qyl.Api.Contracts.*`.
 
 ## Published artifacts
 

package/VERSIONING.md

@@ -40,14 +40,6 @@ enum GenAiVersions {
 }
 
 model GenAiSpanAttributes {
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.System)
-  @removed(GenAiVersions.v1_37)
-  system?: string;
-
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsagePromptTokens)
-  @removed(GenAiVersions.v1_28)
-  usagePromptTokens?: TokenCount;
-
   @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageInputTokens)
   usageInputTokens?: TokenCount;
 
@@ -57,6 +49,14 @@ model GenAiSpanAttributes {
 }
 ```
 
+Note (v0.3.0): the pre-migration `gen_ai.*` fields that carried upstream-deleted
+wire keys (`gen_ai.system`, `gen_ai.prompt`, `gen_ai.completion`,
+`gen_ai.usage.prompt_tokens` / `.completion_tokens`, and the
+`gen_ai.openai.*` vendor keys) were **removed from the contract surface**
+when the OTel 1.42 GenAI-registry split was adopted. Old-key telemetry is a
+collector *ingestion normalization* concern (mapping below), not a contract
+field.
+
 ## Ingestion mapping (deprecated -> current)
 
 Consumers can keep ingestion backward-compatible by normalizing deprecated attribute keys. Keep any downstream mapping aligned with the TypeSpec history.

package/common/types.tsp

@@ -2,7 +2,8 @@
 // qyl common types and scalars
 // =============================================================================
 // Foundational types used across qyl API contracts and OTel-compatible models.
-// OpenTelemetry semantic-convention references are pinned to v1.41.0.
+// OpenTelemetry semantic-convention references are pinned to core v1.43.0
+// (GenAI keys come from the dedicated GenAI registry since the 1.42 split).
 // =============================================================================
 
 import "@typespec/versioning";
@@ -42,8 +43,14 @@ enum OTelVersion {
   @doc("OTel Semconv v1.40 - Oracle DB split, RPC cleanup, GenAI cache tokens")
   v1_40: "1.40.0",
 
-  @doc("OTel Semconv v1.41 - Current compatibility pin")
+  @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",
 }
 
 // =============================================================================

package/generated/README.md

@@ -1,26 +1,35 @@
 # generated
 
-This directory holds Weaver-generated TypeSpec files. **Do not edit by hand.**
+This directory holds the semconv TypeSpec key projection and the emitter
+outputs. `otel-keys.gen.tsp` is Weaver-generated — **do not edit by hand**.
 
 ## Files
 
 | File | Source | Regenerate via |
 | --- | --- | --- |
-| `otel-keys.gen.tsp` | OpenTelemetry semantic-conventions v1.41.0 YAML model, converted by the upstream generator [`ANcpLua/typespec-otel-semconv`](https://github.com/ANcpLua/typespec-otel-semconv) (Weaver-based) | Re-run that generator's pipeline (`scripts/generate.mjs`) and replace this checked-in TypeSpec projection. Lockstep flip planned: this directory becomes a dep on `@ancplua/typespec-otel-semconv@<semconv-version>-<N>` and stops being a checked-in artifact. |
+| `otel-keys.gen.tsp` | OpenTelemetry semantic-conventions core **v1.43.0** + the GenAI dev registry (`open-telemetry/semantic-conventions-genai`, pinned commit), merged and projected by the `Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline | In that repo: `src/…SourceGeneration/scripts/generate.sh` (refresh `Resources/resolved-registry.json`), then `src/…SourceGeneration/scripts/emit_typespec_keys.py --write <path-to-this-file>` |
 
-## What `otel-keys.gen.tsp` provides
+## What the key files provide
 
 One TypeSpec namespace per OpenTelemetry root group, each declaring `const <Name>: string = "<dotted.key>"`. Extracted `.tsp` models reference these consts inside `@encodedName(...)` instead of hand-typing dotted attribute keys.
 
 ```tsp
-@encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.System)
-system?: string;
+@encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.ProviderName)
+providerName?: string;
 ```
 
 Deprecated upstream attributes are emitted with `#deprecated "..."` so models that reference them produce a TypeSpec compiler warning matching upstream's own deprecation notes.
 
 ## Pin
 
-The checked-in projection is pinned to upstream OpenTelemetry semantic-conventions v1.41.0.
-
-Bumping the pin requires regenerating this file from the upstream YAML model with Weaver — done in [`ANcpLua/typespec-otel-semconv`](https://github.com/ANcpLua/typespec-otel-semconv) — before updating this repository. Direction is one-way: this repo never invokes Weaver directly.
+The checked-in projection is pinned to core semantic-conventions **v1.43.0**
+(commit in the file header) plus the GenAI dev registry commit pinned in the
+SemanticConventions repo's `generate.sh` (`SEMCONV_GENAI_REF`). The
+`VerifyKeysLockstep` Nuke target asserts the header pin matches the
+`OtelKeysVersion` parameter (`.nuke/parameters.json`).
+
+Bumping the pin: update the refs in that repo's `generate.sh`, re-run it plus
+`emit_typespec_keys.py --write`, replace this checked-in projection, and keep
+`SemConvSchemaVersion` in that repo's `Version.props` in lockstep — the .NET
+constants and this TypeSpec projection must cite the same registry versions.
+Direction is one-way: this repo never invokes Weaver directly.