@knowledge-stack/ksapi 1.81.0 → 1.82.0

package/.openapi-generator/FILES

@@ -89,6 +89,7 @@ docs/ImageTaxonomy.md
 docs/InformationStatistics.md
 docs/IngestDocumentResponse.md
 docs/IngestionMode.md
+docs/InstructionSnapshot.md
 docs/InviteLinkSettingsRequest.md
 docs/InviteLinkSettingsResponse.md
 docs/InviteResponse.md
@@ -331,6 +332,7 @@ src/models/ImageTaxonomy.ts
 src/models/InformationStatistics.ts
 src/models/IngestDocumentResponse.ts
 src/models/IngestionMode.ts
+src/models/InstructionSnapshot.ts
 src/models/InviteLinkSettingsRequest.ts
 src/models/InviteLinkSettingsResponse.ts
 src/models/InviteResponse.ts

package/README.md

@@ -1,4 +1,4 @@
-# @knowledge-stack/ksapi@1.81.0
+# @knowledge-stack/ksapi@1.82.0
 
 A TypeScript SDK client for the localhost API.
 
@@ -279,6 +279,7 @@ All URIs are relative to *http://localhost:8000*
 - [InformationStatistics](docs/InformationStatistics.md)
 - [IngestDocumentResponse](docs/IngestDocumentResponse.md)
 - [IngestionMode](docs/IngestionMode.md)
+- [InstructionSnapshot](docs/InstructionSnapshot.md)
 - [InviteLinkSettingsRequest](docs/InviteLinkSettingsRequest.md)
 - [InviteLinkSettingsResponse](docs/InviteLinkSettingsResponse.md)
 - [InviteResponse](docs/InviteResponse.md)
@@ -414,7 +415,7 @@ and is automatically generated by the
 [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: `0.1.0`
-- Package version: `1.81.0`
+- Package version: `1.82.0`
 - Generator version: `7.21.0`
 - Build package: `org.openapitools.codegen.languages.TypeScriptFetchClientCodegen`
 

package/dist/apis/WorkflowDefinitionsApi.d.ts

@@ -141,7 +141,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
@@ -153,6 +153,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>;
@@ -282,10 +283,12 @@ export declare class WorkflowDefinitionsApi extends runtime.BaseAPI implements W
      */
     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.
      * Invoke Workflow Handler
      */
     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>;

package/dist/apis/WorkflowDefinitionsApi.js

@@ -217,6 +217,7 @@ class WorkflowDefinitionsApi extends runtime.BaseAPI {
         });
     }
     /**
+     * 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
      */
     invokeWorkflowRaw(requestParameters, initOverrides) {
@@ -227,6 +228,7 @@ class WorkflowDefinitionsApi extends runtime.BaseAPI {
         });
     }
     /**
+     * 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, initOverrides) {

package/dist/esm/apis/WorkflowDefinitionsApi.d.ts

@@ -141,7 +141,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
@@ -153,6 +153,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>;
@@ -282,10 +283,12 @@ export declare class WorkflowDefinitionsApi extends runtime.BaseAPI implements W
      */
     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.
      * Invoke Workflow Handler
      */
     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>;

package/dist/esm/apis/WorkflowDefinitionsApi.js

@@ -181,6 +181,7 @@ export class WorkflowDefinitionsApi extends runtime.BaseAPI {
         });
     }
     /**
+     * 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
      */
     invokeWorkflowRaw(requestParameters, initOverrides) {
@@ -191,6 +192,7 @@ export class WorkflowDefinitionsApi extends runtime.BaseAPI {
         });
     }
     /**
+     * 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, initOverrides) {

package/dist/esm/models/CreateWorkflowDefinitionRequest.d.ts

@@ -13,6 +13,13 @@ import type { SelfHostedRunnerConfig } from './SelfHostedRunnerConfig';
 import type { WorkflowRunnerType } from './WorkflowRunnerType';
 /**
  * Create a new workflow definition.
+ *
+ * ``instruction_path_part_ids`` semantics depend on ``runner_type``:
+ *
+ * - ``KS_INTERNAL``: must be empty (``[]``); the server auto-provisions a
+ *   single ``instruction.md`` and stores ``[doc.path_part_id]``.
+ * - ``SELF_HOSTED``: caller-supplied list of one-or-more document
+ *   PathPart IDs. Must contain at least one entry.
  * @export
  * @interface CreateWorkflowDefinitionRequest
  */
