@ancplua/qyl-api-schema 4.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/api/workflow.tsp

@@ -0,0 +1,231 @@
+import "@typespec/events";
+import "@typespec/http";
+import "@typespec/sse";
+
+import "../common/errors.tsp";
+import "../models/workflow.tsp";
+import "./routes.tsp";
+
+using TypeSpec.Events;
+using TypeSpec.Http;
+using TypeSpec.SSE;
+
+using Qyl.Api.Contracts.Common.Errors;
+using Qyl.Api.Contracts.Workflow;
+
+namespace Qyl.Api.Contracts.Workflow;
+
+@doc("Keep-alive emitted while a workflow event stream has no new event.")
+model WorkflowHeartbeatEvent {
+  type: "heartbeat";
+
+  @encodedName("application/json", "high_water_mark")
+  highWaterMark: WorkflowSequence;
+
+  timestamp: utcDateTime;
+}
+
+@doc("Signals that the requested cursor predates retained workflow history.")
+model WorkflowCursorGapEvent {
+  type: "cursor_gap";
+
+  @encodedName("application/json", "oldest_available_sequence")
+  oldestAvailableSequence: WorkflowSequence;
+
+  @encodedName("application/json", "high_water_mark")
+  highWaterMark: WorkflowSequence;
+
+  timestamp: utcDateTime;
+}
+
+@events
+union WorkflowStreamEvents {
+  event: WorkflowJournalEvent,
+  heartbeat: WorkflowHeartbeatEvent,
+  cursorGap: WorkflowCursorGapEvent,
+}
+
+@route("/api/v1/workflow-runs")
+@tag("Workflow runs")
+@useAuth(Qyl.Api.Contracts.QylApiKeyHeaderAuth)
+interface WorkflowRunsApi {
+  @post
+  create(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @body request: WorkflowRunCreateRequest,
+  ):
+    | WorkflowRun
+    | ValidationError
+    | UnauthorizedError
+    | ConflictError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  list(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @query status?: WorkflowRunStatus,
+    @query
+    @minValue(1)
+    @maxValue(200)
+    limit?: int32 = 50,
+    @query cursor?: string,
+  ):
+    | WorkflowRunPage
+    | ValidationError
+    | UnauthorizedError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}")
+  get(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+  ):
+    | WorkflowRun
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @post
+  @route("/{run_id}/events")
+  appendEvents(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @body request: WorkflowEventBatchAppendRequest,
+  ):
+    | WorkflowEventBatchAppendResponse
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ConflictError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}/events")
+  readEvents(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @query("after_sequence") afterSequence?: WorkflowSequence,
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 250,
+    @query("wait_ms")
+    @minValue(0)
+    @maxValue(30000)
+    waitMs?: int32 = 0,
+  ):
+    | WorkflowEventPage
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}/graph")
+  getGraph(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @query("node_cursor") nodeCursor?: string,
+    @query("node_limit")
+    @minValue(1)
+    @maxValue(1000)
+    nodeLimit?: int32 = 250,
+    @query("edge_cursor") edgeCursor?: string,
+    @query("edge_limit")
+    @minValue(1)
+    @maxValue(2000)
+    edgeLimit?: int32 = 500,
+  ):
+    | WorkflowGraphSnapshot
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}/content/{content_ref}")
+  getContent(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @path("content_ref") contentRef: WorkflowContentRef,
+  ):
+    | WorkflowContent
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}/stream")
+  stream(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @header("Last-Event-ID") lastEventId?: string,
+  ):
+    | SSEStream<WorkflowStreamEvents>
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @post
+  @route("/{run_id}/commands")
+  submitControl(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @body request: WorkflowControlRequest,
+  ):
+    | WorkflowControlCommand
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ConflictError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @get
+  @route("/{run_id}/commands")
+  pollControls(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @query("after_sequence") afterSequence?: WorkflowSequence,
+    @query
+    @minValue(1)
+    @maxValue(100)
+    limit?: int32 = 20,
+    @query("wait_ms")
+    @minValue(0)
+    @maxValue(30000)
+    waitMs?: int32 = 0,
+  ):
+    | WorkflowControlCommandPage
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ServiceUnavailableError
+    | InternalServerError;
+
+  @post
+  @route("/{run_id}/commands/{command_id}/status")
+  updateControl(
+    ...Qyl.Api.Contracts.ProjectScopeHeader,
+    @path("run_id") runId: WorkflowRunId,
+    @path("command_id") commandId: WorkflowCommandId,
+    @body request: WorkflowControlStatusUpdateRequest,
+  ):
+    | WorkflowControlCommand
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | ConflictError
+    | ServiceUnavailableError
+    | InternalServerError;
+}

package/common/types.tsp

@@ -178,12 +178,11 @@ scalar Temperature extends float64;
 @maxLength(64)
 scalar Sha256Hash extends string;
 
-// The revision is a content hash of the emitted OpenAPI artifact, not a package
-// version: two builds of the same contract share it whatever their package
-// versions say, and any contract edit changes it without anyone remembering to
-// bump anything. 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 the SHA-256 digest of the emitted OpenAPI document.")
+// 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.
+@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)
 @maxLength(23)