@ancplua/qyl-api-schema 5.0.0 → 6.0.0

package/README.md

@@ -11,7 +11,7 @@ no metric DTOs or routes. Profiles are not supported.
 ## Contract pipeline
 
 ```text
-Qyl.OpenTelemetry.SemanticConventions
+Qyl.Telemetry.SemanticConventions
         |
         | generated semantic key projection
         v
@@ -45,6 +45,11 @@ regenerate the artifacts, and map the runtime model to the generated contract.
 
 ## Published artifacts
 
+Both registries carry the same version from one release tag. The contract advances on
+its own major cadence and does not track the qyl product version — it was already at
+`5.0.0` when qyl launched at `1.0.0`. Read the current version from npm or nuget.org
+rather than from prose here; this line moves faster than a README is revised.
+
 | Ecosystem | Artifact | Purpose |
 | --- | --- | --- |
 | npm/TypeSpec | `@ancplua/qyl-api-schema` | Authored schema for TypeSpec consumers |
@@ -54,6 +59,16 @@ regenerate the artifacts, and map the runtime model to the generated contract.
 `main.tsp` is the local compile entry point and includes emitter routing. `index.tsp`
 is the published TypeSpec entry point and contains only the client-facing contract.
 
+## Contract revision
+
+`scripts/emit-contract-revision.mjs` stamps a deterministic revision — `sha256:` plus
+the first 16 hex characters of the contract's canonical semantic digest — into both
+generated faces during `npm run compile`. A collector reports the revision it was built
+against on its health response, so a client can detect a peer built from a different
+contract instead of discovering the mismatch one malformed field at a time. Read the
+current value from a running collector or the generated artifacts; it is derived, never
+hand-maintained.
+
 ## Develop
 
 Development and CI use Node.js 24 LTS. Published npm artifacts support maintained

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

@@ -6445,6 +6445,11 @@
         },
         "error": {
           "type": "string"
+        },
+        "occurred_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the reported transition actually occurred at the adapter that executed\nit. The journal event minted for this transition carries this clock — the\noriginating agent's — so control events order and measure consistently with\nthe agent-clocked events around them; omitted, the collector's receipt time\nis the fallback."
         }
       },
       "unevaluatedProperties": {
@@ -6723,9 +6728,6 @@
         "agent_id": {
           "$ref": "#/$defs/Workflow.WorkflowAgentId"
         },
-        "parent_node_id": {
-          "$ref": "#/$defs/Workflow.WorkflowNodeId"
-        },
         "started_at": {
           "type": "string",
           "format": "date-time"

package/generated/openapi/qyl.openapi.json

@@ -21049,6 +21049,11 @@
           },
           "error": {
             "type": "string"
+          },
+          "occurred_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the reported transition actually occurred at the adapter that executed\nit. The journal event minted for this transition carries this clock — the\noriginating agent's — so control events order and measure consistently with\nthe agent-clocked events around them; omitted, the collector's receipt time\nis the fallback."
           }
         },
         "unevaluatedProperties": {
@@ -21327,9 +21332,6 @@
           "agent_id": {
             "$ref": "#/components/schemas/Workflow.WorkflowAgentId"
           },
-          "parent_node_id": {
-            "$ref": "#/components/schemas/Workflow.WorkflowNodeId"
-          },
           "started_at": {
             "type": "string",
             "format": "date-time"

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

@@ -1439,7 +1439,6 @@ export interface WorkflowGraphNode {
     "status": string;
     "attempt_id"?: WorkflowAttemptId;
     "agent_id"?: WorkflowAgentId;
-    "parent_node_id"?: WorkflowNodeId;
     "started_at"?: string;
     "ended_at"?: string;
     "duration_ms"?: number;
@@ -1506,6 +1505,7 @@ export interface WorkflowControlCommandPage {
 export interface WorkflowControlStatusUpdateRequest {
     "status": WorkflowControlStatus;
     "error"?: string;
+    "occurred_at"?: string;
 }
 export interface WorkflowHeartbeatEvent {
     "type": "heartbeat";

package/generated/ts-runtime/api.js

@@ -392,4 +392,4 @@ export const FetchTelemetryViewValues = {
 };
 // --- 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:c4b86d761cbd7299";
+export const CONTRACT_REVISION = "sha256:f32216c3a3172ab0";

package/models/workflow.tsp

@@ -375,9 +375,6 @@ model WorkflowGraphNode {
   @encodedName("application/json", "agent_id")
   agentId?: WorkflowAgentId;
 
-  @encodedName("application/json", "parent_node_id")
-  parentNodeId?: WorkflowNodeId;
-
   @encodedName("application/json", "started_at")
   startedAt?: utcDateTime;
 
@@ -534,4 +531,14 @@ model WorkflowControlCommandPage {
 model WorkflowControlStatusUpdateRequest {
   status: WorkflowControlStatus;
   error?: string;
+
+  @doc("""
+    When the reported transition actually occurred at the adapter that executed
+    it. The journal event minted for this transition carries this clock — the
+    originating agent's — so control events order and measure consistently with
+    the agent-clocked events around them; omitted, the collector's receipt time
+    is the fallback.
+    """)
+  @encodedName("application/json", "occurred_at")
+  occurredAt?: utcDateTime;
 }

package/package.json

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