Transition learning, advanced

Use this guide only when the application needs this relationship:

observable inputs available before the consequence
+ optional proposed or executed action
-> observable target available afterward

A transition Domain answers what happens next. It does not automatically answer whether an action was useful, score movement toward a bounded objective, or assign a final outcome back to earlier actions.

Continuity, ordinary Domain reasoning, feedback adaptation, and stateless structured results do not require custom transition configuration.

Check whether transition learning fits

Use structured transition learning when all of these are true:

The target becomes observable after the configured inputs or action.
Every input can be computed before that consequence.
Equivalent events should be able to reuse one another as evidence.
The application can define one coherent event boundary.
The application can abstain when no eligible support exists.

Do not use it merely because records arrive in order, an episode has several steps, or the output is structured.

One event in one picture

last observation before the action
-> proposed action or intervention
-> exact external execution
-> declared observation point
-> observable target

For direct structured prediction with no action, the eligible input and withheld target belong to one item or event:

observable item fields -> withheld observable target

One eligible event should represent one declared input-to-target relationship. Keep longer operational traces for provenance, but do not collapse unrelated actions, distant consequences, or several targets into one transition sample.

Minimal setup

Use Discovery by default when the target is known but the useful pre-target input surface is not. Set learning.enabled: true and learning.transition.enabled: true, declare the eligible event type and observable target, omit input_paths, and enable autonomous_projection.

{
  "schema": {
    "event_types": ["observed_target"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["observed_target"],
      "targets": [
        {
          "path": "values.output",
          "type": "number"
        }
      ],
      "autonomous_projection": {
        "enabled": true
      }
    }
  }
}

Adapt-1 can accumulate complete observations while the projection is still forming. When Discovery becomes ready, it selects eligible scalar input paths and rebuilds buffered events under the discovered projection. Author input_paths explicitly when the learner-facing ontology must be fixed or reviewed in advance. Explicit paths remain authoritative when supplied. Add action_path only when the learned relationship includes an action or intervention. Add group_by_paths only when evidence must remain separated across incompatible public contexts. Leave support, distance, neighbor, and retention controls at their defaults until the evidence contract shows a specific need. See Use Discovery for the acquisition lifecycle, discovered projection diagnostics, structural representation discovery, and mixed setup. Structured transition learning can coexist with ordinary policy feedback. It can also be the only adaptive relationship in a Domain with no candidate hypotheses.

Keep three data layers separate

Layer	Content	Purpose
Operational record	Complete before and after observations, execution details, timestamps, adapter outputs, provenance, and application metrics	Audit, fault isolation, replay, and Domain revision
Learner view	Configured observations, permitted derived features, optional action, and observable target	Transition evidence and reuse
Application-only context	Hidden state, preferred actions, solver labels, ground truth, downstream acceptance, and private metrics	Application logic and evaluation only

A feedback signal belongs on the applicable feedback route. Keep it separate from an observation-only transition target.

Learner inputs

Every transition input must be available before the consequence. Inputs can include:

Current observable state.
Relative or normalized geometry.
Public operating mode.
A proposed intervention or action.
A derived feature computed only from pre-consequence observations.

Do not include:

The target or any field derived from it.
A hidden cause unavailable to the application.
The preferred or correct action.
A solver label.
A collision, boundary, or success label calculated from the after-state.

A proposed action can imply a physical or logical configuration. Include that configuration only when the application can compute it before execution.

Target structure

The target must preserve every observable distinction the learner must predict. Use one joint target when separately predicted fields can form an impossible combination. For mutually exclusive effects, one categorical target may be safer than independent booleans:

NO_CHANGE
DIMENSION_A_INCREASE
DIMENSION_A_DECREASE
DIMENSION_B_INCREASE
DIMENSION_B_DECREASE

This vocabulary names possible observable effects. It does not declare which action produces them. When the application reconstructs or clamps a prediction, keep these values separate:

Value	Why preserve it
Raw predicted target	Shows what the transition learner returned
Structural or physical validity	Detects impossible combinations
Reconstructed raw next state	Shows the direct predicted consequence
Corrected or clamped next state	Shows what the application accepted

A valid processed state can hide an invalid raw prediction.

Evidence geometry and grouping

Evidence reuse depends on the configured input representation, not on field names alone.

Design choice	Use when	Common failure
Numeric inputs	Magnitude and distance are meaningful	An irrelevant scale controls neighbor selection
Relative or invariant inputs	Translated or transformed events should behave equivalently	Equivalent events remain far apart
Absolute inputs	Position or magnitude changes behavior at a boundary or regime	Removing absolute context mixes incompatible cases
Categorical inputs	Identity changes behavior without implying numeric distance	Arbitrary numeric IDs introduce false ordering
`action_path`	The event relation includes a configured action	Action identity is omitted from an action-dependent transition
`group_by_paths`	Evidence from incompatible public contexts must never mix	Too much grouping prevents useful reuse; too little mixes different dynamics

action_path identifies the action value. group_by_paths determines evidence eligibility. They do not have the same function. Start with the smallest observable representation that preserves the real transition relationship. Change geometry only after inspecting which evidence supported a result.

Admission before interpretation

The API can store an event that the transition learner does not accept. Before using transition output, verify:

