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

# Design a transition Domain

> Map observable inputs and outcomes for structured transition learning, then verify event admission and support.

Adapt-1 reads only the transition fields the Domain maps. Choose the observable input fields and structured target fields. Add an action path only when the relationship being learned includes an executed or proposed action.

Paths, value types, scaling, grouping, event boundaries, and target shape define this learner view. Keep every predicted target out of the inputs.

<Note>
  This guide applies when an application uses structured transition learning. It is not a setup requirement for continuity, general Domain reasoning, the interval-policy contract, or every Adapt-1 workflow.
</Note>

Structured transition learning can map observed inputs to observed targets without defining an episode or delayed credit. Sequential learning is a separate option for workflows where later outcomes must inform earlier decisions.

If you are still shaping the learner view, [Domain learning patterns](/docs/neuroadapt/learning-patterns-for-domains) offers several illustrative patterns without defining a closed catalog of Domain setups.

<Info>
  Ask this question: **Which events can supply evidence for this query?** Reserved API fields and configured paths have specified functions. Other field names do not define causal functions.
</Info>

## Transition setup

Set `learning.enabled: true` and `learning.transition.enabled: true`. Declare the event type, input paths, and observable targets:

```json theme={null}
{
  "schema": {
    "event_types": ["observed_target"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["observed_target"],
      "input_paths": [
        "values.entity",
        "values.feature"
      ],
      "targets": [
        {
          "path": "values.output",
          "type": "number"
        }
      ]
    }
  }
}
```

Add `action_path` only when the learned relationship includes an action. Add `group_by_paths` only when evidence must remain separated across incompatible public task or dataset contexts. Leave support, neighbor, distance, and retention controls at their defaults until the evidence contract requires a change.

Structured transition learning can coexist with ordinary policy feedback in one Domain. It can also be the only adaptive output in a Domain with no hypotheses. Use separate Domains when the input, target, or retention scopes should not mix.

### Application data layers

Keep the complete operational record outside the learner view. This separation preserves provenance. It also lets you revise the Domain without exposing all recorded fields.

| Layer                        | Content                                                                                                                            | Purpose                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Operational record**       | All external observations before and after the event, execution details, timestamps, adapter outputs, and provenance               | Audit, fault isolation, Domain revisions, and application analytics                                |
| **Learner view**             | Configured observations, permitted derived features, and an action or intervention only when the learned relationship requires one | Similarity, grouping, support selection, and structured prediction                                 |
| **Application-only context** | Privileged state, policy decisions, preferred actions, solver labels, downstream acceptance, and application metrics               | Use for application logic and monitoring. Do not use for transition inputs or observation targets. |

The application can send a feedback signal through a documented feedback route. Keep feedback separate from the learner view and the transition target.

### Learner inputs

A learner input can include a relative offset, normalized state, proposed intervention, or operating mode. The application must calculate each input before the consequence occurs.

Do not include the observed consequence, a hidden cause, the preferred action, or a solver label. Do not include a collision or boundary label calculated from the consequence. Use a boundary feature only if permitted observations independently supply that feature before the consequence.

The initial state and proposed intervention can imply a physical configuration. Include that configuration if the application can calculate it before the consequence. Do not describe consequence data as an action feature.

### Event boundary

Make one eligible event for one declared input-to-target relationship. Use the same boundary for equivalent events.

When the relationship includes an intervention, start from the last observation before that intervention and end at its declared observation point:

```text theme={null}
before observation -> proposed intervention -> execution -> observable consequence
```

When the relationship is direct structured prediction, keep the configured inputs and withheld target on the same item or event. Do not put unrelated actions, targets, or distant variables into one sample. Keep longer operational sequences outside this learner view unless their order is itself part of the declared input.

### Transition patterns

The same contract works across many application types:

| Application pattern    | Configured learner input                                  | Observable target                                           |
| ---------------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| Spatial control        | Relative geometry, operating mode, proposed movement      | One coherent displacement or contact effect                 |
| Equipment operation    | Current readings, equipment mode, proposed setting change | Next observable state band or alarm state                   |
| Routing and allocation | Queue or resource state, route/allocation choice          | Observed destination, load band, or completion state        |
| Structured output      | Region, appearance, depth, dataset, or entity features    | Observable region coordinates or normalized action geometry |

