@ancplua/qyl-api-schema 11.6.0 → 12.1.0

package/common/telemetry-query.tsp

@@ -0,0 +1,62 @@
+import "./types.tsp";
+using TypeSpec.OpenAPI;
+namespace Qyl.Api.Contracts.Common;
+
+@doc("Opaque project-scoped failure fingerprint issued and verified by the collector.")
+@minLength(1)
+@maxLength(512)
+scalar FailureId extends string;
+
+@doc("Signed self-contained project-scoped verification token issued by the collector.")
+@minLength(1)
+@maxLength(8192)
+scalar VerifyId extends string;
+
+@doc("A comparison operand preserves booleans and numbers rather than coercing them to strings.")
+union MatcherValue { text: string, number: float64, boolean: boolean }
+
+@doc("Supported predicate operators; equality and prefix retain their existing meaning.")
+enum MatcherOp { eq, neq, `in`, prefix, contains, exists, gt, gte, lt, lte }
+
+@doc("Attribute namespace in which the predicate is evaluated.")
+enum MatcherScope { span, resource, log }
+
+@doc("TelemetryMatcher contract.")
+model TelemetryMatcher {
+  @minLength(1)
+  @maxLength(256)
+  key: string;
+  `op`: MatcherOp;
+  value?: MatcherValue;
+  @minItems(1)
+  @maxItems(256)
+  values?: MatcherValue[];
+  scope?: MatcherScope;
+}
+
+@doc("Absolute half-open window applied by the collector.")
+model ToolWindow {
+  @encodedName("application/json", "start_time")
+  startTime: utcDateTime;
+  @encodedName("application/json", "end_time")
+  endTime: utcDateTime;
+}
+
+@doc("Scan coverage; unknown counts are null, never an invented zero.")
+model ToolCoverage {
+  examined: Count | null;
+  matched: Count | null;
+  returned: Count | null;
+  truncated: boolean;
+  @encodedName("application/json", "scan_complete")
+  scanComplete: boolean;
+  @encodedName("application/json", "as_of")
+  asOf: utcDateTime;
+}
+
+@doc("ToolReadContext contract.")
+model ToolReadContext {
+  window: ToolWindow;
+  coverage: ToolCoverage;
+}
+

package/common/types.tsp

@@ -159,10 +159,18 @@ scalar Temperature extends float64;
 @maxLength(64)
 scalar Sha256Hash extends string;
 
+@doc("""
+  Opaque pagination cursor. Pass the `next_cursor` of one page to receive the
+  next page of the same query. Its content is not part of the contract and
+  must not be parsed or built by a client.
+  """)
+scalar Cursor extends string;
+
 // The revision is a canonical digest of the semantic OpenAPI projection and the
 // exported telemetry-key projection, not a package version. Presentation-only
-// fields do not change it. Truncated to 16 hex characters because it is compared
-// for equality, never used as a security boundary.
+// fields and the release version stamped into `info.version` do not change it.
+// Truncated to 16 hex characters because it is compared for equality, never used
+// as a security boundary.
 @doc("Deterministic revision of the generated API contract: 'sha256:' followed by the first 16 hex characters of its canonical semantic digest.")
 @pattern("^sha256:[a-f0-9]{16}$")
 @minLength(23)