The request returned an event or memory ID.
Every configured input, target, action, and grouping path was present with the expected type.
The transition learner accepted the event.
sample_count_delta changed as specified for one eligible unique event, usually by 1.
The applicable learner or subsystem version advanced as the endpoint contract specifies.

Inspect learner_eligibility, accepted, rejection_reason, missing_paths, sample_count, and model_version when returned. Storage does not prove learner admission. When admission fails, repair the path, type, event kind, target, duplicate handling, or selected learner before sending more events.

Support and abstention

A supported prediction follows a sequence such as:

candidate samples
-> group eligibility
-> input distance and category geometry
-> neighbor selection
-> required support
-> prediction or abstention

Expected behavior:

Evidence state	Required result
No relevant observations	Abstain
Fewer matching observations than `required_support`	Abstain
Enough nearby compatible observations	Predict
Many observations from unrelated contexts	Still abstain

Read predicted values only when the returned status is predicted. When available, preserve support_count, evidence IDs, distances, group identity, disagreement, and the selection or abstention reason. Treat confidence according to the route contract. Do not assume it is a calibrated probability of correctness or an exploration policy.

Optional workflows

Compare candidate actions without writing

An application can query a fixed set of candidate actions without adding evidence, compare their predicted consequences, and then commit externally. The application still owns candidate construction, selection rules, safety checks, and execution.When the route supports them, use:

{
  "allow_exploration": false,
  "update_memory_state": false
}

These flags control different functions. Disabled exploration does not by itself prove that a call is read-only. Verify the endpoint contract, applicable learner-state hash, and versions before and after the read.Preserve the complete Domain query and /explain responses. A later explanation can use a different evidence set unless the route explicitly binds it to the original query or result.

Use typed hypothesis evidence

Transition predictions do not automatically create hypotheses. Add candidate hypotheses only when the mechanism itself is required.Candidates should:

Compete over the same declared relation.
Predict different observable consequences.
Receive both supporting evidence and counterevidence.
Share the same public schema.
Avoid encoding a preferred answer.

Confirm that ordinary events actually change support or counterevidence before combining hypothesis output with transition output. Otherwise treat them as separate contracts.

Induce compact predictive structure

Configure learning.structure only when the Domain should induce compact predictive conditions or relations from accepted events. This is optional and is not required for ordinary transition prediction.

{
  "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. Eligible induced hypotheses can appear in ranked_hypotheses with origin: "induced". Treat the output as predictive structure, not proof of causality. Compatible transfer remains owner-scoped and requires local confirmation.

Troubleshooting

Observed behavior	Likely cause	First correction
Event stored but sample count does not change	Missing path, wrong type, ineligible event kind, duplicate, or learner mismatch	Inspect admission and repair the contract before adding data
`no_matching_group`	Query group context differs or no event is eligible	Verify values, types, and missing or `null` handling
Evidence remains same-action without grouping	Input geometry or coverage separates the actions	Inspect distances and add only permitted relational context
Evidence crosses incompatible modes	Missing conditioning or grouping	Add categorical context or a necessary group boundary
Support fills with unrelated samples	Geometry or distance control is too broad	Tighten the documented distance rule or redesign inputs
Processed next state looks valid but raw effect is impossible	Reconstruction or clamping hides the error	Preserve raw target and validity checks
Confidence is high while effects conflict	Confidence is being overinterpreted	Inspect evidence identity, distance, and disagreement
A read-only test changes state	Route flags or another subsystem still writes	Identify the changing state and correct the route contract

Launch checklist

One eligible event represents one input-to-target relationship.
Every input exists before the consequence.
Operational record, learner view, and application-only context remain separate.
Numeric scale, categorical meaning, invariances, and boundaries match the real transition behavior.
action_path and grouping have distinct justified roles.
The target represents one coherent observable consequence.
Raw prediction and application processing remain separately inspectable.
Learner admission is verified rather than inferred from storage.
Unsupported or incompatible queries abstain.
Evidence identity, distance, group, disagreement, and abstention reasons are preserved.
Read-only checks leave the applicable learner state unchanged.

A correctly scoped transition Domain makes reuse and limits visible. Relevant evidence can support a prediction. Incompatible or insufficient evidence causes abstention. New observations can revise later results without hiding how the result was supported.

Feedback, bounded scoring, and delayed credit

Use the feedback guide when the question is whether a committed action was useful, how it moves a bounded public objective, or how a later outcome should revise earlier decisions.

Get started

Build

Advanced Domain design

Operate

Modalities

Domains

Interval policies

State

System

Spatial Vision API

Check whether transition learning fits

One event in one picture

Minimal setup

Keep three data layers separate

Learner inputs

Target structure

Evidence geometry and grouping

Admission before interpretation

Support and abstention

Optional workflows

Troubleshooting

Launch checklist

Feedback, bounded scoring, and delayed credit

​Check whether transition learning fits

​One event in one picture

​Minimal setup

​Keep three data layers separate

​Learner inputs

​Target structure

​Evidence geometry and grouping

​Admission before interpretation

​Support and abstention

​Optional workflows

​Troubleshooting

​Launch checklist

Feedback, bounded scoring, and delayed credit

Check whether transition learning fits

One event in one picture

Minimal setup

Keep three data layers separate

Learner inputs

Target structure

Evidence geometry and grouping

Admission before interpretation

Support and abstention

Optional workflows

Troubleshooting

Launch checklist