@twin.org/dataspace-models 0.9.1 → 0.9.2-next.2

package/dist/types/models/api/controlPlane/IAppDatasetUpdateRequest.d.ts

@@ -25,5 +25,10 @@ export interface IAppDatasetUpdateRequest {
          * The dataset payload.
          */
         dataset: IDataspaceProtocolDataset;
+        /**
+         * Optional idle window (ms) overriding the node-level idle policy for this
+         * dataset's PULL transfers; 0 disables it for this dataset.
+         */
+        transferIdleTimeoutMs?: number;
     };
 }

package/dist/types/models/controlPlane/IDataspaceAppDataset.d.ts

@@ -15,6 +15,11 @@ export interface IDataspaceAppDataset {
      * The dataset payload.
      */
     dataset: IDataspaceProtocolDataset;
+    /**
+     * Idle window (ms) for this dataset's PULL transfers, overriding the node-level
+     * providerTransferIdleTimeoutMs; 0 disables the idle policy for this dataset.
+     */
+    transferIdleTimeoutMs?: number;
     /**
      * Creation timestamp (ISO string).
      */

package/dist/types/models/controlPlane/IDataspaceControlPlaneComponent.d.ts

@@ -1,8 +1,9 @@
 import type { IComponent } from "@twin.org/core";
-import type { IDataspaceProtocolContractNegotiation, IDataspaceProtocolContractNegotiationError, IDataspaceProtocolDataset, IDataspaceProtocolTransferCompletionMessage, IDataspaceProtocolTransferError, IDataspaceProtocolTransferProcess, IDataspaceProtocolTransferRequestMessage, IDataspaceProtocolTransferStartMessage, IDataspaceProtocolTransferSuspensionMessage, IDataspaceProtocolTransferTerminationMessage, IDataspaceProtocolVersionResponse } from "@twin.org/standards-dataspace-protocol";
+import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolContractNegotiation, IDataspaceProtocolContractNegotiationError, IDataspaceProtocolDataset, IDataspaceProtocolTransferCompletionMessage, IDataspaceProtocolTransferError, IDataspaceProtocolTransferProcess, IDataspaceProtocolTransferRequestMessage, IDataspaceProtocolTransferStartMessage, IDataspaceProtocolTransferSuspensionMessage, IDataspaceProtocolTransferTerminationMessage, IDataspaceProtocolVersionResponse } from "@twin.org/standards-dataspace-protocol";
 import type { IDataspaceAppDataset } from "./IDataspaceAppDataset.js";
 import type { INegotiationCallback } from "./INegotiationCallback.js";
 import type { ITransferCallback } from "./ITransferCallback.js";
