Map Inject Module

Overview

MapInjectModule version 2.0 adds a small deterministic fixture map to downstream workflow state. It is intended for test data, routing hints, feature flags, and other non-secret values that do not justify an external lookup.

The module is also the safe migration target for legacy debug-echo tasks. It does not print, log, publish, or transmit fixture content. It validates every fixture before producing output and rejects credential-like keys, workflow-control keys, oversized structures, and accidental state collisions.

Usage

1. Add Map Inject to a workflow before the task that needs static fixture values.
2. Put the values under the values configuration object.
3. Use descriptive fixture keys such as fixtureRegion or testOrderState.
4. Keep credentials and customer secrets in an appropriate IntegrationAccount or protected business object instead.
5. Leave overwriteExisting disabled unless the workflow intentionally replaces an existing state key.

Version 2 accepts a legacy flat moduleData object when no values object is present, but new workflows should use the canonical nested shape.

Inputs

Input	Required	Description
values	No	Runtime fixture object. It is used only when allowRuntimeValues is enabled and no configured values object exists.

Incoming workflow state is otherwise read only to detect top-level key collisions. The module never mutates its input map.

Outputs

Output	Description
status	success or error.
count	Number of injected top-level fixture keys on success.
injectedKeys	Ordered list of injected top-level keys.
injected	Bounded copy of the complete fixture object.
error	Safe validation code, message, and retryable:false on failure.
Dynamic top-level keys	Each accepted fixture entry is also emitted at the top level for downstream workflow compatibility.

IntegrationAccount Requirements

No IntegrationAccount is required or read. Map Inject performs no provider call and does not need authentication material.

Do not use it to store passwords, API keys, tokens, cookies, private keys, authorization headers, or other credentials. Credential-like keys are rejected at every nesting level.

Configuration

Field	Default	Description
values	{}	Static JSON fixture object. It may contain at most 64 top-level keys, 512 total nodes, arrays of at most 256 items, eight nesting levels, and 64 KiB of JSON.
overwriteExisting	false	Allows same-named incoming workflow-state keys to be replaced. Enable only after reviewing the collision deliberately.
allowRuntimeValues	false	Allows input.values as the fixture source when configured values are absent. This is an advanced, explicitly enabled path.

Top-level fixture keys must begin with a letter and contain at most 64 letters, digits, dots, underscores, or hyphens. Module result fields and workflow-control fields cannot be injected.

Operations

Map Inject exposes one local deterministic operation:

1. Resolve canonical configured values, explicitly allowed runtime values, or legacy flat module data in that order.
2. Validate names, credential markers, entry count, total size, array size, node count, text length, and nesting depth.
3. Compare fixture keys with incoming state and reject collisions unless overwriteExisting is true.
4. Emit the bounded fixture, summary fields, and top-level compatibility outputs.

The module performs no network, filesystem, process, database, logging-payload, event-broadcast, or credential operation.

Errors and Failure Modes

Code	Cause	Recovery
VALUES_REQUIRED	No non-empty configured, allowed runtime, or legacy fixture object was available.	Add a non-empty values object.
INVALID_VALUES	The selected fixture was not a JSON object or could not be normalized safely.	Supply a JSON-compatible object.
INVALID_KEY	A top-level or nested key violated the documented name bound.	Rename the key and retry.
RESERVED_KEY	A fixture attempted to set module result or workflow-control state.	Use a normal business or fixture key instead.
CREDENTIAL_KEY	A key appeared to contain password, secret, token, authorization, cookie, private-key, or API-key material.	Move credentials to a destination-bound IntegrationAccount; do not rename a secret merely to evade the check.
KEY_COLLISION	A fixture key already existed in incoming workflow state.	Rename it or explicitly review and enable overwriteExisting.
LIMIT_EXCEEDED	An entry, structure, array, text, depth, node-count, or JSON-size limit was exceeded.	Reduce or split the fixture. Use a durable object or file for larger data.

Failures clear any result from a previous invocation and return only status plus the safe error object. Fixture values are never copied into an error message.

Example

Configuration:

{
  "values": {
    "fixtureRegion": "us-west-2",
    "fixtureRetries": 2,
    "fixtureFlags": {
      "preview": true
    }
  },
  "overwriteExisting": false,
  "allowRuntimeValues": false
}

Expected result:

{
  "status": "success",
  "count": 3,
  "injectedKeys": [
    "fixtureRegion",
    "fixtureRetries",
    "fixtureFlags"
  ],
  "injected": {
    "fixtureRegion": "us-west-2",
    "fixtureRetries": 2,
    "fixtureFlags": {
      "preview": true
    }
  },
  "fixtureRegion": "us-west-2",
  "fixtureRetries": 2,
  "fixtureFlags": {
    "preview": true
  }
}

Notes

• Pagination: none; all accepted data is bounded and processed in one local pass.
• Limits: 64 top-level keys, 512 total nodes, 256 entries per array, eight nesting levels, 16,384 characters per text value, and 64 KiB of serialized JSON.
• Idempotency: identical input state and configuration produce the same output. There is no external side effect.
• Caching: disabled because collision behavior depends on current workflow state.
• Rate limits: none; the module calls no provider.
• API constraints: none; there is no remote API or approved destination.
• Destructive behavior: none outside the workflow state produced for downstream tasks. Existing keys are protected unless overwrite is explicitly enabled.
• Legacy compatibility: flat version 1 module data is accepted after the same version 2 validation. New workflows should use values.
• Runtime deployment: merged source and public documentation do not update the deployed Workflow Studio catalog until the normal ValkyrAI backend release exposes version 2 through /v1/modules/metadata.
• Unverified boundary: deterministic tests cover request-free behavior, bounds, collision policy, secret/control-key rejection, legacy compatibility, output clearing, and metadata discovery. A backend runtime deployment is outside this documentation release.