@knowledge-stack/ksapi 1.81.0 → 1.83.0

package/docs/PathPartApprovalResponse.md

@@ -0,0 +1,55 @@
+
+# PathPartApprovalResponse
+
+Approval audit-history row over any path_part (file or folder).  ``run_id`` is optional — None when the path_part was approved directly without a workflow-run context.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`id` | string
+`runId` | string
+`pathPartId` | string
+`status` | [PathPartApprovalDecision](PathPartApprovalDecision.md)
+`reviewerId` | string
+`reviewedAt` | Date
+`rejectionReason` | string
+`unapprovedBy` | string
+`unapprovedAt` | Date
+`createdAt` | Date
+`updatedAt` | Date
+
+## Example
+
+```typescript
+import type { PathPartApprovalResponse } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "id": null,
+  "runId": null,
+  "pathPartId": null,
+  "status": null,
+  "reviewerId": null,
+  "reviewedAt": null,
+  "rejectionReason": null,
+  "unapprovedBy": null,
+  "unapprovedAt": null,
+  "createdAt": null,
+  "updatedAt": null,
+} satisfies PathPartApprovalResponse
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as PathPartApprovalResponse
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/RejectFileRequest.md

@@ -0,0 +1,35 @@
+
+# RejectFileRequest
+
+Body for ``POST /workflow-runs/{run}/files/{file}/reject``.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`reason` | string
+
+## Example
+
+```typescript
+import type { RejectFileRequest } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "reason": null,
+} satisfies RejectFileRequest
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as RejectFileRequest
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/RunLockResponse.md

@@ -0,0 +1,39 @@
+
+# RunLockResponse
+
+Reviewer-lock state on a workflow run.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`runId` | string
+`lockUserId` | string
+`lockAcquiredAt` | Date
+
+## Example
+
+```typescript
+import type { RunLockResponse } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "runId": null,
+  "lockUserId": null,
+  "lockAcquiredAt": null,
+} satisfies RunLockResponse
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as RunLockResponse
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/UpdateWorkflowDefinitionRequest.md

@@ -1,7 +1,7 @@
 
 # UpdateWorkflowDefinitionRequest
 
-Full replacement (PUT semantics). All fields are required.
+Full replacement (PUT semantics).  ``instruction_path_part_ids``:  - ``KS_INTERNAL``: must remain ``len == 1`` (the auto-provisioned doc). - ``SELF_HOSTED``: ``len ≥ 1``; callers may swap or add documents.
 
 ## Properties
 
@@ -17,6 +17,7 @@ Name | Type
 `outputPathPartIds` | Array<string>
 `templatePathPartId` | string
 `isActive` | boolean
+`approvalRequired` | boolean
 
 ## Example
 
@@ -35,6 +36,7 @@ const example = {
   "outputPathPartIds": null,
   "templatePathPartId": null,
   "isActive": null,
+  "approvalRequired": null,
 } satisfies UpdateWorkflowDefinitionRequest
 
 console.log(example)

package/docs/WorkflowDefinitionResponse.md

@@ -18,6 +18,7 @@ Name | Type
 `outputPathPartIds` | Array<string>
 `templatePathPartId` | string
 `isActive` | boolean
+`approvalRequired` | boolean
 `createdAt` | Date
 `updatedAt` | Date
 
@@ -39,6 +40,7 @@ const example = {
   "outputPathPartIds": null,
   "templatePathPartId": null,
   "isActive": null,
+  "approvalRequired": null,
   "createdAt": null,
   "updatedAt": null,
 } satisfies WorkflowDefinitionResponse

package/docs/WorkflowDefinitionsApi.md

@@ -236,6 +236,8 @@ No authorization required
 
 Invoke Workflow Handler
 
+Trigger a workflow run.  All business logic lives in ``WorkflowInvocationService``. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to ``FAILED`` rather than rejecting the request.
+
 ### Example
 
 ```ts

package/docs/WorkflowRunResponse.md

@@ -1,7 +1,7 @@
 
 # WorkflowRunResponse
 
-Workflow run response.
+Workflow run response.  Note: ``run_token_jti`` is intentionally NOT exposed. It\'s an internal token identifier persisted on the run row for callback auth — clients should treat run dispatch state as observable via ``status`` (RUNNING => dispatched), not via JTI presence.
 
 ## Properties
 
@@ -16,6 +16,8 @@ Name | Type
 `completedAt` | Date
 `runSnapshot` | [WorkflowRunSnapshot](WorkflowRunSnapshot.md)
 `error` | string
+`inputPathPartIds` | Array<string>
+`inputVersionIds` | Array<string>
 `createdAt` | Date
 `updatedAt` | Date
 
@@ -35,6 +37,8 @@ const example = {
   "completedAt": null,
   "runSnapshot": null,
   "error": null,
+  "inputPathPartIds": null,
+  "inputVersionIds": null,
   "createdAt": null,
   "updatedAt": null,
 } satisfies WorkflowRunResponse

package/docs/WorkflowRunSnapshot.md

