@knowledge-stack/ksapi 1.81.0 → 1.82.0

package/dist/models/InstructionSnapshot.js

@@ -0,0 +1,65 @@
+"use strict";
+/* 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstructionSnapshotPropertyValidationAttributesMap = void 0;
+exports.instanceOfInstructionSnapshot = instanceOfInstructionSnapshot;
+exports.InstructionSnapshotFromJSON = InstructionSnapshotFromJSON;
+exports.InstructionSnapshotFromJSONTyped = InstructionSnapshotFromJSONTyped;
+exports.InstructionSnapshotToJSON = InstructionSnapshotToJSON;
+exports.InstructionSnapshotToJSONTyped = InstructionSnapshotToJSONTyped;
+const PartType_1 = require("./PartType");
+exports.InstructionSnapshotPropertyValidationAttributesMap = {};
+/**
+ * Check if a given object implements the InstructionSnapshot interface.
+ */
+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;
+}
+function InstructionSnapshotFromJSON(json) {
+    return InstructionSnapshotFromJSONTyped(json, false);
+}
+function InstructionSnapshotFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        'pathPartId': json['path_part_id'],
+        'materializedPath': json['materialized_path'],
+        'partType': (0, PartType_1.PartTypeFromJSON)(json['part_type']),
+        'documentVersionId': json['document_version_id'],
+    };
+}
+function InstructionSnapshotToJSON(json) {
+    return InstructionSnapshotToJSONTyped(json, false);
+}
+function InstructionSnapshotToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        'path_part_id': value['pathPartId'],
+        'materialized_path': value['materializedPath'],
+        'part_type': (0, PartType_1.PartTypeToJSON)(value['partType']),
+        'document_version_id': value['documentVersionId'],
+    };
+}

package/dist/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/models/InvokeWorkflowRequest.js

@@ -23,6 +23,10 @@ exports.InvokeWorkflowRequestPropertyValidationAttributesMap = {
     idempotencyKey: {
         maxLength: 255,
     },
+    inputPathPartIds: {
+        maxItems: 50,
+        uniqueItems: false,
+    },
 };
 /**
  * Check if a given object implements the InvokeWorkflowRequest interface.
@@ -39,6 +43,7 @@ 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'],
     };
 }
 function InvokeWorkflowRequestToJSON(json) {
@@ -50,5 +55,6 @@ function InvokeWorkflowRequestToJSONTyped(value, ignoreDiscriminator = false) {
     }
     return {
         'idempotency_key': value['idempotencyKey'],
+        'input_path_part_ids': value['inputPathPartIds'],
     };
 }

package/dist/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/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/models/WorkflowRunResponse.js

@@ -45,6 +45,10 @@ 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)
@@ -68,6 +72,8 @@ function WorkflowRunResponseFromJSONTyped(json, ignoreDiscriminator) {
         'completedAt': (json['completed_at'] == null ? null : new Date(json['completed_at'])),
         'runSnapshot': (0, WorkflowRunSnapshot_1.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'])),
     };
@@ -89,6 +95,8 @@ function WorkflowRunResponseToJSONTyped(value, ignoreDiscriminator = false) {
         'completed_at': value['completedAt'] == null ? value['completedAt'] : value['completedAt'].toISOString(),
         'run_snapshot': (0, WorkflowRunSnapshot_1.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/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/models/WorkflowRunSnapshot.js

@@ -20,6 +20,7 @@ exports.WorkflowRunSnapshotFromJSONTyped = WorkflowRunSnapshotFromJSONTyped;
 exports.WorkflowRunSnapshotToJSON = WorkflowRunSnapshotToJSON;
 exports.WorkflowRunSnapshotToJSONTyped = WorkflowRunSnapshotToJSONTyped;
 const ABCDPathSnapshot_1 = require("./ABCDPathSnapshot");
+const InstructionSnapshot_1 = require("./InstructionSnapshot");
 const WorkflowRunnerType_1 = require("./WorkflowRunnerType");
 exports.WorkflowRunSnapshotPropertyValidationAttributesMap = {};
 /**
@@ -60,7 +61,7 @@ function WorkflowRunSnapshotFromJSONTyped(json, ignoreDiscriminator) {
         'userId': json['user_id'],
         'maxRunDurationSeconds': json['max_run_duration_seconds'],
         'sources': (json['sources'].map(ABCDPathSnapshot_1.ABCDPathSnapshotFromJSON)),
-        'instructions': (json['instructions'].map(ABCDPathSnapshot_1.ABCDPathSnapshotFromJSON)),
+        'instructions': (json['instructions'].map(InstructionSnapshot_1.InstructionSnapshotFromJSON)),
         'outputs': (json['outputs'].map(ABCDPathSnapshot_1.ABCDPathSnapshotFromJSON)),
         'template': (0, ABCDPathSnapshot_1.ABCDPathSnapshotFromJSON)(json['template']),
     };
@@ -79,7 +80,7 @@ function WorkflowRunSnapshotToJSONTyped(value, ignoreDiscriminator = false) {
         'user_id': value['userId'],
         'max_run_duration_seconds': value['maxRunDurationSeconds'],
         'sources': (value['sources'].map(ABCDPathSnapshot_1.ABCDPathSnapshotToJSON)),
-        'instructions': (value['instructions'].map(ABCDPathSnapshot_1.ABCDPathSnapshotToJSON)),
+        'instructions': (value['instructions'].map(InstructionSnapshot_1.InstructionSnapshotToJSON)),
         'outputs': (value['outputs'].map(ABCDPathSnapshot_1.ABCDPathSnapshotToJSON)),
         'template': (0, ABCDPathSnapshot_1.ABCDPathSnapshotToJSON)(value['template']),
     };

package/dist/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/models/WorkflowRunnerType.js

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

package/dist/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/models/index.js

@@ -92,6 +92,7 @@ __exportStar(require("./ImageTaxonomy"), exports);
 __exportStar(require("./InformationStatistics"), exports);
 __exportStar(require("./IngestDocumentResponse"), exports);
 __exportStar(require("./IngestionMode"), exports);
+__exportStar(require("./InstructionSnapshot"), exports);
 __exportStar(require("./InviteLinkSettingsRequest"), exports);
 __exportStar(require("./InviteLinkSettingsResponse"), exports);
 __exportStar(require("./InviteResponse"), exports);

package/docs/CreateWorkflowDefinitionRequest.md

@@ -1,7 +1,7 @@
 
 # CreateWorkflowDefinitionRequest
 
-Create a new workflow definition.
+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.
 
 ## Properties
 

package/docs/InstructionSnapshot.md

@@ -0,0 +1,41 @@
+
+# InstructionSnapshot
+
+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.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`pathPartId` | string
+`materializedPath` | string
+`partType` | [PartType](PartType.md)
+`documentVersionId` | string
+
+## Example
+
+```typescript
+import type { InstructionSnapshot } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "pathPartId": null,
+  "materializedPath": null,
+  "partType": null,
+  "documentVersionId": null,
+} satisfies InstructionSnapshot
+
+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 InstructionSnapshot
+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/InvokeWorkflowRequest.md

@@ -8,6 +8,7 @@ Request body for invoking a workflow definition.
 Name | Type
 ------------ | -------------
 `idempotencyKey` | string
+`inputPathPartIds` | Array<string>
 
 ## Example
 
@@ -17,6 +18,7 @@ import type { InvokeWorkflowRequest } from '@knowledge-stack/ksapi'
 // TODO: Update the object below with actual values
 const example = {
   "idempotencyKey": null,
+  "inputPathPartIds": null,
 } satisfies InvokeWorkflowRequest
 
 console.log(example)

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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledge-stack/ksapi",
-  "version": "1.81.0",
+  "version": "1.82.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> {

package/src/models/CreateWorkflowDefinitionRequest.ts

@@ -30,6 +30,13 @@ import {
 
 /**
  * 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
  */