+import type { ITransferQueryResult } from "./ITransferQueryResult.js";
 /**
  * Dataspace Control Plane Component interface.
  * Implements Eclipse Dataspace Protocol (DSP) specifications:
@@ -245,6 +246,25 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.
      */
     getTransferProcess(pid: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Query Transfer Processes by agreement id.
+     * Lets a caller check whether transfers already exist for an agreement
+     * (e.g. before initiating a new one) without knowing any process ids.
+     *
+     * Role Performed: Consumer / Provider
+     * Called by: Consumer orchestration before requesting a new transfer, or either
+     * party inspecting the transfers attached to an agreement on their side.
+     *
+     * Results are limited to transfers where the authenticated caller is a party
+     * (consumer or provider identity). A returned dataAddress is a point-in-time copy;
+     * if its token has expired the data plane rejects it and a new start is required.
+     * @param agreementId The agreement id to look up transfer processes for.
+     * @param state Optional filter to a single transfer process state.
+     * @param cursor Optional pagination cursor from a previous result page.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns The matching transfer processes and a pagination cursor when more pages exist, empty when none match.
+     */
+    queryDataTransfer(agreementId: string, state: DataspaceProtocolTransferProcessStateType | undefined, cursor: string | undefined, trustPayload: unknown): Promise<ITransferQueryResult>;
     /**
      * Register an app dataset for a dataspace app, owned by the calling tenant.
      * @param id Optional explicit id. If omitted, derived from `dataset["@id"]`
@@ -252,9 +272,14 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @param appId The dataspace app this dataset belongs to (matches
      * `DataspaceAppFactory` registration name).
      * @param dataset The dataset payload (may omit system-stamped fields).
+     * @param options Optional dataset settings.
+     * @param options.transferIdleTimeoutMs Optional idle window (ms) overriding the node-level idle
+     * policy for this dataset's PULL transfers; 0 disables it for this dataset.
      * @returns The resolved dataset id.
      */
-    createAppDataset(id: string | undefined, appId: string, dataset: IDataspaceProtocolDataset): Promise<string>;
+    createAppDataset(id: string | undefined, appId: string, dataset: IDataspaceProtocolDataset, options?: {
+        transferIdleTimeoutMs?: number;
+    }): Promise<string>;
     /**
      * Get an app dataset record owned by the calling tenant.
      * @param id The stored app dataset id.
@@ -276,9 +301,14 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @param id The stored app dataset id.
      * @param appId The dataspace app this dataset belongs to.
      * @param dataset The dataset payload.
+     * @param options Optional dataset settings.
+     * @param options.transferIdleTimeoutMs Optional idle window (ms) overriding the node-level idle
+     * policy for this dataset's PULL transfers; 0 disables it for this dataset.
      * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.
      */
-    updateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;
+    updateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset, options?: {
+        transferIdleTimeoutMs?: number;
+    }): Promise<void>;
     /**
      * Delete an app dataset record owned by the calling tenant.
      * @param id The stored app dataset id.

package/dist/types/models/controlPlane/ITransferCallback.d.ts

@@ -49,9 +49,9 @@ export interface ITransferCallback {
      */
     onFailed?(consumerPid: string, reason: string): Promise<void>;
     /**
-     * Called when the transfer times out, i.e. the provider did not progress it (it sat in REQUESTED)
-     * within the configured window. Optional: implement it to be notified specifically of a non-response
-     * (otherwise the control plane falls back to `onFailed(consumerPid, "transferStalled")`).
+     * Called when the transfer times out: a consumer-side REQUESTED transfer the provider never
+     * progressed, or a provider-side STARTED transfer idle beyond the configured window. Optional:
+     * otherwise the control plane falls back to `onFailed` with the timeout reason.
      * @param consumerPid The consumer-side process ID.
      * @returns Nothing.
      */

package/dist/types/models/controlPlane/ITransferProcess.d.ts

