@ancplua/qyl-api-schema 0.2.0

package/index.tsp

@@ -0,0 +1,55 @@
+// =============================================================================
+// @ancplua/qyl-api-schema — published entry point
+// =============================================================================
+// Consumer-facing barrel. Mirrors main.tsp minus local emit routing.
+// The local emitters depend on `file:` packages
+// (@ancplua/typespec-emit-*) which are not shipped to registry consumers and
+// would break TypeSpec import resolution.
+//
+// Use main.tsp inside this repo for local `tsp compile`; downstream consumers
+// reach the public surface through this file via the `.` export.
+// =============================================================================
+
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi";
+import "@typespec/openapi3";
+import "@typespec/versioning";
+import "@typespec/sse";
+import "@typespec/events";
+
+import "./generated/otel-keys.gen.tsp";
+
+import "./common/types.tsp";
+import "./common/errors.tsp";
+import "./common/pagination.tsp";
+
+import "./otel/enums.tsp";
+import "./otel/resource.tsp";
+import "./otel/span.tsp";
+import "./otel/logs.tsp";
+import "./otel/metrics.tsp";
+import "./otel/profiles.tsp";
+
+import "./models/genai.tsp";
+import "./models/http.tsp";
+import "./models/rpc.tsp";
+import "./models/messaging.tsp";
+import "./models/db.tsp";
+import "./models/session.tsp";
+import "./models/otel-config.tsp";
+import "./models/log.tsp";
+import "./models/error.tsp";
+import "./models/test.tsp";
+import "./models/deployment.tsp";
+import "./models/system.tsp";
+import "./models/identity.tsp";
+import "./models/control-graph.tsp";
+
+import "./api/routes.tsp";
+import "./api/streaming.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.Rest;
+using TypeSpec.OpenAPI;
+using TypeSpec.Versioning;

package/intelligence/causal-rules.tsp

@@ -0,0 +1,34 @@
+// =============================================================================
+// ANcpLua v2.0 - Causal Rules
+// =============================================================================
+// Directed relationship between two diagnostic patterns: if cause is observed,
+// effect is likely. Causal rules build a directed graph. Given matched patterns,
+// the engine traverses causal edges to identify root causes (patterns with no
+// incoming causal edges).
+// =============================================================================
+
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Qyl.Api.Contracts.Intelligence;
+
+@doc("Directed causal relationship between two diagnostic patterns")
+model CausalRule {
+  @doc("Unique rule identifier")
+  id: string;
+
+  @doc("ID of the cause DiagnosticPattern")
+  causePattern: string;
+
+  @doc("ID of the effect DiagnosticPattern")
+  effectPattern: string;
+
+  @doc("Causal confidence (0.0-1.0)")
+  @minValue(0.0)
+  @maxValue(1.0)
+  strength: float64;
+
+  @doc("Time window for correlation (e.g. 5m, 1h)")
+  temporalWindow?: string;
+}

package/intelligence/diagnostic-patterns.tsp

@@ -0,0 +1,54 @@
+// =============================================================================
+// ANcpLua v2.0 - Diagnostic Patterns
+// =============================================================================
+// A named combination of signals that identifies a known failure mode.
+// All signals in a pattern must match (conjunction). Multiple patterns can
+// match the same telemetry — the engine returns all matches ranked by confidence.
+// =============================================================================
+
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Qyl.Api.Contracts.Intelligence;
+
+@doc("Classification category for diagnostic patterns")
+enum PatternCategory {
+  @doc("Exception and error patterns")
+  error: "error",
+
+  @doc("Performance degradation")
+  latency: "latency",
+
+  @doc("Token/cost anomalies")
+  cost: "cost",
+
+  @doc("Service health patterns")
+  availability: "availability",
+
+  @doc("GenAI-specific failure modes")
+  genai: "genai",
+
+  @doc("Database and storage patterns")
+  data: "data",
+}
+
+@doc("Named combination of signals identifying a known failure mode")
+model DiagnosticPattern {
+  @doc("Unique pattern identifier (e.g. genai_rate_limit)")
+  id: string;
+
+  @doc("Pattern classification")
+  category: PatternCategory;
+
+  @doc("Signals that must all match (conjunction)")
+  signals: Signal[];
+
+  @doc("What this pattern means diagnostically")
+  hypothesis: string;
+
+  @doc("Base confidence weight (0.0-1.0)")
+  @minValue(0.0)
+  @maxValue(1.0)
+  confidence: float64;
+}

package/intelligence/investigation-strategies.tsp

