@ancplua/qyl-api-schema 9.0.0 → 10.0.1

package/README.md

@@ -4,20 +4,16 @@ The TypeSpec source of truth for Qyl's client-visible product API. This reposito
 emits the public schema and contract artifacts; it does not implement the server,
 storage engine, or OTLP receiver.
 
-Qyl stores and exposes traces and logs. Metrics are accepted and discarded only by
-the collector's OTLP wire-compatibility handlers, so this product contract exposes
-no metric DTOs or routes. Profiles are not supported.
+Qyl stores and exposes traces, logs, and metrics. The metric surface is read-only.
+`GET /api/v1/metrics` lists the metric descriptors recorded for a project,
+`GET /api/v1/metrics/{metric_name}/series` lists the distinct attribute streams
+under one metric name, and `GET /api/v1/metrics/{metric_name}/query` aggregates one
+metric over a time range into buckets. Metric points are written over OTLP, which
+this contract does not describe. Profiles are not supported.
 
 ## Contract pipeline
 
 ```text
-Qyl.Telemetry.SemanticConventions
-        |
-        | generated semantic key projection
-        v
-generated/otel-keys.gen.tsp
-        |
-        v
 authored Qyl TypeSpec
         |
         +----> OpenAPI ----> bundled JSON Schema
@@ -25,9 +21,10 @@ authored Qyl TypeSpec
         +----> generated TypeScript contracts
 ```
 
-The semantic-key projection is generated from the sibling conventions repository's
-pinned core and GenAI registries. It supplies typed names for telemetry attributes;
 Qyl domain models, routes, responses, stream events, and errors are authored here.
+The OTel-compatible models target schema `https://opentelemetry.io/schemas/1.44.0`;
+attribute keys cross the wire as open string maps, so this contract carries no
+enumeration of the OpenTelemetry attribute registry.
 
 ## Boundary
 
@@ -91,39 +88,9 @@ contract instead of discovering the mismatch one malformed field at a time. Read
 current value from a running collector or the generated artifacts; it is derived, never
 hand-maintained.
 
-## Develop
-
-Development and CI use Node.js 24 LTS. Published npm artifacts support maintained
-Node.js releases from 22 onward.
-
-```bash
-npm ci
-npm run lint
-npm run lint:public
-npm run compile
-./build.sh Check
-```
-
-Important generated outputs include:
-
-- `generated/openapi/qyl.openapi.json`
-- `generated/json-schema/qyl-api-schema.json`
-- `generated/contracts/**/*.cs`
-- `generated/ts-types/**`
-
-Generated files are not editing surfaces. OpenAPI comes from the official TypeSpec
-emitter; the bundled JSON Schema is a deterministic projection of its component
-schemas and exposes inline route bodies as stable
-`Operations.<operationId>.Request` and
-`Operations.<operationId>.Response.<status>` definitions. Both artifacts preserve
-the same wire names. Change TypeSpec or the owning generator and regenerate.
-
-## Publish
+## Contributing
 
-GitHub Actions publishes both registries through OIDC trusted publishing. A release
-tag supplies one version for npm and NuGet. The workflow validates and packs first,
-publishes in an ordered restartable sequence, waits for indexed artifacts, and then
-smokes clean consumers. No long-lived npm or NuGet token is stored.
+How to build, lint, regenerate and publish is in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/common/types.tsp

@@ -2,7 +2,7 @@
 // qyl common types and scalars
 // =============================================================================
 // Foundational types used across qyl API contracts and OTel-compatible models.
-// OpenTelemetry registry provenance is owned by generated/otel-keys.gen.tsp.
+// The contract targets OpenTelemetry semantic conventions schema https://opentelemetry.io/schemas/1.44.0.
 // =============================================================================
 
 import "@typespec/openapi";
@@ -14,16 +14,12 @@ namespace Qyl.Api.Contracts.Common;
 // =============================================================================
 // Identifier Scalars - Strongly Typed IDs
 // =============================================================================
-// The semantic-conventions pin lives in the generated keys header and is
-// machine-checked; a hand-maintained enum of upstream releases would only drift.
 
 @doc("Unique trace identifier (32 lowercase hex characters)")
 @pattern("^[a-f0-9]{32}$")
 @minLength(32)
 @maxLength(32)
 @example("0af7651916cd43dd8448eb211c80319c")
-@TypeSpec.OpenAPI.extension("x-csharp-struct", true)
-@TypeSpec.OpenAPI.extension("x-csharp-type", "TraceId")
 scalar TraceId extends string;
 
 @doc("Unique span identifier (16 lowercase hex characters)")
@@ -31,8 +27,6 @@ scalar TraceId extends string;
 @minLength(16)
 @maxLength(16)
 @example("b7ad6b7169203331")
-@TypeSpec.OpenAPI.extension("x-csharp-struct", true)
-@TypeSpec.OpenAPI.extension("x-csharp-type", "SpanId")
 scalar SpanId extends string;
 
 @doc("W3C Trace Context traceparent header format")
@@ -47,8 +41,6 @@ scalar TraceState extends string;
 @doc("Unique session identifier")
 @minLength(1)
 @maxLength(128)
-@TypeSpec.OpenAPI.extension("x-csharp-struct", true)
-@TypeSpec.OpenAPI.extension("x-csharp-type", "SessionId")
 scalar SessionId extends string;
 
 @doc("User identifier (pseudonymized for privacy)")

