@ancplua/qyl-api-schema 2.1.0 → 4.0.0

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

@@ -356,6 +356,12 @@ export declare const McpDataModeValues: {
     readonly demo: "demo";
 };
 export type McpDataMode = typeof McpDataModeValues[keyof typeof McpDataModeValues];
+export declare const CiPhaseStatusValues: {
+    readonly ok: "ok";
+    readonly error: "error";
+    readonly unset: "unset";
+};
+export type CiPhaseStatus = typeof CiPhaseStatusValues[keyof typeof CiPhaseStatusValues];
 export declare const FetchTelemetryViewValues: {
     readonly traces: "traces";
     readonly trace: "trace";
@@ -531,8 +537,8 @@ export interface Span {
     "trace_state"?: string;
     "name": string;
     "kind": SpanKind;
-    "start_time_unix_nano": number;
-    "end_time_unix_nano": number;
+    "start_time_unix_nano": string;
+    "end_time_unix_nano": string;
     "attributes"?: Attribute[];
     "dropped_attributes_count"?: number;
     "events"?: SpanEvent[];
@@ -546,7 +552,7 @@ export interface Span {
 }
 export interface SpanEvent {
     "name": string;
-    "time_unix_nano": number;
+    "time_unix_nano": string;
     "attributes"?: Attribute[];
     "dropped_attributes_count"?: number;
 }
@@ -566,7 +572,7 @@ export interface TraceSummary {
     "trace_id": TraceId;
     "root_span"?: Span;
     "span_count": number;
-    "duration_ns": number;
+    "duration_ns": string;
     "start_time": string;
     "end_time": string;
     "services": string[];
@@ -582,8 +588,8 @@ export interface SpanQueryFilters {
     "kind"?: SpanKind;
     "service_name"?: string;
     "status_code"?: SpanStatusCode;
-    "min_duration_ns"?: number;
-    "max_duration_ns"?: number;
+    "min_duration_ns"?: string;
+    "max_duration_ns"?: string;
     "attribute"?: string;
 }
 export interface SpanStats {
@@ -591,11 +597,11 @@ export interface SpanStats {
     "error_count": number;
     "error_rate": number;
     "avg_duration_ns": number;
-    "p50_duration_ns": number;
-    "p90_duration_ns": number;
-    "p99_duration_ns": number;
-    "min_duration_ns": number;
-    "max_duration_ns": number;
+    "p50_duration_ns": string;
+    "p90_duration_ns": string;
+    "p99_duration_ns": string;
+    "min_duration_ns": string;
+    "max_duration_ns": string;
     "throughput_per_second": number;
     "by_service"?: SpanStatsByDimension[];
     "by_operation"?: SpanStatsByDimension[];
@@ -607,8 +613,8 @@ export interface SpanStatsByDimension {
     "error_rate": number;
 }
 export interface LogRecord {
-    "time_unix_nano": number;
-    "observed_time_unix_nano": number;
+    "time_unix_nano": string;
+    "observed_time_unix_nano": string;
     "severity_number": SeverityNumber;
     "severity_text"?: SeverityText;
     "body": LogBody;
@@ -703,6 +709,7 @@ export interface HealthReport {
     "status": HealthStatus;
     "total_duration_ms": number;
     "entries": Record<string, HealthCheckEntry>;
+    "contract_revision": string;
 }
 export interface RunnerResourceState {
     "name": string;
@@ -1305,6 +1312,31 @@ export interface SearchLogsOutput {
     "logs": LogRecord[];
     "mode": McpDataMode;
 }
+export interface CiLogInput {
+    "run_id"?: SessionId;
+    "limit"?: number;
+}
+export interface CiRunSummary {
+    "run_id": SessionId;
+    "state": SessionState;
+    "start_time": string;
+    "duration_ms"?: number;
+    "error_count": number;
+    "services": string[];
+}
+export interface CiPhase {
+    "leg": string;
+    "phase": string;
+    "status": CiPhaseStatus;
+    "duration_ms": number;
+    "message"?: string;
+}
+export interface CiLogOutput {
+    "runs"?: CiRunSummary[];
+    "run_id"?: SessionId;
+    "phases"?: CiPhase[];
+    "mode": McpDataMode;
+}
 export interface FetchTelemetryInput {
     "view": FetchTelemetryView;
     "trace_id"?: TraceId;
@@ -1354,3 +1386,5 @@ export interface CursorPageSessionEntity {
     "prev_cursor"?: string;
     "has_more": boolean;
 }
+/** Revision of the API contract these types were emitted from; compare against HealthReport.contract_revision. */
+export declare const CONTRACT_REVISION: string;

package/generated/ts-runtime/api.js

@@ -284,9 +284,17 @@ export const McpDataModeValues = {
     "live": "live",
     "demo": "demo",
 };
+export const CiPhaseStatusValues = {
+    "ok": "ok",
+    "error": "error",
+    "unset": "unset",
+};
 export const FetchTelemetryViewValues = {
     "traces": "traces",
     "trace": "trace",
     "logs": "logs",
     "mcpStats": "mcp_stats",
 };
+// --- 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:9ba787d0bd3269a9";

package/models/health.tsp

@@ -1,3 +1,7 @@
+import "../common/types.tsp";
+
+using Qyl.Api.Contracts.Common;
+
 namespace Qyl.Api.Contracts.Health;
 
 @doc("Health state reported by a qyl-managed process.")
@@ -21,4 +25,12 @@ model HealthReport {
   @encodedName("application/json", "total_duration_ms")
   totalDurationMs: float64;
   entries: Record<HealthCheckEntry>;
+
+  // The meta surface of the contract loop: first-party clients compare this to
+  // the revision baked into their own generated artifacts and refuse to run on
+  // a mismatch, so a redeployed collector cannot silently serve a contract its
+  // clients were not generated from.
+  @doc("Revision of the API contract this process serves, for the client-side startup handshake.")
+  @encodedName("application/json", "contract_revision")
+  contractRevision: ContractRevision;
 }

package/models/mcp-tools.tsp

@@ -117,6 +117,76 @@ model SearchLogsOutput {
   mode: McpDataMode;
 }
 
+@doc("Outcome of one CI phase span, projected from its OpenTelemetry span status.")
+enum CiPhaseStatus {
+  ok: "ok",
+  error: "error",
+  unset: "unset",
+}
+
+@doc("Input for ci_log.")
+model CiLogInput {
+  @doc("Session id of one CI run for a per-leg phase breakdown; omit to list recent runs.")
+  @encodedName("application/json", "run_id")
+  runId?: SessionId;
+
+  @doc("Maximum CI runs to list.")
+  @minValue(1)
+  @maxValue(50)
+  limit?: int32 = 10;
+}
+
+@doc("One CI run, summarized from the session its telemetry is grouped under.")
+model CiRunSummary {
+  @encodedName("application/json", "run_id")
+  runId: SessionId;
+
+  state: SessionState;
+
+  @encodedName("application/json", "start_time")
+  startTime: utcDateTime;
+
+  @encodedName("application/json", "duration_ms")
+  durationMs?: DurationMs;
+
+  @doc("Spans in the run that ended with an error status.")
+  @encodedName("application/json", "error_count")
+  @minValue(0)
+  errorCount: int32;
+
+  @doc("Service names observed in the run, at least one of which is CI-emitted.")
+  services: string[];
+}
+
+@doc("One phase span of a CI run, attributed to the leg that executed it.")
+model CiPhase {
+  @doc("Value of the span's ci.leg attribute, falling back to its service name.")
+  leg: string;
+
+  @doc("Span name, which the CI emitter convention sets to the phase name.")
+  phase: string;
+
+  status: CiPhaseStatus;
+
+  @encodedName("application/json", "duration_ms")
+  durationMs: DurationMs;
+
+  @doc("Span status message, present on a failed phase.")
+  message?: string;
+}
+
+@doc("Structured output for ci_log: recent runs, or one run's phases.")
+model CiLogOutput {
+  runs?: CiRunSummary[];
+
+  @encodedName("application/json", "run_id")
+  runId?: SessionId;
+
+  phases?: CiPhase[];
+
+  mode: McpDataMode;
+}
+
 @doc("Input for the app-only fetch_telemetry tool.")
 model FetchTelemetryInput {
   view: FetchTelemetryView;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "2.1.0",
+  "version": "4.0.0",
   "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": {
@@ -85,9 +85,10 @@
     "build:emitters": "tsc -p emitters/csharp && tsc -p emitters/ts-types && tsc -p emitters/qyl-lint",
     "build:ts-runtime": "tsc -p tsconfig.contracts.json",
     "build:json-schema": "node scripts/openapi-to-json-schema.mjs",
+    "emit:contract-revision": "node scripts/emit-contract-revision.mjs",
     "prepare": "npm run build:emitters",
     "prepack": "npm run compile",
-    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run build:json-schema && npm run build:ts-runtime",
+    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run emit:contract-revision && npm run build:json-schema && npm run build:ts-runtime",
     "watch": "tsp compile main.tsp --watch",
     "format": "tsp format **/*.tsp",
     "lint": "npm run build:emitters && tsp compile main.tsp --no-emit --warn-as-error",
@@ -98,7 +99,7 @@
   },
   "peerDependencies": {
     "@typespec/compiler": "^1.13.0 || >=1.13.0-dev.0",
-    "@typespec/events": "^0.83.0",
+    "@typespec/events": "^0.83.0 || ^0.84.0",
     "@typespec/http": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
     "@typespec/openapi3": "^1.13.0",
@@ -128,13 +129,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": "24.13.3",
+    "@types/node": "26.1.1",
     "@typespec/compiler": "1.14.0",
-    "@typespec/events": "0.83.0",
-    "@typespec/http": "1.13.0",
-    "@typespec/openapi": "1.13.0",
-    "@typespec/openapi3": "1.13.0",
-    "@typespec/sse": "0.83.0",
+    "@typespec/events": "0.84.0",
+    "@typespec/http": "1.14.0",
+    "@typespec/openapi": "1.14.0",
+    "@typespec/openapi3": "1.14.0",
+    "@typespec/sse": "0.84.0",
     "ajv": "8.20.0",
     "typescript": "7.0.2"
   }