@ancplua/qyl-api-schema 5.0.0 → 5.1.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": {

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": {

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

@@ -1506,6 +1506,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:9d94fe8f5c913e4b";

package/models/workflow.tsp

@@ -534,4 +534,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": "5.1.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": {