@@ -58,7 +65,7 @@ export interface CreateWorkflowDefinitionRequest {
      * @type {Array<string>}
      * @memberof CreateWorkflowDefinitionRequest
      */
-    instructionPathPartIds: Array<string>;
+    instructionPathPartIds?: Array<string>;
     /**
      *
      * @type {Array<string>}

package/dist/esm/models/CreateWorkflowDefinitionRequest.js

@@ -30,7 +30,6 @@ export const CreateWorkflowDefinitionRequestPropertyValidationAttributesMap = {
     },
     instructionPathPartIds: {
         maxItems: 20,
-        minItems: 1,
         uniqueItems: false,
     },
     outputPathPartIds: {
@@ -49,8 +48,6 @@ export function instanceOfCreateWorkflowDefinitionRequest(value) {
         return false;
     if (!('sourcePathPartIds' in value) || value['sourcePathPartIds'] === undefined)
         return false;
-    if (!('instructionPathPartIds' in value) || value['instructionPathPartIds'] === undefined)
-        return false;
     if (!('outputPathPartIds' in value) || value['outputPathPartIds'] === undefined)
         return false;
     return true;
@@ -69,7 +66,7 @@ export function CreateWorkflowDefinitionRequestFromJSONTyped(json, ignoreDiscrim
         'runnerConfig': json['runner_config'] == null ? undefined : SelfHostedRunnerConfigFromJSON(json['runner_config']),
         'maxRunDurationSeconds': json['max_run_duration_seconds'] == null ? undefined : json['max_run_duration_seconds'],
         'sourcePathPartIds': json['source_path_part_ids'],
-        'instructionPathPartIds': json['instruction_path_part_ids'],
+        'instructionPathPartIds': json['instruction_path_part_ids'] == null ? undefined : json['instruction_path_part_ids'],
         'outputPathPartIds': json['output_path_part_ids'],
         'templatePathPartId': json['template_path_part_id'] == null ? undefined : json['template_path_part_id'],
     };

package/dist/esm/models/InstructionSnapshot.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { PartType } from './PartType';
+/**
+ * Snapshot of one instruction document, pinned at trigger time.
+ *
+ * The instruction file is the workflow's **contract**: the agent reads
+ * this exact ``document_version_id`` for the duration of the run, even
+ * if the document is edited mid-flight or after the run completes.
+ * Reproducibility and audit replay depend on this pinning.
+ * @export
+ * @interface InstructionSnapshot
+ */
+export interface InstructionSnapshot {
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    pathPartId: string;
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    materializedPath: string;
+    /**
+     *
+     * @type {PartType}
+     * @memberof InstructionSnapshot
+     */
+    partType: PartType;
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    documentVersionId: string;
+}
+export declare const InstructionSnapshotPropertyValidationAttributesMap: {
+    [property: string]: {
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        maximum?: number;
+        exclusiveMaximum?: boolean;
+        minimum?: number;
+        exclusiveMinimum?: boolean;
+        multipleOf?: number;
+        maxItems?: number;
+        minItems?: number;
+        uniqueItems?: boolean;
+    };
+};
+/**
+ * Check if a given object implements the InstructionSnapshot interface.
+ */
+export declare function instanceOfInstructionSnapshot(value: object): value is InstructionSnapshot;
+export declare function InstructionSnapshotFromJSON(json: any): InstructionSnapshot;
+export declare function InstructionSnapshotFromJSONTyped(json: any, ignoreDiscriminator: boolean): InstructionSnapshot;
+export declare function InstructionSnapshotToJSON(json: any): InstructionSnapshot;
+export declare function InstructionSnapshotToJSONTyped(value?: InstructionSnapshot | null, ignoreDiscriminator?: boolean): any;

package/dist/esm/models/InstructionSnapshot.js

@@ -0,0 +1,57 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import { PartTypeFromJSON, PartTypeToJSON, } from './PartType';
+export const InstructionSnapshotPropertyValidationAttributesMap = {};
+/**
+ * Check if a given object implements the InstructionSnapshot interface.
+ */
+export function instanceOfInstructionSnapshot(value) {
+    if (!('pathPartId' in value) || value['pathPartId'] === undefined)
+        return false;
+    if (!('materializedPath' in value) || value['materializedPath'] === undefined)
+        return false;
+    if (!('partType' in value) || value['partType'] === undefined)
+        return false;
+    if (!('documentVersionId' in value) || value['documentVersionId'] === undefined)
+        return false;
+    return true;
+}
+export function InstructionSnapshotFromJSON(json) {
+    return InstructionSnapshotFromJSONTyped(json, false);
+}
+export function InstructionSnapshotFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        'pathPartId': json['path_part_id'],
+        'materializedPath': json['materialized_path'],
+        'partType': PartTypeFromJSON(json['part_type']),
+        'documentVersionId': json['document_version_id'],
+    };
+}
+export function InstructionSnapshotToJSON(json) {
+    return InstructionSnapshotToJSONTyped(json, false);
+}
+export function InstructionSnapshotToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        'path_part_id': value['pathPartId'],
+        'materialized_path': value['materializedPath'],
+        'part_type': PartTypeToJSON(value['partType']),
+        'document_version_id': value['documentVersionId'],
+    };
+}