package/generated/json-schema/qyl-api-schema.json

@@ -911,9 +911,7 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 128,
-      "description": "Unique session identifier",
-      "x-csharp-type": "SessionId",
-      "x-csharp-struct": true
+      "description": "Unique session identifier"
     },
     "Common.Sha256Hash": {
       "type": "string",
@@ -930,9 +928,7 @@
       "description": "Unique span identifier (16 lowercase hex characters)",
       "examples": [
         "b7ad6b7169203331"
-      ],
-      "x-csharp-type": "SpanId",
-      "x-csharp-struct": true
+      ]
     },
     "Common.Temperature": {
       "type": "number",
@@ -962,9 +958,7 @@
       "description": "Unique trace identifier (32 lowercase hex characters)",
       "examples": [
         "0af7651916cd43dd8448eb211c80319c"
-      ],
-      "x-csharp-type": "TraceId",
-      "x-csharp-struct": true
+      ]
     },
     "Common.TraceParent": {
       "type": "string",

package/generated/openapi/qyl.openapi.json

@@ -13892,9 +13892,7 @@
         "type": "string",
         "minLength": 1,
         "maxLength": 128,
-        "description": "Unique session identifier",
-        "x-csharp-type": "SessionId",
-        "x-csharp-struct": true
+        "description": "Unique session identifier"
       },
       "Common.Sha256Hash": {
         "type": "string",
@@ -13911,9 +13909,7 @@
         "description": "Unique span identifier (16 lowercase hex characters)",
         "examples": [
           "b7ad6b7169203331"
-        ],
-        "x-csharp-type": "SpanId",
-        "x-csharp-struct": true
+        ]
       },
       "Common.Temperature": {
         "type": "number",
@@ -13943,9 +13939,7 @@
         "description": "Unique trace identifier (32 lowercase hex characters)",
         "examples": [
           "0af7651916cd43dd8448eb211c80319c"
-        ],
-        "x-csharp-type": "TraceId",
-        "x-csharp-struct": true
+        ]
       },
       "Common.TraceParent": {
         "type": "string",

package/generated/ts-runtime/api.js

@@ -320,4 +320,4 @@ export const FetchTelemetryViewValues = {
 };
 // --- contract revision (scripts/emit-contract-revision.mjs) ---
 /** Revision of the API contract these types were emitted from; compare against HealthReport.contract_revision. */
-export const CONTRACT_REVISION = "sha256:d1c859393b628164";
+export const CONTRACT_REVISION = "sha256:cd69d9c37a41916c";

package/index.tsp

@@ -6,8 +6,6 @@ import "@typespec/http";
 import "@typespec/openapi";
 import "@typespec/sse";
 
-import "./generated/otel-keys.gen.tsp";
-
 import "./common/types.tsp";
 import "./common/errors.tsp";
 import "./common/pagination.tsp";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "9.0.0",
+  "version": "10.0.1",
   "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": {
@@ -32,10 +32,6 @@
       "typespec": "./otel/otel-conventions.tsp",
       "default": "./otel/otel-conventions.tsp"
     },
-    "./generated/otel-keys": {
-      "typespec": "./generated/otel-keys.gen.tsp",
-      "default": "./generated/otel-keys.gen.tsp"
-    },
     "./types": {
       "types": "./generated/ts-runtime/api.d.ts",
       "import": "./generated/ts-runtime/api.js",
@@ -72,7 +68,6 @@
     "otel/otel-conventions.tsp",
     "otel/resource.tsp",
     "otel/span.tsp",
-    "generated/otel-keys.gen.tsp",
     "generated/ts-runtime/api.d.ts",
     "generated/ts-runtime/api.js",
     "generated/openapi/qyl.openapi.json",
@@ -107,11 +102,11 @@
   },
   "peerDependencies": {
     "@typespec/compiler": "^1.13.0 || >=1.13.0-dev.0",
-    "@typespec/events": "^0.83.0 || ^0.84.0 || ^0.85.0",
+    "@typespec/events": "^0.83.0 || ^0.84.0 || ^0.85.0 || ^0.86.0",
     "@typespec/http": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
     "@typespec/openapi3": "^1.13.0",
-    "@typespec/sse": ">=0.83.0 <0.86.0",
+    "@typespec/sse": ">=0.83.0 <0.87.0",
     "zod": ">=4.5.0 <5"
   },
   "peerDependenciesMeta": {
@@ -141,13 +136,13 @@
     "@ancplua/typespec-emit-csharp": "file:./emitters/csharp",
     "@ancplua/typespec-emit-ts-types": "file:./emitters/ts-types",
     "@ancplua/typespec-qyl-lint": "file:./emitters/qyl-lint",
-    "@types/node": "26.3.0",
-    "@typespec/compiler": "1.15.0",
-    "@typespec/events": "0.85.0",
-    "@typespec/http": "1.15.0",
-    "@typespec/openapi": "1.15.0",
-    "@typespec/openapi3": "1.15.0",
-    "@typespec/sse": "0.85.0",
+    "@types/node": "26.4.1",
+    "@typespec/compiler": "1.16.0",
+    "@typespec/events": "0.86.0",
+    "@typespec/http": "1.16.0",
+    "@typespec/openapi": "1.16.0",
+    "@typespec/openapi3": "1.16.0",
+    "@typespec/sse": "0.86.0",
     "ajv": "8.20.0",
     "typescript": "7.0.2",
     "zod": "4.5.4"