@@ -0,0 +1,37 @@
+// =============================================================================
+// ANcpLua v2.0 - Investigation Strategies
+// =============================================================================
+// A deterministic sequence of steps to investigate a matched pattern.
+// The LLM does not invent investigation paths — it selects from known
+// strategies and interprets results.
+// =============================================================================
+
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Qyl.Api.Contracts.Intelligence;
+
+@doc("Single step in an investigation strategy")
+model InvestigationStep {
+  @doc("What to do (e.g. query_traces, get_code_location, compare_deployments)")
+  action: string;
+
+  @doc("Query template or tool name")
+  query: string;
+
+  @doc("Human-readable explanation of this step")
+  description: string;
+}
+
+@doc("Deterministic investigation sequence triggered by a matched pattern")
+model InvestigationStrategy {
+  @doc("Unique strategy identifier")
+  id: string;
+
+  @doc("Trigger — pattern ID or category:X for category-wide triggers")
+  triggerPattern: string;
+
+  @doc("Ordered investigation steps")
+  steps: InvestigationStep[];
+}

package/intelligence/main.tsp

@@ -0,0 +1,19 @@
+// =============================================================================
+// ANcpLua v2.0 - Telemetry Intelligence Model
+// =============================================================================
+// Canonical reasoning model over telemetry data. Schema-driven, generated,
+// deterministic. Defines diagnostic patterns, causal rules, and investigation
+// strategies as typed data consumed by Loom, MCP, and dashboard.
+//
+// Source of truth: specs/telemetry-intelligence.md
+// =============================================================================
+
+import "@typespec/openapi";
+
+import "./signals.tsp";
+import "./diagnostic-patterns.tsp";
+import "./causal-rules.tsp";
+import "./investigation-strategies.tsp";
+import "./seed/patterns.tsp";
+import "./seed/rules.tsp";
+import "./seed/strategies.tsp";

package/intelligence/seed/patterns.tsp

@@ -0,0 +1,172 @@
+// =============================================================================
+// ANcpLua v2.0 - Seed Diagnostic Patterns (v1)
+// =============================================================================
+// 19 initial diagnostic patterns (10 infra + 9 agent behavioral)
+// Source: specs/telemetry-intelligence.md §5.1 + Microsoft Research AgentRx (March 2026)
+// These compile to static registries in DiagnosticPatterns.g.cs.
+//
+// Signal attributes reference:
+//   - OTel semantic attributes (status_code, duration_ns, etc.)
+//   - qyl-derived attributes (gen_ai_provider_name, gen_ai_stop_reason, etc.)
+//   - Computed fields (occurrence_rate, span_count_under_parent, etc.)
+// =============================================================================
+
+namespace Qyl.Api.Contracts.Intelligence.Seed;
+
+// ---------------------------------------------------------------------------
+// Pattern: genai_rate_limit
+// Category: genai
+// Signals: status_code=2, gen_ai_provider_name exists, error_type contains rate_limit
+// Hypothesis: Provider throttling. Check quota, reduce concurrency, add backoff.
+// Confidence: 0.9
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: genai_token_exhaustion
+// Category: genai
+// Signals: gen_ai_stop_reason=length
+// Hypothesis: Context window exceeded. Reduce prompt size or switch to larger model.
+// Confidence: 0.85
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: genai_content_filter
+// Category: genai
+// Signals: gen_ai_stop_reason contains content_filter
+// Hypothesis: Content policy violation. Review prompt content.
+// Confidence: 0.95
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: db_timeout
+// Category: data
+// Signals: exception_type=TimeoutException, db.system.name exists, duration_ns > 2000000000
+// Hypothesis: Database query timeout. Check query plan, connection pool, lock contention.
+// Confidence: 0.85
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: db_n_plus_one
+// Category: data
+// Signals: db.system.name exists, parent_span_id exists, span_count_under_parent > 10
+// Hypothesis: N+1 query pattern. Batch or prefetch related data.
+// Confidence: 0.80
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: http_5xx_cluster
+// Category: error
+// Signals: http.response.status_code gte 500, occurrence_rate > baseline * 3
+// Hypothesis: Server error spike. Check recent deployments and upstream dependencies.
+// Confidence: 0.75
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: deployment_regression
+// Category: error
+// Signals: error_type exists, first_seen_at > last_deployment_time
+// Hypothesis: New error class after deployment. Compare with previous version.
+// Confidence: 0.80
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: cascading_timeout
+// Category: latency
+// Signals: exception_type contains Timeout, downstream_service_error=true
+// Hypothesis: Upstream failure causing downstream timeouts. Investigate root service first.
+// Confidence: 0.70
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: memory_pressure_latency
+// Category: latency
+// Signals: process.runtime.dotnet.gc.duration gt 100, avg_latency > p99_baseline
+// Hypothesis: GC pressure causing latency. Check memory allocation patterns.
+// Confidence: 0.65
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: cost_spike
+// Category: cost
+// Signals: gen_ai_cost_usd > daily_average * 3
+// Hypothesis: Abnormal cost increase. Identify the model, service, and session responsible.
+// Confidence: 0.75
+// ---------------------------------------------------------------------------
+
+// =============================================================================
+// Agent behavioral failure patterns (AgentRx taxonomy)
+// Source: Microsoft Research AgentRx, March 2026
+// 9 failure categories from Magentic-One and TAU-Retail benchmarks
+// =============================================================================
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_intent_plan_misalignment
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.operation.name=invoke_agent, status_code=2
+// Hypothesis: Agent plan diverges from user intent. Review task decomposition.
+// Confidence: 0.70
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_misinterpret_tool_info
+// Category: agent
+// Signals: gen_ai.tool.name exists, gen_ai.tool.call.id exists, error_type contains tool
+// Hypothesis: Agent misinterpreted tool output or schema.
+// Confidence: 0.75
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_rai_policy_violation
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.stop_reason contains content_filter
+// Hypothesis: Agent triggered responsible AI policy violation.
+// Confidence: 0.95
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_plan_adherence_failure
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.operation.name=invoke_agent, gen_ai.usage.output_tokens>0, child_span_count>20
+// Hypothesis: Agent deviated from its own plan. Excessive tool calls suggest improvisation.
+// Confidence: 0.65
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_invent_new_info
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.operation.name=invoke_agent
+// Hypothesis: Agent fabricated information not in tool outputs. Cross-reference claims vs results.
+// Confidence: 0.60
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_invalid_invocation
+// Category: agent
+// Signals: gen_ai.tool.name exists, error_type contains invalid, gen_ai.agent.name exists
+// Hypothesis: Agent called tool with invalid arguments or nonexistent name.
+// Confidence: 0.85
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_hallucination_doubt
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.usage.output_tokens>500, gen_ai.tool.call.id not_exists
+// Hypothesis: Long response without tool grounding. High hallucination risk.
+// Confidence: 0.55
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_instruction_adherence_failure
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.operation.name=invoke_agent
+// Hypothesis: Agent ignored or contradicted system prompt constraints.
+// Confidence: 0.60
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Pattern: agent_underspecified_intent
+// Category: agent
+// Signals: gen_ai.agent.name exists, gen_ai.operation.name=invoke_agent, gen_ai.usage.input_tokens<50
+// Hypothesis: Ambiguous request with insufficient context for reliable execution.
+// Confidence: 0.65
+// ---------------------------------------------------------------------------

