@ancplua/qyl-api-schema 0.5.12 → 0.5.14

package/api/routes.tsp

@@ -183,7 +183,9 @@ interface GenAiEtlAuditApi {
   @get
   report(
     ...ProjectScopeHeader,
+    @doc("Optional audit-period start. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.")
     @query startTime?: utcDateTime,
+    @doc("Optional audit-period end. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.")
     @query endTime?: utcDateTime,
     @query @minValue(1) @maxValue(100) limit?: int32 = 25,
   ): GenAiEtlAuditReport | ValidationError | UnauthorizedError | InternalServerError;
@@ -192,7 +194,9 @@ interface GenAiEtlAuditApi {
   @route("/evaluate")
   evaluate(
     ...ProjectScopeHeader,
+    @doc("Optional audit-period start. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.")
     @query startTime?: utcDateTime,
+    @doc("Optional audit-period end. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.")
     @query endTime?: utcDateTime,
     @body request: GenAiEtlAuditEvaluationRequest,
   ): GenAiEtlAuditEvaluationResponse | ValidationError | UnauthorizedError | InternalServerError;

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

@@ -848,7 +848,6 @@
         "cluster_id",
         "workflow_key",
         "service_name",
-        "span_name",
         "output_contract",
         "task_family",
         "call_count",
@@ -863,7 +862,7 @@
         "p95_latency_ms",
         "cost_attribution",
         "candidate_path",
-        "validation_metric",
+        "validation_metrics",
         "residual_path",
         "evidence_signals",
         "missing_evidence",
@@ -876,13 +875,14 @@
         },
         "workflow_key": {
           "type": "string",
-          "description": "Privacy-safe workflow identity used to group repeated calls."
+          "description": "Privacy-safe derived grouping identity used to group repeated calls."
         },
         "service_name": {
           "type": "string"
         },
         "span_name": {
-          "type": "string"
+          "type": "string",
+          "description": "Present only when an upstream source proves or canonicalizes a low-cardinality, privacy-safe span name."
         },
         "operation_name": {
           "type": "string"
@@ -970,8 +970,13 @@
         "candidate_path": {
           "$ref": "#/$defs/Cost.GenAiEtlCandidatePath"
         },
-        "validation_metric": {
-          "$ref": "#/$defs/Cost.GenAiEtlValidationMetric"
+        "validation_metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Cost.GenAiEtlValidationMetric"
+          },
+          "minItems": 1,
+          "description": "Task-specific metrics required to falsify the proposed replacement."
         },
         "residual_path": {
           "$ref": "#/$defs/Cost.GenAiEtlResidualPath"
@@ -1389,6 +1394,9 @@
       "enum": [
         "accuracy",
         "macro_f1",
+        "calibration_error",
+        "span_precision",
+        "span_recall",
         "span_f1",
         "field_exact_match",
         "schema_validity",
@@ -1401,7 +1409,7 @@
         "task_success",
         "unavailable"
       ],
-      "description": "Task-specific metric that can falsify a proposed replacement."
+      "description": "Task-specific metrics that can falsify a proposed replacement."
     },
     "Cost.ProviderCostAttribution": {
       "type": "string",
@@ -1514,6 +1522,7 @@
       "type": "string",
       "enum": [
         "unconfigured",
+        "pending",
         "current",
         "stale",
         "sync_failed",

package/generated/openapi/qyl.openapi.json

@@ -76,6 +76,7 @@
             "name": "startTime",
             "in": "query",
             "required": false,
+            "description": "Optional audit-period start. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.",
             "schema": {
               "type": "string",
               "format": "date-time"
@@ -86,6 +87,7 @@
             "name": "endTime",
             "in": "query",
             "required": false,
+            "description": "Optional audit-period end. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.",
             "schema": {
               "type": "string",
               "format": "date-time"
@@ -224,6 +226,7 @@
             "name": "startTime",
             "in": "query",
             "required": false,
+            "description": "Optional audit-period start. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.",
             "schema": {
               "type": "string",
               "format": "date-time"
@@ -234,6 +237,7 @@
             "name": "endTime",
             "in": "query",
             "required": false,
+            "description": "Optional audit-period end. Omitted dates select the previous 30 completed UTC days; an explicit range may not exceed 180 days.",
             "schema": {
               "type": "string",
               "format": "date-time"
@@ -4844,7 +4848,6 @@
           "cluster_id",
           "workflow_key",
           "service_name",
-          "span_name",
           "output_contract",
           "task_family",
           "call_count",
@@ -4859,7 +4862,7 @@
           "p95_latency_ms",
           "cost_attribution",
           "candidate_path",
-          "validation_metric",
+          "validation_metrics",
           "residual_path",
           "evidence_signals",
           "missing_evidence",
@@ -4872,13 +4875,14 @@
           },
           "workflow_key": {
             "type": "string",
-            "description": "Privacy-safe workflow identity used to group repeated calls."
+            "description": "Privacy-safe derived grouping identity used to group repeated calls."
           },
           "service_name": {
             "type": "string"
           },
           "span_name": {
-            "type": "string"
+            "type": "string",
+            "description": "Present only when an upstream source proves or canonicalizes a low-cardinality, privacy-safe span name."
           },
           "operation_name": {
             "type": "string"
@@ -4966,8 +4970,13 @@
           "candidate_path": {
             "$ref": "#/components/schemas/Cost.GenAiEtlCandidatePath"
           },
-          "validation_metric": {
-            "$ref": "#/components/schemas/Cost.GenAiEtlValidationMetric"
+          "validation_metrics": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Cost.GenAiEtlValidationMetric"
+            },
+            "minItems": 1,
+            "description": "Task-specific metrics required to falsify the proposed replacement."
           },
           "residual_path": {
             "$ref": "#/components/schemas/Cost.GenAiEtlResidualPath"
@@ -5385,6 +5394,9 @@
         "enum": [
           "accuracy",
           "macro_f1",
+          "calibration_error",
+          "span_precision",
+          "span_recall",
           "span_f1",
           "field_exact_match",
           "schema_validity",
@@ -5397,7 +5409,7 @@
           "task_success",
           "unavailable"
         ],
-        "description": "Task-specific metric that can falsify a proposed replacement."
+        "description": "Task-specific metrics that can falsify a proposed replacement."
       },
       "Cost.ProviderCostAttribution": {
         "type": "string",
@@ -5510,6 +5522,7 @@
         "type": "string",
         "enum": [
           "unconfigured",
+          "pending",
           "current",
           "stale",
           "sync_failed",

package/generated/ts-runtime/api.d.ts

@@ -296,6 +296,7 @@ export declare const ProviderCostSourceKindValues: {
 export type ProviderCostSourceKind = typeof ProviderCostSourceKindValues[keyof typeof ProviderCostSourceKindValues];
 export declare const ProviderCostSourceStatusValues: {
     readonly unconfigured: "unconfigured";
+    readonly pending: "pending";
     readonly current: "current";
     readonly stale: "stale";
     readonly syncFailed: "sync_failed";
@@ -362,6 +363,9 @@ export type GenAiEtlCandidatePath = typeof GenAiEtlCandidatePathValues[keyof typ
 export declare const GenAiEtlValidationMetricValues: {
     readonly accuracy: "accuracy";
     readonly macroF1: "macro_f1";
+    readonly calibrationError: "calibration_error";
+    readonly spanPrecision: "span_precision";
+    readonly spanRecall: "span_recall";
     readonly spanF1: "span_f1";
     readonly fieldExactMatch: "field_exact_match";
     readonly schemaValidity: "schema_validity";
@@ -1077,7 +1081,7 @@ export interface GenAiEtlAuditCluster {
     "cluster_id": string;
     "workflow_key": string;
     "service_name": string;
-    "span_name": string;
+    "span_name"?: string;
     "operation_name"?: string;
     "provider"?: string;
     "model"?: string;
@@ -1100,7 +1104,7 @@ export interface GenAiEtlAuditCluster {
     "measurable_coverage"?: number;
     "safe_deferral_coverage"?: number;
     "candidate_path": GenAiEtlCandidatePath;
-    "validation_metric": GenAiEtlValidationMetric;
+    "validation_metrics": GenAiEtlValidationMetric[];
     "residual_path": GenAiEtlResidualPath;
     "evidence_signals": GenAiEtlEvidenceSignal[];
     "missing_evidence": GenAiEtlEvidenceSignal[];

package/generated/ts-runtime/api.js

@@ -254,6 +254,7 @@ export const ProviderCostSourceKindValues = {
 };
 export const ProviderCostSourceStatusValues = {
     "unconfigured": "unconfigured",
+    "pending": "pending",
     "current": "current",
     "stale": "stale",
     "syncFailed": "sync_failed",
@@ -313,6 +314,9 @@ export const GenAiEtlCandidatePathValues = {
 export const GenAiEtlValidationMetricValues = {
     "accuracy": "accuracy",
     "macroF1": "macro_f1",
+    "calibrationError": "calibration_error",
+    "spanPrecision": "span_precision",
+    "spanRecall": "span_recall",
     "spanF1": "span_f1",
     "fieldExactMatch": "field_exact_match",
     "schemaValidity": "schema_validity",

package/models/cost-etl-audit.tsp

@@ -24,6 +24,9 @@ enum ProviderCostSourceStatus {
   @doc("The source has no configured provider credential or cloud identity.")
   unconfigured: "unconfigured",
 
+  @doc("A provider credential or cloud identity is configured, but no fetch has completed yet.")
+  pending: "pending",
+
   @doc("The most recent provider fetch completed inside its freshness window.")
   current: "current",
 
@@ -140,10 +143,13 @@ enum GenAiEtlCandidatePath {
   insufficientEvidence: "insufficient_evidence",
 }
 
-@doc("Task-specific metric that can falsify a proposed replacement.")
+@doc("Task-specific metrics that can falsify a proposed replacement.")
 enum GenAiEtlValidationMetric {
   accuracy: "accuracy",
   macroF1: "macro_f1",
+  calibrationError: "calibration_error",
+  spanPrecision: "span_precision",
+  spanRecall: "span_recall",
   spanF1: "span_f1",
   fieldExactMatch: "field_exact_match",
   schemaValidity: "schema_validity",
@@ -217,15 +223,16 @@ model GenAiEtlAuditCluster {
   @encodedName("application/json", "cluster_id")
   clusterId: string;
 
-  @doc("Privacy-safe workflow identity used to group repeated calls.")
+  @doc("Privacy-safe derived grouping identity used to group repeated calls.")
   @encodedName("application/json", "workflow_key")
   workflowKey: string;
 
   @encodedName("application/json", "service_name")
   serviceName: string;
 
+  @doc("Present only when an upstream source proves or canonicalizes a low-cardinality, privacy-safe span name.")
   @encodedName("application/json", "span_name")
-  spanName: string;
+  spanName?: string;
 
   @encodedName("application/json", "operation_name")
   operationName?: string;
@@ -296,8 +303,10 @@ model GenAiEtlAuditCluster {
   @encodedName("application/json", "candidate_path")
   candidatePath: GenAiEtlCandidatePath;
 
-  @encodedName("application/json", "validation_metric")
-  validationMetric: GenAiEtlValidationMetric;
+  @doc("Task-specific metrics required to falsify the proposed replacement.")
+  @encodedName("application/json", "validation_metrics")
+  @minItems(1)
+  validationMetrics: GenAiEtlValidationMetric[];
 
   @encodedName("application/json", "residual_path")
   residualPath: GenAiEtlResidualPath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "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": {