> ## 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.

# Operate stateful and adaptive workflows

> Keep ordered, stateful Adapt-1 workflows isolated, retryable, and auditable.

export const OrderedWriteTimeline = () => {
  const stages = [{
    index: "01",
    label: "Write",
    detail: "Send stable run, trial, and event identifiers.",
    tone: "border-sky-200 bg-sky-50 dark:border-sky-900 dark:bg-sky-950"
  }, {
    index: "02",
    label: "Persist",
    detail: "Store the last response that the client confirmed.",
    tone: "border-emerald-200 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950"
  }, {
    index: "03",
    label: "Ambiguous failure",
    detail: "A gateway timeout may occur after the upstream write.",
    tone: "border-rose-200 bg-rose-50 dark:border-rose-900 dark:bg-rose-950"
  }, {
    index: "04",
    label: "Reconcile",
    detail: "Inspect current state before replaying a mutating request.",
    tone: "border-amber-200 bg-amber-50 dark:border-amber-900 dark:bg-amber-950"
  }, {
    index: "05",
    label: "Resume",
    detail: "Continue from the last confirmed logical event.",
    tone: "border-stone-200 bg-stone-50 dark:border-zinc-800 dark:bg-zinc-900"
  }];
  return <figure className="not-prose my-8 overflow-hidden rounded-2xl border border-stone-200 bg-white shadow-sm dark:border-zinc-800 dark:bg-zinc-950" aria-labelledby="write-caption">
<div className="flex flex-wrap items-center justify-between gap-3 border-b border-stone-200 px-5 py-4 dark:border-zinc-800">
<div>
<div className="text-xs font-semibold uppercase tracking-widest text-stone-500 dark:text-zinc-400">Stateful write recovery</div>
<div className="mt-1 text-sm font-semibold text-stone-900 dark:text-zinc-100">One writer · stable identifiers · explicit checkpoints</div>
</div>
<span className="rounded-full border border-stone-200 px-3 py-1 font-mono text-xs text-stone-500 dark:border-zinc-700 dark:text-zinc-400">ordered state</span>
</div>
<div className="grid gap-3 p-4 md:grid-cols-5">
{stages.map(stage => <section key={stage.index} className={`rounded-xl border p-3 ${stage.tone}`}>
<div className="font-mono text-xs text-stone-400 dark:text-zinc-500">{stage.index}</div>
<div className="mt-4 text-xs font-semibold text-stone-900 dark:text-zinc-100">{stage.label}</div>
<div className="mt-2 text-xs leading-5 text-stone-600 dark:text-zinc-400">{stage.detail}</div>
</section>)}
</div>
<div className="grid gap-px border-t border-stone-200 bg-stone-200 dark:border-zinc-800 dark:bg-zinc-800 sm:grid-cols-3">
<div className="bg-white p-3 text-xs text-stone-600 dark:bg-zinc-950 dark:text-zinc-400"><span className="font-mono text-stone-400">READ</span><span className="ml-2">Repeat when the contract is non-mutating.</span></div>
<div className="bg-white p-3 text-xs text-stone-600 dark:bg-zinc-950 dark:text-zinc-400"><span className="font-mono text-rose-500">WRITE</span><span className="ml-2">Treat completion as ambiguous until reconciled.</span></div>
<div className="bg-white p-3 text-xs text-stone-600 dark:bg-zinc-950 dark:text-zinc-400"><span className="font-mono text-amber-600">RESET</span><span className="ml-2">Record every declared state boundary.</span></div>
</div>
<figcaption id="write-caption" className="border-t border-stone-200 px-5 py-3 text-xs text-stone-500 dark:border-zinc-800 dark:text-zinc-500">Do not blindly replay a timed-out event or feedback write when duplication could change the learned state.</figcaption>
</figure>;
};

Stateful integrations need explicit isolation, ordering, stable identifiers, and careful retry behavior.

<OrderedWriteTimeline />

## Recommended metadata

Use stable identifiers on event and feedback writes when the request schema accepts metadata:

```json theme={null}
{
  "metadata": {
    "run_id": "run1",
    "trial_id": "run1-trial-001",
    "event_id": "run1-event-001",
    "relation": "in_front_of",
    "policy": "footprint_edge_projection"
  }
}
```

`run_id` isolates a workflow, `trial_id` identifies one outcome unit, and `event_id` identifies one logical write. Relation and policy fields keep feedback scoped when that workflow uses them.

## Online-policy ordering

For Adaptive Policies:

```text theme={null}
one writer
fresh domain_id
POST /api/v1/domains/{domain_id}/adapt/reset before replay
ordered observations
checkpointed responses
```

Concurrent workers against the same domain/session can interleave observations and change the result.

Do not reset state between interactions that share learning. Reset policy state only for a new state history or a rebuild from a known record. Record each reset in the application log.

## Retryable failures

Handle `429`, `502`, `503`, and `504` as transient. Use exponential backoff with jitter and a bounded retry count.

```text theme={null}
0.5s -> 1s -> 2s -> 4s -> 8s maximum
```

Do not automatically retry `400`, `401`, `403`, `404`, or `422`; correct the request first.

## Ambiguous writes

A gateway failure can occur after an upstream write was accepted. Until a route explicitly documents idempotency, treat failed event and feedback writes as ambiguous:

1. Send stable `run_id` and event/trial identifiers.
2. Check the available state or audit response before resubmitting when a duplicate would affect the result.
3. Checkpoint the last confirmed identifier.
4. Resume from the last confirmed write.

`POST /api/v1/domains/{domain_id}/adapt/predict` reads current adaptive state without adding an observation and can be repeated safely according to its documented contract.

## Read-only state inspection

A route name does not specify if the route changes state. Use the documented state-change contract for the selected endpoint.

If the route supports `allow_exploration` and `update_memory_state`, set both fields to `false`. Record the learner-state hash and applicable versions before the calls. Compare the values after the calls. The values must not change.

The two fields control different functions. `allow_exploration: false` does not prevent state updates.

Store the complete response and the required query context. If a query changes a learner version, stop the inspection. Identify the endpoint or process that changed the version.

## Reset and clear

| Operation                                                                             |                                Evidence | Policy/context | Transition | Structural | Adaptive interval | Definition |
| ------------------------------------------------------------------------------------- | --------------------------------------: | -------------: | ---------: | ---------: | ----------------: | ---------: |
| `POST https://rei-neuroadapt-api.reilabs.org/api/v1/memory/clear`                     | clears caller memory and memory indexes |       retained |   retained |   retained |          retained |   retained |
| `POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/clear`        |           clears that Domain's evidence |       retained |   retained |   retained |          retained |   retained |
| `POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/policy/reset` |                                retained |        cleared |   retained |   retained |          retained |   retained |
| `POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/adapt/reset`  |                                retained |       retained |   retained |   retained |      configurable |   retained |
| `DELETE https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}`            |                  clears Domain evidence |        cleared |    cleared |    cleared |           cleared |    deleted |

Choose the route that owns the intended state boundary. For a completely cold Domain evaluation, delete and recreate the Domain; also clear memory if the same identity holds unrelated test memories.

## Production integration checklist

* Keep API keys server-side and use canonical `/api/v1` routes.
* Persist memory IDs and sealed Domain decision IDs when later correction, deletion, feedback, or historical explanation is required.
* Set `update_memory_state: false` for read-only evaluation and replay.
* Check learner eligibility and abstention fields instead of assuming every stored event trained a learner.
* Use the dedicated adaptive routes for adaptive output and validate Vision grounding before acting on a point.
* Record every reset boundary and choose its scope deliberately.