@@ -13,7 +13,7 @@ Name | Type
 `userId` | string
 `maxRunDurationSeconds` | number
 `sources` | [Array<ABCDPathSnapshot>](ABCDPathSnapshot.md)
-`instructions` | [Array<ABCDPathSnapshot>](ABCDPathSnapshot.md)
+`instructions` | [Array<InstructionSnapshot>](InstructionSnapshot.md)
 `outputs` | [Array<ABCDPathSnapshot>](ABCDPathSnapshot.md)
 `template` | [ABCDPathSnapshot](ABCDPathSnapshot.md)
 

package/docs/WorkflowRunStatus.md

@@ -1,7 +1,7 @@
 
 # WorkflowRunStatus
 
-Lifecycle status of a workflow run.
+Combined lifecycle + approval-rollup status of a workflow run.  Absorbs the prior split between ``status`` (PENDING/RUNNING/COMPLETED/ FAILED) and ``approval_state`` (in_progress/awaiting_review/approved/ rejected/failed). One state field per run.  Allowed transitions::      PENDING        -> IN_PROGRESS              (agent dispatched)     IN_PROGRESS    -> COMPLETED                (workflow.approval_required=FALSE)     IN_PROGRESS    -> NEEDS_APPROVAL           (workflow.approval_required=TRUE, agent done)     NEEDS_APPROVAL -> APPROVED                 (run folder approved by reviewer)     NEEDS_APPROVAL -> REJECTED                 (run folder or any child rejected)     APPROVED       -> NEEDS_APPROVAL           (run folder unapproved)     REJECTED       -> NEEDS_APPROVAL           (rejection reversed; mutable)     any non-terminal -> FAILED                 (agent error)
 
 ## Properties
 

package/docs/WorkflowRunsApi.md

@@ -4,12 +4,168 @@ All URIs are relative to *http://localhost:8000*
 
 | Method | HTTP request | Description |
 |------------- | ------------- | -------------|
