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.

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.

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 offers several illustrative patterns without defining a closed catalog of Domain setups.

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.

Transition setup

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

{
  "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:

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.

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. The two relationships are different.

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

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.

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.

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.

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:

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:

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.

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.

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:

{
  "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.

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.

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.

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

Advanced: autonomous structural learning

Configure learning.structure when the Domain should induce compact predictive conditions or relations from accepted events without using an LLM:

{
  "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.

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.