@ancplua/qyl-api-schema 8.0.0 → 10.0.0

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
 

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,8 +14,6 @@ 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}$")