@@ -76,10 +76,8 @@ export interface ITransferProcess {
      */
     format?: string;
     /**
-     * Data address for consumer-initiated push transfers (HttpData-PUSH).
-     * Contains the consumer's /inbox endpoint as supplied in the TransferRequestMessage.
-     * Absent for PULL (HttpData-PULL) and provider-initiated push (HttpData-POST),
-     * where the consumer deliberately omits a dataAddress.
+     * Data address for the transfer: the consumer's inbox for PUSH, or the
+     * provider-built address persisted at start for PULL/POST; may expire while STARTED.
      */
     dataAddress?: IDataspaceProtocolDataAddress;
     /**

package/dist/types/models/controlPlane/ITransferQueryResult.d.ts

@@ -0,0 +1,14 @@
+import type { ITransferProcess } from "./ITransferProcess.js";
+/**
+ * Result of querying Transfer Processes by agreement.
+ */
+export interface ITransferQueryResult {
+    /**
+     * The transfer processes matching the query, empty when none match.
+     */
+    transfers: ITransferProcess[];
+    /**
+     * Pagination cursor for retrieving the next page, omitted when no more results exist.
+     */
+    cursor?: string;
+}

package/dist/types/models/controlPlane/transferTerminationCode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Machine-readable codes set on provider-initiated TransferTerminationMessages
+ * by the control plane's transfer lifecycle policies.
+ */
+export declare const TransferTerminationCode: {
+    /**
+     * A Provider-side STARTED transfer had no data-plane activity within the configured idle window.
+     */
+    readonly IdleTimeout: "idleTimeout";
+};
+/**
+ * Type for TransferTerminationCode values.
+ */
+export type TransferTerminationCode = (typeof TransferTerminationCode)[keyof typeof TransferTerminationCode];

package/docs/changelog.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.9.2-next.2](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.9.2-next.1...dataspace-models-v0.9.2-next.2) (2026-07-30)
+
+
+### Miscellaneous Chores
+
+* **dataspace-models:** Synchronize repo versions
+
+## [0.9.2-next.1](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.9.2-next.0...dataspace-models-v0.9.2-next.1) (2026-07-28)
+
+
+### Features
+
+* add consumer transfer callbacks and startDataTransfer convenience method ([#151](https://github.com/iotaledger/twin-dataspace/issues/151)) ([0ab66c3](https://github.com/iotaledger/twin-dataspace/commit/0ab66c3636fd1f98f89baca1e99764d77c6f91d9))
+* add dataspace transfer format ([#111](https://github.com/iotaledger/twin-dataspace/issues/111)) ([f59ff5e](https://github.com/iotaledger/twin-dataspace/commit/f59ff5ef10d261d1cebbf5c6bb0689e74a10738a))
+* add inline tasks and concurrent options ([#104](https://github.com/iotaledger/twin-dataspace/issues/104)) ([2227a21](https://github.com/iotaledger/twin-dataspace/commit/2227a212d906f58ba77850c79bb20bf2cb7195a8))
+* add telemetry metrics to dataspace control and data plane services ([#212](https://github.com/iotaledger/twin-dataspace/issues/212)) ([b5b0248](https://github.com/iotaledger/twin-dataspace/commit/b5b024899ed12c0f639c5d51aefa3e509753eac6))
+* add transferStarted provider method to start a data transfer ([#206](https://github.com/iotaledger/twin-dataspace/issues/206)) ([3ec2dc8](https://github.com/iotaledger/twin-dataspace/commit/3ec2dc8943c8531cd8d8e4ab07cb970ef7b11090))
+* add well known versions endpoint ([#251](https://github.com/iotaledger/twin-dataspace/issues/251)) ([4b4cbe9](https://github.com/iotaledger/twin-dataspace/commit/4b4cbe91a40980481dad6e0650c1ee73c53ae360))
+* align all config times to ms ([40238d5](https://github.com/iotaledger/twin-dataspace/commit/40238d59a2b45caedc01792b682ce7206815dfd1))
+* cross-node transfer callbacks and DataTransferManager auto-start ([#199](https://github.com/iotaledger/twin-dataspace/issues/199)) ([1089aa3](https://github.com/iotaledger/twin-dataspace/commit/1089aa344e3598e382f37a82ca03230c5cf6cacd))
+* docs update ([8b44c7a](https://github.com/iotaledger/twin-dataspace/commit/8b44c7a75afb8d377a6f606616f8a78d58439ab4))
+* endpoint encryption + getDatasetTargets multi-target fix ([#112](https://github.com/iotaledger/twin-dataspace/issues/112)) ([3288941](https://github.com/iotaledger/twin-dataspace/commit/328894113c19c7402f7d00dfa77b6a97ae40ca91))
+* get activity log add trust payload ([#201](https://github.com/iotaledger/twin-dataspace/issues/201)) ([cdb5486](https://github.com/iotaledger/twin-dataspace/commit/cdb5486942c1b94ddf6435236b9b9d190bea0407))
+* implement DSP push transfer mode ([#109](https://github.com/iotaledger/twin-dataspace/issues/109)) ([71f5fee](https://github.com/iotaledger/twin-dataspace/commit/71f5feec1d92dfec8ed6899c951809818e1bf2a3))
+* improve error handling and component usage ([544e20e](https://github.com/iotaledger/twin-dataspace/commit/544e20e640d6f09266942bfc698aead6227a7769))
+* improve open-api examples ([1368dbe](https://github.com/iotaledger/twin-dataspace/commit/1368dbed5c36e074b4854942304a19b9ce51e088))
+* improve validation ([#82](https://github.com/iotaledger/twin-dataspace/issues/82)) ([8bfaf7b](https://github.com/iotaledger/twin-dataspace/commit/8bfaf7b830f89b63575f8a51ee96bd8ac4da02f4))
+* organization identifiers ([#188](https://github.com/iotaledger/twin-dataspace/issues/188)) ([af643d3](https://github.com/iotaledger/twin-dataspace/commit/af643d3bb7f212d6cbb672e362a9e1bbe886d1a5))
+* provider-side idle lifecycle policy for STARTED data transfers ([#284](https://github.com/iotaledger/twin-dataspace/issues/284)) ([a9312ef](https://github.com/iotaledger/twin-dataspace/commit/a9312ef7573a92805c99cb2a314e8b289a6ab195))
+* provider-side transfer auto-start and negotiation/transfer timeout callbacks ([#227](https://github.com/iotaledger/twin-dataspace/issues/227)) ([619d858](https://github.com/iotaledger/twin-dataspace/commit/619d858e8d44e59744dc8a0f73e06be976932b53))
+* query existing data transfers by agreement to avoid duplicate preparations ([#289](https://github.com/iotaledger/twin-dataspace/issues/289)) ([53fe251](https://github.com/iotaledger/twin-dataspace/commit/53fe2516b2287b6b6a7a6ca6fc6063ea4a446cf0))
+* remove datasetsHandled method from apps ([9fdc950](https://github.com/iotaledger/twin-dataspace/commit/9fdc95018d38ab49c4a1094642be2ee83ee0e4cd))
+* remove hosting component ([#209](https://github.com/iotaledger/twin-dataspace/issues/209)) ([5e19328](https://github.com/iotaledger/twin-dataspace/commit/5e1932823aa8a0f88f559f096610b9df1f3b8615))
+* rename completed callback ([#147](https://github.com/iotaledger/twin-dataspace/issues/147)) ([f62baad](https://github.com/iotaledger/twin-dataspace/commit/f62baad0ff444e2913439b12dcd06d20c9a4f6a4))
+* resolve DSP transfer flow bugs for cross-node communication ([#76](https://github.com/iotaledger/twin-dataspace/issues/76)) ([506a45c](https://github.com/iotaledger/twin-dataspace/commit/506a45c94e63d5f958b1fc7131adfe452c3e2974))
+* shortcut implicit trust ([#215](https://github.com/iotaledger/twin-dataspace/issues/215)) ([f9bcfea](https://github.com/iotaledger/twin-dataspace/commit/f9bcfeab8f069b62017502833c108b4ee3791414))
+* types update ([77c338e](https://github.com/iotaledger/twin-dataspace/commit/77c338e9244dcc7e3d597fdb06229513b1f13eac))
+* typescript 6 update ([340f10e](https://github.com/iotaledger/twin-dataspace/commit/340f10e4767f6285c694938944f7e044474f9aaa))
+* unification of the data exchange and the data space connector ([#57](https://github.com/iotaledger/twin-dataspace/issues/57)) ([df2644d](https://github.com/iotaledger/twin-dataspace/commit/df2644d989471e07dadd83d27bef736179e31bf4))
+* update DataspaceTransferFormat names ([2c9d424](https://github.com/iotaledger/twin-dataspace/commit/2c9d424a07b97346faa2124048c4675514d58109))
+
+
+### Bug Fixes
+
+* always verify trust in notifyActivity, no internal by ([#192](https://github.com/iotaledger/twin-dataspace/issues/192)) ([2cfc160](https://github.com/iotaledger/twin-dataspace/commit/2cfc16082a7c9d417f0b05f90f123e40f47d1e05))
+* avoid compaction of incoming activities ([#77](https://github.com/iotaledger/twin-dataspace/issues/77)) ([ff43d6a](https://github.com/iotaledger/twin-dataspace/commit/ff43d6a3e1563eb9cb185501134b2a53ae88787c))
+* docs ([652f4f2](https://github.com/iotaledger/twin-dataspace/commit/652f4f2fec8601bb3772e054b2c823f599ef68dc))
+* filtering query optional q ([#248](https://github.com/iotaledger/twin-dataspace/issues/248)) ([e9e8ff1](https://github.com/iotaledger/twin-dataspace/commit/e9e8ff1e1bb3b93f0960260c21a46d6f58dbfaa2))
+* implement missing trust check on negotiateAgreement ([#136](https://github.com/iotaledger/twin-dataspace/issues/136)) ([a3589c2](https://github.com/iotaledger/twin-dataspace/commit/a3589c279476d5450b68ea7c2790be7e3125bfe2))
+* missing dependencies ([54e9e9c](https://github.com/iotaledger/twin-dataspace/commit/54e9e9c474b61cce3b9a82f9ccec27c7f8133382))
+* retain cursor after pep enforcement ([#296](https://github.com/iotaledger/twin-dataspace/issues/296)) ([5198cd2](https://github.com/iotaledger/twin-dataspace/commit/5198cd29505ceffa532fa4fa18c97a5c8e78f663))
+* return 422/500 when inline activity processing fails ([#135](https://github.com/iotaledger/twin-dataspace/issues/135)) ([8635187](https://github.com/iotaledger/twin-dataspace/commit/863518724cb90af15edc5f456d9a93c6cad7d661))
+* throw not supported error for in-process only control plane methods ([#185](https://github.com/iotaledger/twin-dataspace/issues/185)) ([130f00a](https://github.com/iotaledger/twin-dataspace/commit/130f00a87412b34defde891855bee7aa3ac34130))
+
 ## [0.9.1](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.9.1...dataspace-models-v0.9.1) (2026-07-27)
 
 

package/docs/reference/classes/DataspaceAppDataset.md

@@ -62,6 +62,15 @@ opaque object and validated/populated at publish time.
 
 ***
 
+### transferIdleTimeoutMs? {#transferidletimeoutms}
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Idle window (ms) for this dataset's PULL transfers, overriding the node-level
+providerTransferIdleTimeoutMs; 0 disables the idle policy for this dataset.
+
+***
+
 ### dateCreated {#datecreated}
 
 > **dateCreated**: `string`

package/docs/reference/classes/DataspaceAppDatasetV0.md

@@ -0,0 +1,77 @@
+# Class: DataspaceAppDatasetV0
+
+Tenant-supplied Dataset shape persisted by the Control Plane, version 0.
+
+## Constructors
+
+### Constructor
+
+> **new DataspaceAppDatasetV0**(): `DataspaceAppDatasetV0`
+
+#### Returns
+
+`DataspaceAppDatasetV0`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the dataset.
+
+***
+
+### organizationIdentity {#organizationidentity}
+
+> **organizationIdentity**: `string`
+
+The identity of the organization that owns this entity.
+
+***
+
+### tenantId? {#tenantid}
+
+> `optional` **tenantId?**: `string`
+
+The tenant that owns this dataset, captured from the request context at
+write time. Optional — single-tenant nodes (no `TWIN_TENANT_ENABLED`)
+register datasets without a tenant context.
+
+***
+
+### appId {#appid}
+
+> **appId**: `string`
+
+The dataspace app that this dataset belongs to. Matches the app's
+registered name in `DataspaceAppFactory` (typically the app's URI).
+
+***
+
+### dataset {#dataset}
+
+> **dataset**: `object`
+
+The user-controlled JSON-LD dataset payload. Stored as an
+opaque object and validated/populated at publish time.
+
+#### Index Signature
+
+\[`key`: `string`\]: `unknown`
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+Creation timestamp (ISO string format).
+
+***
+
+### dateModified {#datemodified}
+
+> **dateModified**: `string`
+
+Last update timestamp (ISO string format).

package/docs/reference/classes/TransferProcess.md

@@ -152,4 +152,5 @@ Policies from the Agreement (stored as JSON).
 
 > `optional` **dataAddress?**: `IDataspaceProtocolDataAddress`
 
-Data address for push mode transfers (stored as JSON).
+Data address for the transfer (stored as JSON): the consumer's inbox for PUSH, or the
+provider-built address persisted at start for PULL/POST; may expire while STARTED.

package/docs/reference/classes/TransferRetrieval.md

@@ -0,0 +1,38 @@
+# Class: TransferRetrieval
+
+Records the consumer's first successful retrieval for a transfer.
+Written by the Data Plane, read by the Control Plane's one-shot policy sweep.
+
+## Constructors
+
+### Constructor
+
+> **new TransferRetrieval**(): `TransferRetrieval`
+
+#### Returns
+
+`TransferRetrieval`
+
+## Properties
+
+### consumerPid {#consumerpid}
+
+> **consumerPid**: `string`
+
+The consumer PID of the transfer, primary key.
+
+***
+
+### dateFirstRetrieved {#datefirstretrieved}
+
+> **dateFirstRetrieved**: `string`
+
+When the first successful retrieval happened (ISO string format).
+
+***
+
+### dateLastRetrieved {#datelastretrieved}
+
+> **dateLastRetrieved**: `string`
+
+When the most recent successful retrieval happened (ISO string format).

package/docs/reference/index.md

@@ -4,7 +4,9 @@
 
 - [DataspaceDataTypes](classes/DataspaceDataTypes.md)
 - [DataspaceAppDataset](classes/DataspaceAppDataset.md)
+- [DataspaceAppDatasetV0](classes/DataspaceAppDatasetV0.md)
 - [TransferProcess](classes/TransferProcess.md)
+- [TransferRetrieval](classes/TransferRetrieval.md)
 
 ## Interfaces
 
@@ -65,6 +67,7 @@
 - [ITransferCallback](interfaces/ITransferCallback.md)
 - [ITransferContext](interfaces/ITransferContext.md)
 - [ITransferProcess](interfaces/ITransferProcess.md)
+- [ITransferQueryResult](interfaces/ITransferQueryResult.md)
 - [ITransferContextResponse](interfaces/ITransferContextResponse.md)
 - [IDataspaceDataPlaneComponent](interfaces/IDataspaceDataPlaneComponent.md)
 
@@ -76,6 +79,7 @@
 - [DataRequestType](type-aliases/DataRequestType.md)
 - [DataspaceControlPlaneMetricIds](type-aliases/DataspaceControlPlaneMetricIds.md)
 - [TransferProcessRole](type-aliases/TransferProcessRole.md)
+- [TransferTerminationCode](type-aliases/TransferTerminationCode.md)
 - [DataspaceDataPlaneMetricIds](type-aliases/DataspaceDataPlaneMetricIds.md)
 - [DataspaceContexts](type-aliases/DataspaceContexts.md)
 - [DataspaceTransferFormat](type-aliases/DataspaceTransferFormat.md)
@@ -90,6 +94,7 @@
 - [DataspaceControlPlaneMetricIds](variables/DataspaceControlPlaneMetricIds.md)
 - [DataspaceControlPlaneMetrics](variables/DataspaceControlPlaneMetrics.md)
 - [TransferProcessRole](variables/TransferProcessRole.md)
+- [TransferTerminationCode](variables/TransferTerminationCode.md)
 - [DataspaceDataPlaneMetricIds](variables/DataspaceDataPlaneMetricIds.md)
 - [DataspaceDataPlaneMetrics](variables/DataspaceDataPlaneMetrics.md)
 - [DataspaceContexts](variables/DataspaceContexts.md)

package/docs/reference/interfaces/IAppDatasetCreateRequest.md

@@ -35,3 +35,10 @@ registered name in `DataspaceAppFactory` (typically the app's URI).
 
 The dataset payload. System-stamped fields like `dcterms:publisher`
 may be omitted — the Control Plane fills them in at publish time.
+
+#### transferIdleTimeoutMs?
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Optional idle window (ms) overriding the node-level idle policy for this
+dataset's PULL transfers; 0 disables it for this dataset.

package/docs/reference/interfaces/IAppDatasetUpdateRequest.md

@@ -36,3 +36,10 @@ update if the tenant wants to retarget the dataset.
 > **dataset**: `IDataspaceProtocolDataset`
 
 The dataset payload.
+
+#### transferIdleTimeoutMs?
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Optional idle window (ms) overriding the node-level idle policy for this
+dataset's PULL transfers; 0 disables it for this dataset.

package/docs/reference/interfaces/IDataspaceAppDataset.md

@@ -28,6 +28,15 @@ The dataset payload.
 
 ***
 
+### transferIdleTimeoutMs? {#transferidletimeoutms}
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Idle window (ms) for this dataset's PULL transfers, overriding the node-level
+providerTransferIdleTimeoutMs; 0 disables the idle policy for this dataset.
+
+***
+
 ### dateCreated {#datecreated}
 
 > **dateCreated**: `string`

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -550,9 +550,59 @@ Transfer Process (DSP compliant) with current state, or TransferError if the ope
 
 ***
 
+### queryDataTransfer() {#querydatatransfer}
+
+> **queryDataTransfer**(`agreementId`, `state`, `cursor`, `trustPayload`): `Promise`\<[`ITransferQueryResult`](ITransferQueryResult.md)\>
+
+Query Transfer Processes by agreement id.
+Lets a caller check whether transfers already exist for an agreement
+(e.g. before initiating a new one) without knowing any process ids.
+
+Role Performed: Consumer / Provider
+Called by: Consumer orchestration before requesting a new transfer, or either
+party inspecting the transfers attached to an agreement on their side.
+
+Results are limited to transfers where the authenticated caller is a party
+(consumer or provider identity). A returned dataAddress is a point-in-time copy;
+if its token has expired the data plane rejects it and a new start is required.
+
+#### Parameters
+
+##### agreementId
+
+`string`
+
+The agreement id to look up transfer processes for.
+
+##### state
+
+`DataspaceProtocolTransferProcessStateType` \| `undefined`
+
+Optional filter to a single transfer process state.
+
+##### cursor
+
+`string` \| `undefined`
+
+Optional pagination cursor from a previous result page.
+
+##### trustPayload
+
+`unknown`
+
+Trust payload containing authorization information (JWT, VC, etc.).
+
+#### Returns
+
+`Promise`\<[`ITransferQueryResult`](ITransferQueryResult.md)\>
+
+The matching transfer processes and a pagination cursor when more pages exist, empty when none match.
+
+***
+
 ### createAppDataset() {#createappdataset}
 
-> **createAppDataset**(`id`, `appId`, `dataset`): `Promise`\<`string`\>
+> **createAppDataset**(`id`, `appId`, `dataset`, `options?`): `Promise`\<`string`\>
 
 Register an app dataset for a dataspace app, owned by the calling tenant.
 
@@ -578,6 +628,17 @@ The dataspace app this dataset belongs to (matches
 
 The dataset payload (may omit system-stamped fields).
 
+##### options?
+
+Optional dataset settings.
+
+###### transferIdleTimeoutMs?
+
+`number`
+
+Optional idle window (ms) overriding the node-level idle
+policy for this dataset's PULL transfers; 0 disables it for this dataset.
+
 #### Returns
 
 `Promise`\<`string`\>
@@ -638,7 +699,7 @@ The stored app datasets and the next-page cursor if more exist.
 
 ### updateAppDataset() {#updateappdataset}
 
-> **updateAppDataset**(`id`, `appId`, `dataset`): `Promise`\<`void`\>
+> **updateAppDataset**(`id`, `appId`, `dataset`, `options?`): `Promise`\<`void`\>
 
 Update an app dataset record owned by the calling tenant.
 
@@ -662,6 +723,17 @@ The dataspace app this dataset belongs to.
 
 The dataset payload.
 
+##### options?
+
+Optional dataset settings.
+
+###### transferIdleTimeoutMs?
+
+`number`
+
+Optional idle window (ms) overriding the node-level idle
+policy for this dataset's PULL transfers; 0 disables it for this dataset.
+
 #### Returns
 
 `Promise`\<`void`\>

package/docs/reference/interfaces/ITransferCallback.md

@@ -174,9 +174,9 @@ Nothing.
 
 > `optional` **onTimeout**(`consumerPid`): `Promise`\<`void`\>
 
-Called when the transfer times out, i.e. the provider did not progress it (it sat in REQUESTED)
-within the configured window. Optional: implement it to be notified specifically of a non-response
-(otherwise the control plane falls back to `onFailed(consumerPid, "transferStalled")`).
+Called when the transfer times out: a consumer-side REQUESTED transfer the provider never
+progressed, or a provider-side STARTED transfer idle beyond the configured window. Optional:
+otherwise the control plane falls back to `onFailed` with the timeout reason.
 
 #### Parameters
 

package/docs/reference/interfaces/ITransferProcess.md

@@ -134,10 +134,8 @@ Specified by a Distribution for the Dataset associated with the Agreement.
 
 > `optional` **dataAddress?**: `IDataspaceProtocolDataAddress`
 
-Data address for consumer-initiated push transfers (HttpData-PUSH).
-Contains the consumer's /inbox endpoint as supplied in the TransferRequestMessage.
-Absent for PULL (HttpData-PULL) and provider-initiated push (HttpData-POST),
-where the consumer deliberately omits a dataAddress.
+Data address for the transfer: the consumer's inbox for PUSH, or the
+provider-built address persisted at start for PULL/POST; may expire while STARTED.
 
 ***
 

package/docs/reference/interfaces/ITransferQueryResult.md

@@ -0,0 +1,19 @@
+# Interface: ITransferQueryResult
+
+Result of querying Transfer Processes by agreement.
+
+## Properties
+
+### transfers {#transfers}
+
+> **transfers**: [`ITransferProcess`](ITransferProcess.md)[]
+
+The transfer processes matching the query, empty when none match.
+
+***
+
+### cursor? {#cursor}
+
+> `optional` **cursor?**: `string`
+
+Pagination cursor for retrieving the next page, omitted when no more results exist.

package/docs/reference/type-aliases/TransferTerminationCode.md

@@ -0,0 +1,5 @@
+# Type Alias: TransferTerminationCode
+
+> **TransferTerminationCode** = *typeof* [`TransferTerminationCode`](../variables/TransferTerminationCode.md)\[keyof *typeof* [`TransferTerminationCode`](../variables/TransferTerminationCode.md)\]
+
+Type for TransferTerminationCode values.

package/docs/reference/variables/TransferTerminationCode.md

@@ -0,0 +1,14 @@
+# Variable: TransferTerminationCode
+
+> `const` **TransferTerminationCode**: `object`
+
+Machine-readable codes set on provider-initiated TransferTerminationMessages
+by the control plane's transfer lifecycle policies.
+
+## Type Declaration
+
+### IdleTimeout {#idletimeout}
+
+> `readonly` **IdleTimeout**: `"idleTimeout"` = `"idleTimeout"`
+
+A Provider-side STARTED transfer had no data-plane activity within the configured idle window.