+| [**acquireWorkflowRunLock**](WorkflowRunsApi.md#acquireworkflowrunlock) | **POST** /v1/workflow-runs/{run_id}/lock | Acquire Workflow Run Lock Handler |
+| [**approveWorkflowRunFile**](WorkflowRunsApi.md#approveworkflowrunfile) | **POST** /v1/workflow-runs/{run_id}/files/{path_part_id}/approve | Approve Workflow Run File Handler |
 | [**deleteWorkflowRun**](WorkflowRunsApi.md#deleteworkflowrun) | **DELETE** /v1/workflow-runs/{run_id} | Delete Workflow Run Handler |
 | [**getWorkflowRun**](WorkflowRunsApi.md#getworkflowrun) | **GET** /v1/workflow-runs/{run_id} | Get Workflow Run Handler |
+| [**rejectWorkflowRunFile**](WorkflowRunsApi.md#rejectworkflowrunfile) | **POST** /v1/workflow-runs/{run_id}/files/{path_part_id}/reject | Reject Workflow Run File Handler |
+| [**releaseWorkflowRunLock**](WorkflowRunsApi.md#releaseworkflowrunlock) | **DELETE** /v1/workflow-runs/{run_id}/lock | Release Workflow Run Lock Handler |
+| [**unapproveWorkflowRunFile**](WorkflowRunsApi.md#unapproveworkflowrunfile) | **POST** /v1/workflow-runs/{run_id}/files/{path_part_id}/unapprove | Unapprove Workflow Run File Handler |
 | [**workflowRunCallback**](WorkflowRunsApi.md#workflowruncallbackoperation) | **POST** /v1/workflow-runs/{run_id}/callback | Workflow Run Callback Handler |
 
 
 
+## acquireWorkflowRunLock
+
+> RunLockResponse acquireWorkflowRunLock(runId, authorization, ksUat)
+
+Acquire Workflow Run Lock Handler
+
+Acquire (or renew) the reviewer lock on ``run_id``.  The current holder may re-POST to refresh ``lock_acquired_at``. A different user receives 409 until the lock is released or auto-swept.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  WorkflowRunsApi,
+} from '@knowledge-stack/ksapi';
+import type { AcquireWorkflowRunLockRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new WorkflowRunsApi();
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies AcquireWorkflowRunLockRequest;
+
+  try {
+    const data = await api.acquireWorkflowRunLock(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**RunLockResponse**](RunLockResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
+## approveWorkflowRunFile
+
+> PathPartApprovalResponse approveWorkflowRunFile(runId, pathPartId, authorization, ksUat)
+
+Approve Workflow Run File Handler
+
+Approve a single generated file. Caller must hold the run lock.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  WorkflowRunsApi,
+} from '@knowledge-stack/ksapi';
+import type { ApproveWorkflowRunFileRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new WorkflowRunsApi();
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string
+    pathPartId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies ApproveWorkflowRunFileRequest;
+
+  try {
+    const data = await api.approveWorkflowRunFile(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+| **pathPartId** | `string` |  | [Defaults to `undefined`] |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**PathPartApprovalResponse**](PathPartApprovalResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
 ## deleteWorkflowRun
 
 > deleteWorkflowRun(runId, authorization, ksUat)
@@ -154,6 +310,237 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
+## rejectWorkflowRunFile
+
+> PathPartApprovalResponse rejectWorkflowRunFile(runId, pathPartId, rejectFileRequest, authorization, ksUat)
+
+Reject Workflow Run File Handler
+
+Reject a single generated file with a reason. Caller must hold the run lock.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  WorkflowRunsApi,
+} from '@knowledge-stack/ksapi';
+import type { RejectWorkflowRunFileRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new WorkflowRunsApi();
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string
+    pathPartId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // RejectFileRequest
+    rejectFileRequest: ...,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies RejectWorkflowRunFileRequest;
+
+  try {
+    const data = await api.rejectWorkflowRunFile(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+| **pathPartId** | `string` |  | [Defaults to `undefined`] |
+| **rejectFileRequest** | [RejectFileRequest](RejectFileRequest.md) |  | |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**PathPartApprovalResponse**](PathPartApprovalResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: `application/json`
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
+## releaseWorkflowRunLock
+
+> releaseWorkflowRunLock(runId, authorization, ksUat)
+
+Release Workflow Run Lock Handler
+
+Release the reviewer lock; only the holder may call this.  DELETE /lock is idempotent: returns 204 even if no lock is held.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  WorkflowRunsApi,
+} from '@knowledge-stack/ksapi';
+import type { ReleaseWorkflowRunLockRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new WorkflowRunsApi();
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies ReleaseWorkflowRunLockRequest;
+
+  try {
+    const data = await api.releaseWorkflowRunLock(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+`void` (Empty response body)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **204** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
+## unapproveWorkflowRunFile
+
+> PathPartApprovalResponse unapproveWorkflowRunFile(runId, pathPartId, authorization, ksUat)
+
+Unapprove Workflow Run File Handler
+
+Revert an approved file to ``pending``.  Does NOT require the reviewer lock — anyone with ``can_write`` on the run path may unapprove (pilot plan §11.7).
+
+### Example
+
+```ts
+import {
+  Configuration,
+  WorkflowRunsApi,
+} from '@knowledge-stack/ksapi';
+import type { UnapproveWorkflowRunFileRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new WorkflowRunsApi();
+
+  const body = {
+    // string
+    runId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string
+    pathPartId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies UnapproveWorkflowRunFileRequest;
+
+  try {
+    const data = await api.unapproveWorkflowRunFile(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **runId** | `string` |  | [Defaults to `undefined`] |
+| **pathPartId** | `string` |  | [Defaults to `undefined`] |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**PathPartApprovalResponse**](PathPartApprovalResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
 ## workflowRunCallback
 
 > WorkflowCallbackResponse workflowRunCallback(runId, workflowRunCallbackRequest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledge-stack/ksapi",
-  "version": "1.81.0",
+  "version": "1.83.0",
   "description": "OpenAPI client for @knowledge-stack/ksapi",
   "author": "OpenAPI-Generator",
   "repository": {

package/src/apis/WorkflowDefinitionsApi.ts

@@ -190,7 +190,7 @@ export interface WorkflowDefinitionsApiInterface {
     invokeWorkflowRequestOpts(requestParameters: InvokeWorkflowOperationRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * 
+     * Trigger a workflow run.  All business logic lives in ``WorkflowInvocationService``. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to ``FAILED`` rather than rejecting the request.
      * @summary Invoke Workflow Handler
      * @param {string} definitionId 
      * @param {InvokeWorkflowRequest} invokeWorkflowRequest 
@@ -203,6 +203,7 @@ export interface WorkflowDefinitionsApiInterface {
     invokeWorkflowRaw(requestParameters: InvokeWorkflowOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WorkflowRunResponse>>;
 
     /**
+     * Trigger a workflow run.  All business logic lives in ``WorkflowInvocationService``. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to ``FAILED`` rather than rejecting the request.
      * Invoke Workflow Handler
      */
     invokeWorkflow(requestParameters: InvokeWorkflowOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WorkflowRunResponse>;
@@ -493,6 +494,7 @@ export class WorkflowDefinitionsApi extends runtime.BaseAPI implements WorkflowD
     }
 
     /**
+     * Trigger a workflow run.  All business logic lives in ``WorkflowInvocationService``. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to ``FAILED`` rather than rejecting the request.
      * Invoke Workflow Handler
      */
     async invokeWorkflowRaw(requestParameters: InvokeWorkflowOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WorkflowRunResponse>> {
@@ -503,6 +505,7 @@ export class WorkflowDefinitionsApi extends runtime.BaseAPI implements WorkflowD
     }
 
     /**
+     * Trigger a workflow run.  All business logic lives in ``WorkflowInvocationService``. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to ``FAILED`` rather than rejecting the request.
      * Invoke Workflow Handler
      */
     async invokeWorkflow(requestParameters: InvokeWorkflowOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WorkflowRunResponse> {