package/intelligence/seed/rules.tsp

@@ -0,0 +1,44 @@
+// =============================================================================
+// ANcpLua v2.0 - Seed Causal Rules (v1)
+// =============================================================================
+// 6 initial causal rules. Source: specs/telemetry-intelligence.md §5.2
+// These compile to static registries in CausalRules.g.cs.
+// =============================================================================
+
+namespace Qyl.Api.Contracts.Intelligence.Seed;
+
+// ---------------------------------------------------------------------------
+// Rule: deploy_causes_regression
+// Cause: deployment_regression → Effect: http_5xx_cluster
+// Strength: 0.85, Window: 1h
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rule: rate_limit_causes_cascade
+// Cause: genai_rate_limit → Effect: cascading_timeout
+// Strength: 0.70, Window: 5m
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rule: db_timeout_causes_http_error
+// Cause: db_timeout → Effect: http_5xx_cluster
+// Strength: 0.80, Window: 1m
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rule: n_plus_one_causes_db_timeout
+// Cause: db_n_plus_one → Effect: db_timeout
+// Strength: 0.75, Window: 30s
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rule: memory_causes_timeout
+// Cause: memory_pressure_latency → Effect: cascading_timeout
+// Strength: 0.65, Window: 5m
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rule: token_exhaustion_causes_cost
+// Cause: genai_token_exhaustion → Effect: cost_spike
+// Strength: 0.60, Window: 1h
+// ---------------------------------------------------------------------------

package/intelligence/seed/strategies.tsp