These examples supply necessary observations. They do not supply the preferred choice or the observable target in advance.

<Note>
  This page covers the structured-transition learner that predicts declared observable targets from configured event inputs. An action is part of that input only when the declared relationship requires one. If the application instead needs policy scoring against a bounded public objective, use [bounded transition scoring](/docs/neuroadapt/make-behavior-improve-from-feedback#bounded-transition-scoring). The two relationships are different.
</Note>

## Support diagnostics

### Evidence reuse

| Domain choice                | Use condition                                                                                                | Possible configuration problem                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Event boundary               | One intervention has one declared observation point                                                          | The learner can associate distant or overlapping changes with the wrong intervention |
| Numeric inputs               | Use comparable quantities. Normalize when an irrelevant scale must not control selection.                    | Scale or absolute placement controls neighbor selection                              |
| Relative or invariant inputs | Translation, rotation, or another transform does not change the transition behavior                          | Physically equivalent events remain far apart                                        |
| Absolute inputs              | Position or magnitude changes transition behavior, such as at a wall or regime boundary                      | Removing the absolute term treats incompatible cases as equivalent                   |
| Categorical inputs           | Identity changes the transition behavior without implying numeric distance                                   | Arbitrary category IDs introduce false ordering or proximity                         |
| Action representation        | Different action labels produce equivalent physical configurations that are available before the consequence | Equivalent actions stay in separate evidence sets                                    |
| `group_by_paths`             | The route must exclude evidence from incompatible transition relations                                       | Too little grouping mixes incompatible evidence. Too much grouping prevents reuse.   |
| Target shape                 | The target preserves each observable distinction that the learner must predict                               | Independent outputs can make a transition that cannot occur                          |
| `required_support`           | The application requires a minimum number of eligible observations                                           | Irrelevant or distant samples can fill the support count                             |
| Event coverage               | The event stream contains routine states, boundaries, exceptions, and applicable operating modes             | A narrow event stream supplies support for only one operating region                 |

<Warning>
  **`action_path` and `group_by_paths` have different functions.** An action path identifies the configured action value. Grouping controls evidence eligibility. Document exact matching and the handling of missing or `null` group values. Removing a group does not guarantee evidence reuse between actions. The remaining input geometry can still separate the actions.
</Warning>

### Event admission

The API can accept and store an event that the structured-transition learner does not accept. Do these checks before you use the result:

1. The API accepted the request and returned an event or memory ID.
2. Every configured input, target, action, and grouping path was present with the expected type.
3. The structured-transition learner accepted the sample.
4. For one eligible and unique event, `sample_count_delta` reports the specified increase. This value is usually `1`.
5. The learner-relevant model or subsystem version advanced exactly as the endpoint contract specifies.

If a counter does not change, examine the skip or rejection reason. Do not change the Domain or send more events first. Storage does not prove learner admission.

<Info>
  After posting an event, inspect `learner_eligibility`. `accepted` confirms that the event matched the configured learner view. `rejection_reason` and `missing_paths` explain rejected events. `sample_count` and `model_version` are learner-state diagnostics, not settings users must tune.
</Info>

### Evidence-routing refinement

Start with observable inputs that have the correct numeric and categorical meanings. Examine returned evidence to find routing problems. Make the smallest necessary Domain change.

* Normalize comparable quantities when an irrelevant scale controls neighbor selection.
* Add relative or invariant features when equivalent physical events are far apart.
* Add categorical action context when action identity changes the transition behavior.
* Add grouping only when evidence must not cross incompatible operating modes.

If a geometry change gives stored memories a new meaning, create a new Domain revision. Process the original chronological records into the new revision.

Inspect evidence identity as well as the prediction:

* Do equivalent events retrieve one another?
* Do arbitrary action labels prevent evidence reuse?
* Does the support set contain incompatible modes?
* Does the learner abstain when no eligible nearby experience exists?

An application result does not show how Adapt-1 reused evidence. Examine evidence memory IDs, distances, group identity, disagreement, and abstention reasons.

### Target structure

The target must preserve each observable distinction that the learner must predict. Use one object when the possible distinctions constrain one another. Keep the complete after-observation in the operational record.

If effects are mutually exclusive, use one joint target. Independent coordinates can combine into an effect that cannot occur. For example:

```text theme={null}
NO_CHANGE
DIMENSION_A_INCREASE
DIMENSION_A_DECREASE
DIMENSION_B_INCREASE
DIMENSION_B_DECREASE
```

This class preserves all distinctions in the declared effect vocabulary. It does not declare which intervention produces an effect.

Application processing can map different raw effects to the same visible state. In this case, select a target that represents the observations available to the application. Keep an unobserved effect outside the learner view unless a permitted observation shows it.

If application processing changes the state, keep these values separately:

| Value                           | Purpose                                                  |
| ------------------------------- | -------------------------------------------------------- |
| Raw predicted target            | Shows what the transition learner actually predicted     |
| Structural or physical validity | Identifies impossible combinations before reconstruction |
| Reconstructed raw next state    | Shows the direct consequence of the predicted target     |
| Clamped or corrected next state | Shows what the application or environment accepts        |

A valid processed state can hide an invalid raw transition prediction. Keep both values available for application monitoring.

### Abstention

`required_support` is one step in the support sequence. It does not fully define relevance. Use it with these controls:

```text theme={null}
candidate samples
-> group eligibility under the route contract
-> distance and category geometry
-> neighbor selection
-> required support
-> prediction or abstention
```

Before the application uses transition predictions, confirm the specified support states:

| Support state                                       | Required response |
| --------------------------------------------------- | ----------------- |
| No relevant observations                            | Abstain           |
| Fewer matching observations than `required_support` | Abstain           |
| Enough nearby, matching observations                | Predict           |
| Many observations from unrelated contexts           | Still abstain     |

Read predicted values only when the returned status is `predicted`. When returned, `support_count` and `evidence_memory_ids` identify the supporting observations.

The API can select distant samples that have eligible group values. Use the documented distance control if the route supplies one. Otherwise, change the feature geometry or grouping. `required_support` alone does not control distance.

<Warning>
  Treat confidence as a support signal for this workflow. Do not treat confidence as a probability of correctness or as an exploration policy. Use a different meaning only if the response contract defines it. Examine support identity, distance, disagreement, missing evidence, and the selection or abstention reason.
</Warning>

### Read-only inspection

Use non-mutating Domain queries and `/explain` to examine a prediction, uncertainty, or an integration.

One use of this read-only pattern is counterfactual evaluation. An application can construct a fixed set of candidate interventions, query the learned transition state for each without adding evidence, and compare the predicted consequences before committing an action. The application still defines the candidates, selection rule, and execution boundary.

For a repeatable read, include the required query and grouping context. If the route supports these fields, disable exploration and memory-state updates:

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

Connect `/explain` to the exact query or result ID if the route supports this connection. A later explanation can use a different evidence set. Assume identical evidence only if the endpoint contract guarantees it.

Keep both complete responses. Use the route schema to find each field. Different subsystems can put fields at different levels.

| Snapshot                  | Preserve when returned                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Domain query              | `transition_prediction`, evidence memory IDs, `learning_state`, and the selection or abstention reason                                           |
| `/explain`                | `ranked_hypotheses`, supporting and counterevidence IDs, `supporting_memories`, `missing_evidence`, `predicted_observations`, and `core_support` |
| Around the read operation | Domain and schema revision, model and subsystem versions, and the documented learner-relevant state hash                                         |

Use `/explain` as specified in its route contract. For a read-only call, the documented learner-state hash and applicable versions must not change. Do not use a service hash unless the API defines that hash as learner state.

<Note>
  `allow_exploration: false` and `update_memory_state: false` control different functions. Disabled exploration does not prove that the read cannot change state. Use the endpoint contract and version checks together.
</Note>

<Accordion title="Advanced: hypothesis evidence">
  Transition predictions do not automatically create hypotheses. A Domain with no configured candidates can return an empty hypothesis list.

  When the application needs hypotheses, use alternatives of equal status. The alternatives must:

  * compete over the same relation.
  * predict different observable consequences.
  * can gain both supporting evidence and counterevidence.
  * share the same schema and do not encode a preferred answer.
  * use the events that distinguish them.

  Before the application uses hypotheses, confirm that the alternatives use the specified event relation:

  1. Declare two or more alternatives with different observable predictions.
  2. Send ordinary application events that distinguish those alternatives.
  3. Read `/explain` before adding feedback.
  4. Confirm that supporting evidence or counterevidence changes with the observations.
  5. If the evidence does not change, do not combine transition output with hypothesis output. Treat a feedback-driven hypothesis route as a separate contract.

  Avoid candidates that all make the same observable prediction.
</Accordion>

## Evidence-routing troubleshooting

| Observed behavior                                        | Likely configuration cause                                                                       | Corrective action                                                                                     |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Event stored but `sample_count_delta: 0`                 | Required path, type, target, event kind, duplicate, or learner-selection mismatch                | Repair the path, type, target, or route configuration before consuming transition output              |
| `no_matching_group` on a valid query                     | Missing or different query group context, or no event eligible under the grouping contract       | Verify group values, types, missing/`null` handling, and the specified partition                      |
| Evidence remains same-action without configured grouping | Input geometry, event coverage, or retrieval rules select same-action neighbors                  | Examine support distances and coverage. Add permitted relational or physical geometry when necessary. |
| Evidence crosses incompatible actions or modes           | Insufficient conditioning or grouping                                                            | Add categorical conditioning or grouping for the incompatible modes                                   |
| Support count fills with unrelated samples               | Candidate geometry or distance control is too broad                                              | Tighten the documented distance constraint or redesign feature geometry and grouping                  |
| Exact next state is correct but raw effect is invalid    | Reconstruction or post-processing hides the error                                                | Preserve and inspect the raw target and structural validity before consuming the post-processed state |
| Confidence is high while consequences conflict           | Confidence is not a probability of correctness                                                   | Do not use confidence alone. Examine evidence identity, distance, and disagreement.                   |
| Hypotheses are absent or tied                            | No candidates, candidates with equal predictions, missing evidence contract, or separate outputs | Review candidate distinctions, event relation, and the hypothesis evidence route                      |
| Learner state changes around a read-only call            | A query flag, endpoint, or background update changes learner state                               | Identify the state-changing subsystem and correct the route contract mismatch                         |

<Accordion title="Advanced: autonomous structural learning">
  Configure `learning.structure` when the Domain should induce compact predictive conditions or relations from accepted events without using an LLM:

  ```json theme={null}
  {
    "learning": {
      "structure": {
        "enabled": true,
        "event_types": ["observation"],
        "feature_paths": ["values.mode", "values.pressure", "values.load"],
        "targets": [
          {"path": "values.state", "type": "categorical"},
          {"path": "values.risk", "type": "number"}
        ],
        "min_support": 3,
        "min_calibration_support": 2,
        "max_literals": 3,
        "transfer_enabled": true,
        "min_local_support_for_transfer": 2
      }
    }
  }
  ```

  Supported target types are `number`, `categorical`, `boolean`, and `set`. Accepted events sent to `POST https://rei-neuroadapt-api-uat.reilabs.org/api/v1/domains/{domain_id}/events` update structural state; Domain query and explain can return `induced_structure`, and eligible induced hypotheses appear in `ranked_hypotheses` with `origin: "induced"`.

  Structural output is predictive rather than proof of causality. The learner can abstain under weak or ambiguous support, and compatible transfer remains owner-scoped and requires local confirmation.
</Accordion>

## Launch checklist

Before relying on a transition result, verify:

* Store the operational record, learner view, and application-only context separately.
* Confirm that every derived learner feature is computable before the consequence.
* Keep one meaningful intervention inside each declared event boundary.
* Match numeric scale, position, and invariances to the transition behavior.
* Keep arbitrary numeric distance out of categorical values.
* Give `action_path`, categorical inputs, and grouping separate functions.
* Use grouping only to block incompatible transition behavior.
* Represent each legal observable consequence as one coherent target.
* Keep raw predictions and post-processed state separately inspectable.
* Verify learner admission instead of inferring it from event storage.
* Confirm that unsupported queries abstain and unrelated events cannot supply support.
* Preserve evidence identity, distance, disagreement, and abstention reasons.
* If the Domain uses hypotheses, make them distinguishable and document their evidence route.
* Confirm that read-only query and explanation calls leave learner state unchanged.

A correctly scoped transition Domain lets Adapt-1 reuse relevant evidence consistently. It also makes limits visible. Insufficient support causes abstention. The support record shows incompatible evidence. Raw output shows invalid predictions before application processing. New events can revise competing hypotheses.