@@ -75,7 +82,7 @@ export interface CreateWorkflowDefinitionRequest {
      * @type {Array<string>}
      * @memberof CreateWorkflowDefinitionRequest
      */
-    instructionPathPartIds: Array<string>;
+    instructionPathPartIds?: Array<string>;
     /**
      * 
      * @type {Array<string>}
@@ -122,7 +129,6 @@ export const CreateWorkflowDefinitionRequestPropertyValidationAttributesMap: {
     },
     instructionPathPartIds: {
         maxItems: 20,
-        minItems: 1,
         uniqueItems: false,
     },
     outputPathPartIds: {
@@ -140,7 +146,6 @@ export function instanceOfCreateWorkflowDefinitionRequest(value: object): value
     if (!('name' in value) || value['name'] === undefined) return false;
     if (!('runnerType' in value) || value['runnerType'] === undefined) 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;
 }
@@ -161,7 +166,7 @@ export function CreateWorkflowDefinitionRequestFromJSONTyped(json: any, ignoreDi
         '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/src/models/InstructionSnapshot.ts

@@ -0,0 +1,125 @@
+/* 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 { mapValues } from '../runtime';
+import type { PartType } from './PartType';
+import {
+    PartTypeFromJSON,
+    PartTypeFromJSONTyped,
+    PartTypeToJSON,
+    PartTypeToJSONTyped,
+} 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 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 function instanceOfInstructionSnapshot(value: object): value is InstructionSnapshot {
+    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: any): InstructionSnapshot {
+    return InstructionSnapshotFromJSONTyped(json, false);
+}
+
+export function InstructionSnapshotFromJSONTyped(json: any, ignoreDiscriminator: boolean): InstructionSnapshot {
+    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: any): InstructionSnapshot {
+    return InstructionSnapshotToJSONTyped(json, false);
+}
+
+export function InstructionSnapshotToJSONTyped(value?: InstructionSnapshot | null, ignoreDiscriminator: boolean = false): any {
+    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/src/models/InvokeWorkflowRequest.ts

@@ -25,6 +25,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 const InvokeWorkflowRequestPropertyValidationAttributesMap: {
     [property: string]: {
@@ -44,6 +50,10 @@ export const InvokeWorkflowRequestPropertyValidationAttributesMap: {
     idempotencyKey: {
         maxLength: 255,
     },
+    inputPathPartIds: {
+        maxItems: 50,
+        uniqueItems: false,
+    },
 }
 
 
@@ -65,6 +75,7 @@ export function InvokeWorkflowRequestFromJSONTyped(json: any, ignoreDiscriminato
     return {
         
         'idempotencyKey': json['idempotency_key'] == null ? undefined : json['idempotency_key'],
+        'inputPathPartIds': json['input_path_part_ids'] == null ? undefined : json['input_path_part_ids'],
     };
 }
 
@@ -80,6 +91,7 @@ export function InvokeWorkflowRequestToJSONTyped(value?: InvokeWorkflowRequest |
     return {
         
         'idempotency_key': value['idempotencyKey'],
+        'input_path_part_ids': value['inputPathPartIds'],
     };
 }