@@ -0,0 +1,56 @@
+// =============================================================================
+// ANcpLua v2.0 - Seed Investigation Strategies (v1)
+// =============================================================================
+// 4 initial investigation strategies. Source: specs/telemetry-intelligence.md §5.3
+// These compile to static registries in InvestigationStrategies.g.cs.
+//
+// Trigger patterns use category:X syntax for category-wide triggers.
+// Query templates are abstract qyl investigation hints; the runtime decides how to execute them.
+// =============================================================================
+
+namespace Qyl.Api.Contracts.Intelligence.Seed;
+
+// ---------------------------------------------------------------------------
+// Strategy: investigate_error_issue
+// Trigger: category:error (any error category pattern)
+// Steps:
+//   1. get_issue — SELECT * FROM error_issues WHERE id = ?
+//   2. get_events — SELECT * FROM error_issue_events WHERE issue_id = ? ORDER BY timestamp DESC LIMIT 10
+//   3. get_traces — SELECT * FROM spans WHERE trace_id IN (?) ORDER BY start_time_unix_nano
+//   4. get_code_location — SELECT code_filepath, code_function, code_lineno FROM spans WHERE span_id = ?
+//   5. correlate_deployment — SELECT * FROM deployments WHERE service_name = ? AND start_time <= ? ORDER BY start_time DESC LIMIT 1
+//   6. check_fix_history — SELECT * FROM fix_runs WHERE issue_id = ?
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Strategy: investigate_latency
+// Trigger: category:latency (any latency category pattern)
+// Steps:
+//   1. identify_service — SELECT service_name, AVG(duration_ns), PERCENTILE_CONT(0.99) ... GROUP BY service_name
+//   2. compare_distributions — SELECT duration_ns FROM spans WHERE service_name = ? AND start_time BETWEEN ? AND ?
+//   3. find_regression_window — Time-series analysis of p99 latency
+//   4. correlate_deployment — SELECT * FROM deployments WHERE service_name = ? AND start_time <= ? ORDER BY start_time DESC LIMIT 1
+//   5. inspect_slow_spans — SELECT * FROM spans WHERE service_name = ? AND duration_ns > ? ORDER BY duration_ns DESC LIMIT 20
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Strategy: investigate_cost
+// Trigger: category:cost (any cost category pattern)
+// Steps:
+//   1. identify_model — SELECT gen_ai_request_model, SUM(gen_ai_cost_usd) ... GROUP BY gen_ai_request_model
+//   2. identify_service — SELECT service_name, SUM(gen_ai_cost_usd) ... GROUP BY service_name
+//   3. identify_session — SELECT session_id, SUM(gen_ai_cost_usd) ... GROUP BY session_id ORDER BY 2 DESC
+//   4. trace_to_root — Follow session → traces → spans
+//   5. compare_to_baseline — Compare current period vs previous period
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Strategy: investigate_genai
+// Trigger: category:genai (any genai category pattern)
+// Steps:
+//   1. get_error_details — SELECT * FROM spans WHERE status_code = 2 AND gen_ai_provider_name IS NOT NULL
+//   2. check_provider_status — Evaluate gen_ai_provider_name + error frequency
+//   3. analyze_token_usage — SELECT gen_ai_input_tokens, gen_ai_output_tokens FROM spans WHERE gen_ai_request_model = ?
+//   4. check_prompt_patterns — Inspect spans around the error for prompt size trends
+//   5. suggest_mitigation — Pattern-specific recommendation
+// ---------------------------------------------------------------------------

package/intelligence/signals.tsp

@@ -0,0 +1,60 @@
+// =============================================================================
+// ANcpLua v2.0 - Signal Primitive
+// =============================================================================
+// The atomic unit of telemetry observation. A single attribute condition.
+// Signals reference semconv attributes and qyl-derived attributes only.
+// =============================================================================
+
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Qyl.Api.Contracts.Intelligence;
+
+@doc("Comparison operator for signal evaluation")
+enum SignalOperator {
+  @doc("Equals")
+  eq: "eq",
+
+  @doc("Not equals")
+  neq: "neq",
+
+  @doc("Greater than")
+  gt: "gt",
+
+  @doc("Greater than or equal")
+  gte: "gte",
+
+  @doc("Less than")
+  lt: "lt",
+
+  @doc("Less than or equal")
+  lte: "lte",
+
+  @doc("String contains")
+  contains: "contains",
+
+  @doc("Attribute is non-null")
+  exists: "exists",
+
+  @doc("Attribute is null")
+  not_exists: "not_exists",
+
+  @doc("Regex match")
+  matches: "matches",
+
+  @doc("Value in set (comma-separated)")
+  in_set: "in",
+}
+
+@doc("Atomic telemetry observation — a single attribute condition")
+model Signal {
+  @doc("Telemetry attribute name (semconv or promoted column)")
+  attribute: string;
+
+  @doc("Comparison operator")
+  operator: SignalOperator;
+
+  @doc("Expected value (type-coerced at evaluation time). Omit for exists/not_exists.")
+  value?: string;
+}