> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reilabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an inspectable stateful workflow

> Define the state lifecycle and preserve an ordered record of Adapt-1 results and observable consequences.

Start one Adapt-1 workflow. Define its state lifecycle and input contract. Keep the calls in order. Record each Core result and external consequence.

This procedure is normal application setup. The application supplies observations and executes operations. Adapt-1 forms and changes task-relevant structure. The selected route returns the result.

## Application boundary

| Responsibility         | Contribution                                                                       | Data to record                                           |
| ---------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Source system          | Native observations and available operations                                       | Exact data available before each Adapt-1 call            |
| Adapter                | Optional translation of format, features, or modality                              | Adapter version and translated fields                    |
| Adapt-1                | Persistent reasoning, adaptation, prediction, support, or abstention               | Complete route response and learner-state metadata       |
| Application commitment | Maps, accepts, defers, selects between equal values, or overrides a returned value | Returned value, selected value, and selection rule       |
| Executor               | Applies the physical or software operation                                         | Exact operation and parameters                           |
| Consequence source     | Supplies the next observation, native consequence, or application feedback         | External consequence and information returned to Adapt-1 |

If source data agrees with the route contract, an adapter is not necessary. If you use an adapter, translate only the observable interface. Do not supply the preferred answer or consequence relation.

## State lifecycle

Before the first write, select a new state history or an existing state history.

| Lifecycle                | Use condition                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| New state history        | The workflow must not inherit accumulated state from another application, tenant, Domain revision, or operational history |
| Continuing state history | Later interactions must use and change the existing learner state                                                         |
| Rebuilt state history    | The application must process a known chronological record into a new Domain or schema revision                            |

Use the clear or reset route for the applicable state. Domain state, session state, and interval-policy state have different scopes. Do not clear state between interactions that share learning.

Use one writer for ordered online state. Concurrent writers can change the event order. This change can affect the evidence available to later calls.

## Input contract

Version the parts of the application boundary that determine what Adapt-1 receives:

* Domain and schema.
* Event boundary.
* Input and target paths.
* Numeric normalization and categorical representation.
* Grouping context.
* Adapter or feature extractor.
* Action dictionary.
* Consequence translation.
* response field consumed by the application.

A Domain can declare public action meanings, event types, and output vocabulary. Do not include private target state, the preferred procedure, or the consequence relation to learn.

For transition learning, keep the operational record, learner view, and application-only context separate. See [Design Domains for transition learning](/docs/neuroadapt/design-transition-domains).

## Ordered provenance

Use stable identifiers that the selected request contract accepts. Keep an application interaction record:

```json theme={null}
{
  "workflow_id": "line-routing-v3",
  "interaction_id": "interaction-0042",
  "event_id": "event-0042",
  "domain_revision": "3",
  "adapter_version": "features-12",
  "result_ref": "result-0042",
  "returned_value": "route_left",
  "selected_value": "route_left",
  "selected_by": "adapt_1",
  "executed_operation": "route_left",
  "observable_consequence": "item_entered_lane_left",
  "feedback_returned": null
}
```

The JSON object is an application record. It is not a universal API request. Submit only the fields that the selected route accepts.

The important sequence is:

```text theme={null}
input supplied
-> Adapt-1 result
-> application commitment
-> exact execution
-> observable consequence
-> information returned
```

If a value changes between steps, keep the original value and the final value.

## Transition-event admission

The API can store a Domain event that the structured-transition learner does not accept. Before you use transition output, confirm these contract fields:

* Event or memory ID.
* Required input, target, action, and grouping paths.
* Accepted or skipped learner status.
* Sample-count change.
* Skip reason.
* learner or subsystem version.

Storage does not prove that the transition learner received the observation.

## Read-only inspection

Use the applicable Domain query and `/explain` to examine a result. Include the query and grouping context that the application normally supplies.

If the route supports these fields, disable exploration and memory-state updates:

```json theme={null}
{
  "allow_exploration": false,
  "update_memory_state": false
}
```

Keep both complete responses. Confirm that the documented learner-state hash and applicable versions do not change during the read-only calls.

Inspect:

* The result used by the application.
* Evidence memory IDs and support.
* Selection or abstention reason.
* Missing evidence and disagreement.
* Hypothesis evidence when configured.
* Domain, schema, model, and subsystem versions.

See [Explain and audit a result](/docs/neuroadapt/explain-and-audit-responses).

## Ambiguous-write recovery

A gateway timeout can occur after the upstream service accepts an event or feedback write. Until the route specifies idempotency:

1. Send stable logical identifiers.
2. Persist the last response confirmed by the client.
3. Examine current state before you repeat a write that can cause two learner-state changes.
4. Resume from the last confirmed logical interaction.

Do not repeat a timed-out event or feedback request without a state check.

See [Operate stateful and adaptive workflows](/docs/neuroadapt/operational-behavior-and-retries).

## Generated language

Structured Adapt-1 workflows do not require generated text. If the application generates language, record that operation, latency, and cost separately.

## Workflow readiness checklist

* State lifecycle chosen explicitly
* Correct clear or reset route identified
* One writer for ordered state
* Domain, schema, adapter, and action contract versioned
* Application-private information kept outside the learner view
* Stable workflow, interaction, and event identifiers
* Complete route response preserved
* Returned value connected to application commitment
* Exact execution and observable consequence recorded
* Feedback returned to Adapt-1 kept separate from application-only consequence data
* Learner admission confirmed for transition events
* Read-only inspection leaves learner state unchanged
* Ambiguous writes reconciled before resubmission

This workflow keeps Adapt-1 state, inputs, decisions, execution, and consequences clear during operation.