@ancplua/qyl-api-schema 0.2.1 → 0.2.3

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  (+ generated/otel-keys-legacy.tsp, hand-frozen wire keys)
         |
         | TypeSpec import / lockstep key projection
         v
@@ -27,10 +28,13 @@ 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 (the retired
+`@ancplua/typespec-otel-semconv@1.41.0-2` package was its frozen predecessor).
+This repo defines qyl domain models, routes, and response contracts under
+`Qyl.Api.Contracts.*`.
 
 ## Published artifacts
 
@@ -84,6 +88,10 @@ npm run compile
 
 ## Publishing
 
-During normal operation, GitHub Releases publish npm and NuGet artifacts in lockstep. When GitHub
-Actions is unavailable, publish manually from locally verified artifacts using package tokens passed
-through environment variables. Never print tokens and never commit credentials.
+Publishing is fully automated via GitHub Actions OIDC **trusted publishing** — no stored secrets, no
+API keys. Publish a GitHub Release whose tag is `vMAJOR.MINOR.PATCH[-prerelease]`; `publish.yml` then,
+all-or-nothing, packs and validates the artifacts, stamps that single tag-derived version onto both,
+pushes `Qyl.Api.Contracts` to nuget.org (NuGet/login OIDC) and publishes `@ancplua/qyl-api-schema` to
+npmjs.org (npm trusted publishing + provenance). NuGet pushes first (idempotent) and npm last
+(immutable), so a partial failure re-runs cleanly. See [VERSIONING.md](VERSIONING.md) for how the
+version is derived from the tag. There are no long-lived publish tokens to manage or rotate.

package/VERSIONING.md

@@ -2,6 +2,16 @@
 
 This repository uses `@typespec/versioning` to record when schema elements were added or removed across qyl API versions and OpenTelemetry compatibility-model pins. The annotations live in TypeSpec so schema evolution is reviewable at the contract source.
 
+## Release versioning (the package version)
+
+Separate from the `@typespec/versioning` schema annotations below: the published **package** version
+(npm `@ancplua/qyl-api-schema` and NuGet `Qyl.Api.Contracts`) is **CI-owned and tag-derived** — no
+hand-bumped version lives in any committed file. To cut a release, publish a GitHub Release whose tag
+is `vMAJOR.MINOR.PATCH[-prerelease]`; `publish.yml` strips the leading `v` and stamps that single
+version onto both npm and NuGet (no build metadata — npm rejects it and NuGet strips it), so the two
+registries are lockstep by construction. The committed `package.json` version is the non-authoritative
+placeholder `0.0.0-development`, and `packaging/Qyl.Api.Contracts.csproj` carries no `<Version>`.
+
 ## Where it is used
 
 - `models/genai.tsp` for GenAI semantic-convention shaped models

package/generated/README.md

@@ -1,14 +1,23 @@
 # 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**.
+`otel-keys-legacy.tsp` is the one deliberate exception: hand-maintained,
+see below.
 
 ## 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>` |
+| `otel-keys-legacy.tsp` | Hand-maintained. Frozen legacy wire keys (10 `gen_ai.*` consts) that upstream deleted at the 1.41→1.43 bump but that qyl's published contracts still carry on deprecated migration fields. Values are verbatim from the last registry that defined them (v1.41.0). | Never regenerated. Delete a const here only if upstream re-introduces the same name (the `VerifyKeysLockstep` Nuke target and the TypeSpec duplicate-declaration error both catch that). |
 
