ValorIDEExecModule Migration Guide

Overview

ValorIDEExecModule is a retired compatibility shell. Version 1.0 accepted a caller-selected ValorIDE instance, arbitrary action, and opaque data, then manufactured a raw SWARM command envelope. Its optional response mode waited on process-local memory that had no production listener wiring, so a delivered command could still end as a local timeout. The path did not own immutable workflow materialization, placement, leases, fences, durable idempotency, approval evidence, or a canonical execution receipt. Its catalog behavior also incorrectly claimed that no network or external-data operation occurred.

Version 2.0 keeps the Java class, Spring bean, public method, and security annotations loadable so saved workflows and security coverage can inspect it. It is hidden from new Workflow Studio catalogs and always returns MODULE_RETIRED without reading, serializing, logging, dispatching, or waiting on legacy input.

Use ValkyrSwarmExecModule for remote execution. That module starts one authorized immutable WorkflowDeployment through the workflow-native remote execution service, which owns compatible node placement, a lease and fence, stable correlation-based idempotency, governed dispatch, and durable execution receipts.

Usage

1. Find saved tasks whose module type is ValorIDEExecModule.
2. Reconcile earlier commands against durable SWARM command and workflow execution receipts. A version 1.0 sent, timeout, or exception result is not proof of the remote outcome.
3. Express the desired remote action as a reviewed ValkyrAI Workflow and publish an immutable WorkflowDeployment version.
4. Confirm the target SWARM node advertises workflow.engine.execute-workflow and any additional required capabilities.
5. Replace the task with ValkyrSwarmExecModule, supply the immutable deployment UUID, and choose a stable business correlation ID.
6. Read back the canonical WorkflowExecution and receipt before allowing downstream side effects.

Inputs

The retired module preserves five legacy fields only for catalog compatibility:

Name	Type	Required	Version 2.0 behavior
targetInstanceId	string	no	Ignored; no agent is resolved or contacted.
action	string	no	Ignored; no command action is accepted.
data	object	no	Ignored; never serialized, dispatched, or logged.
timeout	integer	no	Ignored; no wait or timer is created.
waitForResponse	boolean	no	Ignored; no response future is registered.

The replacement requires workflowDeploymentId and correlationId. It accepts typed workflow inputs, optional providerKind (lm-studio or ollama), and an optional exact preferredSwarmInstanceId. Placement restrictions such as environment, privacy zone, trust, latency, cost, and required capabilities remain workflow-native constraints rather than opaque command data.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, and migration guidance.

It never returns the legacy target, action, data, credentials, command ID, response, exception text, or timeout value.

ValkyrSwarmExecModule returns the canonical workflow execution, deployment and version IDs, selected runner and SWARM instance, execution and dispatch states, command and receipt references, lease fence, reuse indicator, and any bounded rejection code that is present.

IntegrationAccount Requirements

No IntegrationAccount is required or read by the retired module. Version 2.0 performs no provider or network operation.

The replacement also does not accept raw provider secrets in workflow input. Provider access used inside the deployed workflow must be declared by that workflow's concrete modules and resolved through their own authorized IntegrationAccount contracts. A SWARM node's registration and capability grants are platform state, not reusable credentials to embed in inputs.

Configuration

There is no active configuration for ValorIDEExecModule version 2.0. Legacy fields are ignored.

A minimal replacement task input is:

{
  "workflowDeploymentId": "7bc3117d-13c2-4bc8-8f86-0cab78eddb2a",
  "correlationId": "customer-42:repo-a:validation-17",
  "inputs": {
    "repositoryRef": "sha256:8d10c9f4...",
    "validationProfile": "java-test"
  },
  "preferredSwarmInstanceId": "valoride-tenant-1"
}

Use a complete immutable repository or artifact reference in production. Do not put shell text, environment variables, access tokens, or unrestricted host paths in replacement inputs.

Operations

ValorIDEExecModule supports one compatibility operation: reject execution and identify ValkyrSwarmExecModule as the migration target.

The replacement supports one semantic operation: start or reuse the exact immutable remote workflow identified by workflowDeploymentId plus correlationId. The remote execution service, not the caller, selects or validates the workflow runner, materializes the immutable version, acquires the lease and fence, dispatches the governed command, and records the receipt.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace or remove the task; retrying cannot restore raw dispatch.
Legacy input contains sensitive data	Input is ignored and absent from output and logs.	Remove it from the saved task and rotate exposed credentials if prior handling is uncertain.
Prior result was sent or timeout	Remote outcome remains unproven.	Reconcile durable SWARM and workflow receipts before another action.
Deployment UUID is absent or invalid	Replacement rejects before placement.	Publish and authorize an immutable WorkflowDeployment.
No compatible runner exists	Replacement returns a bounded placement rejection.	Register a healthy node with the exact required capabilities; do not fall back to raw commands.
Correlation ID is reused for different semantics	Canonical idempotency checks reject or reuse the original operation.	Derive the key from the stable business operation, not a random retry.
Approval or policy evidence is missing	Protected execution remains blocked.	Complete the canonical approval flow and retry with the durable evidence reference.

Example

A saved legacy task reaches the compatibility shell:

{
  "targetInstanceId": "valoride-1",
  "action": "code.execute",
  "data": {"command": "npm test"},
  "timeout": 30000,
  "waitForResponse": true
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "ValorIDEExecModule is retired; use ValkyrSwarmExecModule with an immutable WorkflowDeployment",
    "retryable": false,
    "migrationTargets": ["ValkyrSwarmExecModule"],
    "requiredAction": "Create an authorized WorkflowDeployment and invoke ValkyrSwarmExecModule with a stable correlationId"
  }
}

Notes

• Pagination: neither the compatibility response nor one remote-workflow start paginates. Inspect durable execution history through its bounded API instead of embedding history in module output.
• Limits: the shell returns immediately. The replacement bounds typed inputs, placement candidates, cost, latency, capabilities, execution state, and receipt material according to the remote workflow contract.
• Idempotency: version 2.0 is deterministic and side-effect free. Version 1.0 was not idempotent because a retry created a new command UUID. The replacement uses the stable correlationId and immutable deployment identity.
• API constraints: the retired module makes no API or SWARM call. The replacement requires an authorized deployment and a compatible node advertising workflow.engine.execute-workflow.
• Logging and secrets: version 2.0 logs only that dispatch was blocked. It never logs input, response data, target identity, command content, credentials, or exception text.
• Destructive behavior: the shell performs none. Side effects inside the replacement workflow must remain explicitly declared, approval-gated where required, and reconciled through durable module and workflow receipts.
• Runtime deployment: merged source and published documentation do not update the backend serving /v1/modules/metadata. Workflow Studio will continue to report version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, input non-disclosure, repeatability, annotation completeness, discovery exclusion, security-annotation preservation, and direct compatibility lookup. They do not dispatch a SWARM command or run a remote workflow.