package/dist/esm/models/InvokeWorkflowRequest.d.ts

@@ -21,6 +21,12 @@ export interface InvokeWorkflowRequest {
      * @memberof InvokeWorkflowRequest
      */
     idempotencyKey?: string | null;
+    /**
+     * Path part IDs of input documents to pin to this run. Each path_part must be a DOCUMENT readable by the caller. Active document_version_id is captured at trigger time.
+     * @type {Array<string>}
+     * @memberof InvokeWorkflowRequest
+     */
+    inputPathPartIds?: Array<string>;
 }
 export declare const InvokeWorkflowRequestPropertyValidationAttributesMap: {
     [property: string]: {

package/dist/esm/models/InvokeWorkflowRequest.js

@@ -15,6 +15,10 @@ export const InvokeWorkflowRequestPropertyValidationAttributesMap = {
     idempotencyKey: {
         maxLength: 255,
     },
+    inputPathPartIds: {
+        maxItems: 50,
+        uniqueItems: false,
+    },
 };
 /**
  * Check if a given object implements the InvokeWorkflowRequest interface.
@@ -31,6 +35,7 @@ export function InvokeWorkflowRequestFromJSONTyped(json, ignoreDiscriminator) {
     }
     return {
         'idempotencyKey': json['idempotency_key'] == null ? undefined : json['idempotency_key'],
+        'inputPathPartIds': json['input_path_part_ids'] == null ? undefined : json['input_path_part_ids'],
     };
 }
 export function InvokeWorkflowRequestToJSON(json) {
@@ -42,5 +47,6 @@ export function InvokeWorkflowRequestToJSONTyped(value, ignoreDiscriminator = fa
     }
     return {
         'idempotency_key': value['idempotencyKey'],
+        'input_path_part_ids': value['inputPathPartIds'],
     };
 }

package/dist/esm/models/UpdateWorkflowDefinitionRequest.d.ts

@@ -12,7 +12,12 @@
 import type { SelfHostedRunnerConfig } from './SelfHostedRunnerConfig';
 import type { WorkflowRunnerType } from './WorkflowRunnerType';
 /**
- * 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.
  * @export
  * @interface UpdateWorkflowDefinitionRequest
  */

package/dist/esm/models/WorkflowRunResponse.d.ts

@@ -14,6 +14,11 @@ import type { WorkflowRunStatus } from './WorkflowRunStatus';
 import type { WorkflowRunnerType } from './WorkflowRunnerType';
 /**
  * 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.
  * @export
  * @interface WorkflowRunResponse
  */
@@ -72,6 +77,18 @@ export interface WorkflowRunResponse {
      * @memberof WorkflowRunResponse
      */
     error: string | null;
+    /**
+     *
+     * @type {Array<string>}
+     * @memberof WorkflowRunResponse
+     */
+    inputPathPartIds: Array<string>;
+    /**
+     *
+     * @type {Array<string>}
+     * @memberof WorkflowRunResponse
+     */
+    inputVersionIds: Array<string>;
     /**
      *
      * @type {Date}

package/dist/esm/models/WorkflowRunResponse.js

@@ -37,6 +37,10 @@ export function instanceOfWorkflowRunResponse(value) {
         return false;
     if (!('error' in value) || value['error'] === undefined)
         return false;
+    if (!('inputPathPartIds' in value) || value['inputPathPartIds'] === undefined)
+        return false;
+    if (!('inputVersionIds' in value) || value['inputVersionIds'] === undefined)
+        return false;
     if (!('createdAt' in value) || value['createdAt'] === undefined)
         return false;
     if (!('updatedAt' in value) || value['updatedAt'] === undefined)
@@ -60,6 +64,8 @@ export function WorkflowRunResponseFromJSONTyped(json, ignoreDiscriminator) {
         'completedAt': (json['completed_at'] == null ? null : new Date(json['completed_at'])),
         'runSnapshot': WorkflowRunSnapshotFromJSON(json['run_snapshot']),
         'error': json['error'],
+        'inputPathPartIds': json['input_path_part_ids'],
+        'inputVersionIds': json['input_version_ids'],
         'createdAt': (new Date(json['created_at'])),
         'updatedAt': (new Date(json['updated_at'])),
     };
@@ -81,6 +87,8 @@ export function WorkflowRunResponseToJSONTyped(value, ignoreDiscriminator = fals
         'completed_at': value['completedAt'] == null ? value['completedAt'] : value['completedAt'].toISOString(),
         'run_snapshot': WorkflowRunSnapshotToJSON(value['runSnapshot']),
         'error': value['error'],
+        'input_path_part_ids': value['inputPathPartIds'],
+        'input_version_ids': value['inputVersionIds'],
         'created_at': value['createdAt'].toISOString(),
         'updated_at': value['updatedAt'].toISOString(),
     };

package/dist/esm/models/WorkflowRunSnapshot.d.ts

@@ -10,6 +10,7 @@
  * Do not edit the class manually.
  */
 import type { ABCDPathSnapshot } from './ABCDPathSnapshot';
+import type { InstructionSnapshot } from './InstructionSnapshot';
 import type { WorkflowRunnerType } from './WorkflowRunnerType';
 /**
  * Frozen ABCD configuration captured at workflow trigger time.
@@ -55,10 +56,10 @@ export interface WorkflowRunSnapshot {
     sources: Array<ABCDPathSnapshot>;
     /**
      *
-     * @type {Array<ABCDPathSnapshot>}
+     * @type {Array<InstructionSnapshot>}
      * @memberof WorkflowRunSnapshot
      */
-    instructions: Array<ABCDPathSnapshot>;
+    instructions: Array<InstructionSnapshot>;
     /**
      *
      * @type {Array<ABCDPathSnapshot>}

package/dist/esm/models/WorkflowRunSnapshot.js

@@ -12,6 +12,7 @@
  * Do not edit the class manually.
  */
 import { ABCDPathSnapshotFromJSON, ABCDPathSnapshotToJSON, } from './ABCDPathSnapshot';
+import { InstructionSnapshotFromJSON, InstructionSnapshotToJSON, } from './InstructionSnapshot';
 import { WorkflowRunnerTypeFromJSON, WorkflowRunnerTypeToJSON, } from './WorkflowRunnerType';
 export const WorkflowRunSnapshotPropertyValidationAttributesMap = {};
 /**
@@ -52,7 +53,7 @@ export function WorkflowRunSnapshotFromJSONTyped(json, ignoreDiscriminator) {
         'userId': json['user_id'],
         'maxRunDurationSeconds': json['max_run_duration_seconds'],
         'sources': (json['sources'].map(ABCDPathSnapshotFromJSON)),
-        'instructions': (json['instructions'].map(ABCDPathSnapshotFromJSON)),
+        'instructions': (json['instructions'].map(InstructionSnapshotFromJSON)),
         'outputs': (json['outputs'].map(ABCDPathSnapshotFromJSON)),
         'template': ABCDPathSnapshotFromJSON(json['template']),
     };
@@ -71,7 +72,7 @@ export function WorkflowRunSnapshotToJSONTyped(value, ignoreDiscriminator = fals
         'user_id': value['userId'],
         'max_run_duration_seconds': value['maxRunDurationSeconds'],
         'sources': (value['sources'].map(ABCDPathSnapshotToJSON)),
-        'instructions': (value['instructions'].map(ABCDPathSnapshotToJSON)),
+        'instructions': (value['instructions'].map(InstructionSnapshotToJSON)),
         'outputs': (value['outputs'].map(ABCDPathSnapshotToJSON)),
         'template': ABCDPathSnapshotToJSON(value['template']),
     };

package/dist/esm/models/WorkflowRunnerType.d.ts

@@ -15,6 +15,7 @@
  */
 export declare const WorkflowRunnerType: {
     readonly SelfHosted: "SELF_HOSTED";
+    readonly KsInternal: "KS_INTERNAL";
 };
 export type WorkflowRunnerType = typeof WorkflowRunnerType[keyof typeof WorkflowRunnerType];
 export declare function instanceOfWorkflowRunnerType(value: any): boolean;

package/dist/esm/models/WorkflowRunnerType.js

@@ -16,7 +16,8 @@
  * @export
  */
 export const WorkflowRunnerType = {
-    SelfHosted: 'SELF_HOSTED'
+    SelfHosted: 'SELF_HOSTED',
+    KsInternal: 'KS_INTERNAL'
 };
 export function instanceOfWorkflowRunnerType(value) {
     for (const key in WorkflowRunnerType) {

package/dist/esm/models/index.d.ts

@@ -74,6 +74,7 @@ export * from './ImageTaxonomy';
 export * from './InformationStatistics';
 export * from './IngestDocumentResponse';
 export * from './IngestionMode';
+export * from './InstructionSnapshot';
 export * from './InviteLinkSettingsRequest';
 export * from './InviteLinkSettingsResponse';
 export * from './InviteResponse';

package/dist/esm/models/index.js

@@ -76,6 +76,7 @@ export * from './ImageTaxonomy';
 export * from './InformationStatistics';
 export * from './IngestDocumentResponse';
 export * from './IngestionMode';
+export * from './InstructionSnapshot';
 export * from './InviteLinkSettingsRequest';
 export * from './InviteLinkSettingsResponse';
 export * from './InviteResponse';

package/dist/models/CreateWorkflowDefinitionRequest.d.ts

@@ -13,6 +13,13 @@ import type { SelfHostedRunnerConfig } from './SelfHostedRunnerConfig';
 import type { WorkflowRunnerType } from './WorkflowRunnerType';
 /**
  * Create a new workflow definition.
+ *
+ * ``instruction_path_part_ids`` semantics depend on ``runner_type``:
+ *
+ * - ``KS_INTERNAL``: must be empty (``[]``); the server auto-provisions a
+ *   single ``instruction.md`` and stores ``[doc.path_part_id]``.
+ * - ``SELF_HOSTED``: caller-supplied list of one-or-more document
+ *   PathPart IDs. Must contain at least one entry.
  * @export
  * @interface CreateWorkflowDefinitionRequest
  */
@@ -58,7 +65,7 @@ export interface CreateWorkflowDefinitionRequest {
      * @type {Array<string>}
      * @memberof CreateWorkflowDefinitionRequest
      */
-    instructionPathPartIds: Array<string>;
+    instructionPathPartIds?: Array<string>;
     /**
      *
      * @type {Array<string>}

package/dist/models/CreateWorkflowDefinitionRequest.js

@@ -38,7 +38,6 @@ exports.CreateWorkflowDefinitionRequestPropertyValidationAttributesMap = {
     },
     instructionPathPartIds: {
         maxItems: 20,
-        minItems: 1,
         uniqueItems: false,
     },
     outputPathPartIds: {
@@ -57,8 +56,6 @@ function instanceOfCreateWorkflowDefinitionRequest(value) {
         return false;
     if (!('sourcePathPartIds' in value) || value['sourcePathPartIds'] === undefined)
         return false;
-    if (!('instructionPathPartIds' in value) || value['instructionPathPartIds'] === undefined)
-        return false;
     if (!('outputPathPartIds' in value) || value['outputPathPartIds'] === undefined)
         return false;
     return true;
@@ -77,7 +74,7 @@ function CreateWorkflowDefinitionRequestFromJSONTyped(json, ignoreDiscriminator)
         'runnerConfig': json['runner_config'] == null ? undefined : (0, SelfHostedRunnerConfig_1.SelfHostedRunnerConfigFromJSON)(json['runner_config']),
         'maxRunDurationSeconds': json['max_run_duration_seconds'] == null ? undefined : json['max_run_duration_seconds'],
         'sourcePathPartIds': json['source_path_part_ids'],
-        'instructionPathPartIds': json['instruction_path_part_ids'],
+        'instructionPathPartIds': json['instruction_path_part_ids'] == null ? undefined : json['instruction_path_part_ids'],
         'outputPathPartIds': json['output_path_part_ids'],
         'templatePathPartId': json['template_path_part_id'] == null ? undefined : json['template_path_part_id'],
     };

package/dist/models/InstructionSnapshot.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { PartType } from './PartType';
+/**
+ * Snapshot of one instruction document, pinned at trigger time.
+ *
+ * The instruction file is the workflow's **contract**: the agent reads
+ * this exact ``document_version_id`` for the duration of the run, even
+ * if the document is edited mid-flight or after the run completes.
+ * Reproducibility and audit replay depend on this pinning.
+ * @export
+ * @interface InstructionSnapshot
+ */
+export interface InstructionSnapshot {
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    pathPartId: string;
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    materializedPath: string;
+    /**
+     *
+     * @type {PartType}
+     * @memberof InstructionSnapshot
+     */
+    partType: PartType;
+    /**
+     *
+     * @type {string}
+     * @memberof InstructionSnapshot
+     */
+    documentVersionId: string;
+}
+export declare const InstructionSnapshotPropertyValidationAttributesMap: {
+    [property: string]: {
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        maximum?: number;
+        exclusiveMaximum?: boolean;
+        minimum?: number;
+        exclusiveMinimum?: boolean;
+        multipleOf?: number;
+        maxItems?: number;
+        minItems?: number;
+        uniqueItems?: boolean;
+    };
+};
+/**
+ * Check if a given object implements the InstructionSnapshot interface.
+ */
+export declare function instanceOfInstructionSnapshot(value: object): value is InstructionSnapshot;
+export declare function InstructionSnapshotFromJSON(json: any): InstructionSnapshot;
+export declare function InstructionSnapshotFromJSONTyped(json: any, ignoreDiscriminator: boolean): InstructionSnapshot;
+export declare function InstructionSnapshotToJSON(json: any): InstructionSnapshot;
+export declare function InstructionSnapshotToJSONTyped(value?: InstructionSnapshot | null, ignoreDiscriminator?: boolean): any;