-## What `otel-keys.gen.tsp` provides
+The predecessor projection was the npm package
+[`@ancplua/typespec-otel-semconv@1.41.0-2`](https://github.com/ANcpLua/typespec-otel-semconv)
+— its source repo is archived/deleted, so 1.41.0-2 was its last possible
+release; it is no longer a dependency of this repo.
+
+## 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.
 
@@ -17,10 +26,18 @@ One TypeSpec namespace per OpenTelemetry root group, each declaring `const <Name
 system?: string;
 ```
 
-Deprecated upstream attributes are emitted with `#deprecated "..."` so models that reference them produce a TypeSpec compiler warning matching upstream's own deprecation notes.
+Deprecated upstream attributes are emitted with `#deprecated "..."` so models that reference them produce a TypeSpec compiler warning matching upstream's own deprecation notes. The legacy file's consts are all `#deprecated` by construction.
 
 ## 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.

package/generated/otel-keys-legacy.tsp

@@ -0,0 +1,51 @@
+// Hand-maintained companion to otel-keys.gen.tsp — NOT generated. Frozen legacy
+// wire keys that upstream removed from the registries at the 1.41→1.43 bump
+// (the GenAI split: gen_ai.system/prompt/completion/usage.{prompt,completion}_tokens
+// were dropped outright; of the gen_ai.openai.* vendor keys, service_tier ×2 and
+// response.system_fingerprint were renamed to openai.*, seed and
+// request.response_format were removed with no successor).
+//
+// qyl's public contracts still carry these dotted keys on deliberately-deprecated
+// migration fields (`@removed(GenAiVersions.…)` in models/genai.tsp). A wire name
+// is a published contract: it stays frozen even after upstream deletes the key.
+// The values below are verbatim from the last registry that defined them
+// (open-telemetry/semantic-conventions v1.41.0, via the retired
+// @ancplua/typespec-otel-semconv@1.41.0-2 projection).
+//
+// TypeSpec merges namespaces across files, so these consts land in the same
+// Keys.GenAi namespace the generated file populates — consuming models did not
+// change. If a future regeneration re-introduces one of these names, the
+// compiler will error on the duplicate: resolve by deleting it HERE.
+
+namespace ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi {
+  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.output.messages). */
+  #deprecated "Removed upstream; frozen for contract compatibility."
+  const Completion: string = "gen_ai.completion";
+  /** Frozen legacy wire key; removed from semconv (no openai.* successor at 1.43). */
+  #deprecated "Removed upstream; frozen for contract compatibility."
+  const OpenaiRequestResponseFormat: string = "gen_ai.openai.request.response_format";
+  /** Frozen legacy wire key; removed from semconv (no openai.* successor at 1.43). */
+  #deprecated "Removed upstream; frozen for contract compatibility."
+  const OpenaiRequestSeed: string = "gen_ai.openai.request.seed";
+  /** Frozen legacy wire key; renamed upstream to openai.request.service_tier. */
+  #deprecated "Renamed upstream to openai.request.service_tier; frozen for contract compatibility."
+  const OpenaiRequestServiceTier: string = "gen_ai.openai.request.service_tier";
+  /** Frozen legacy wire key; renamed upstream to openai.response.service_tier. */
+  #deprecated "Renamed upstream to openai.response.service_tier; frozen for contract compatibility."
+  const OpenaiResponseServiceTier: string = "gen_ai.openai.response.service_tier";
+  /** Frozen legacy wire key; renamed upstream to openai.response.system_fingerprint. */
+  #deprecated "Renamed upstream to openai.response.system_fingerprint; frozen for contract compatibility."
+  const OpenaiResponseSystemFingerprint: string = "gen_ai.openai.response.system_fingerprint";
+  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.input.messages). */
+  #deprecated "Removed upstream; frozen for contract compatibility."
+  const Prompt: string = "gen_ai.prompt";
+  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.provider.name). */
+  #deprecated "Replaced by gen_ai.provider.name; frozen for contract compatibility."
+  const System: string = "gen_ai.system";
+  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.usage.output_tokens). */
+  #deprecated "Replaced by gen_ai.usage.output_tokens; frozen for contract compatibility."
+  const UsageCompletionTokens: string = "gen_ai.usage.completion_tokens";
+  /** Frozen legacy wire key; removed from semconv (replaced by gen_ai.usage.input_tokens). */
+  #deprecated "Replaced by gen_ai.usage.input_tokens; frozen for contract compatibility."
+  const UsagePromptTokens: string = "gen_ai.usage.prompt_tokens";
+}