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

# Build domain-aware behavior

> Define a Domain from the public task interface, then let live evidence determine episode-specific behavior.

export const DomainScopeFigure = () => {
  const declared = ["entities + relations", "signals + public event semantics", "action + plan interface semantics", "optional hypotheses + rules", "query + output contracts"];
  const formed = ["episode-specific role assignments", "support from live evidence", "recurring task-local structure", "co-active associations + revisions", "current result + returned evidence"];
  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="domain-scope-caption">
      <div className="border-b border-stone-200 px-5 py-4 dark:border-zinc-800">
        <div className="text-xs font-semibold uppercase tracking-widest text-amber-700 dark:text-amber-400">Domain boundary</div>
        <div className="mt-1 text-sm font-semibold text-stone-900 dark:text-zinc-100">The public task interface is declared; episode structure is formed</div>
      </div>
      <div className="grid md:grid-cols-2">
        <section aria-labelledby="declared-scope-title" className="border-b border-stone-200 p-5 dark:border-zinc-800 md:border-b-0 md:border-r">
          <div className="flex flex-wrap items-center justify-between gap-3">
            <h3 id="declared-scope-title" className="text-sm font-semibold text-stone-900 dark:text-zinc-100">May be declared as scope</h3>
            <span className="rounded-full bg-stone-100 px-2 py-1 text-xs text-stone-500 dark:bg-zinc-900 dark:text-zinc-400">before evidence</span>
          </div>
          <ul className="m-0 mt-4 grid list-none gap-2 p-0">
            {declared.map(item => <li key={item} className="m-0 rounded-lg border border-stone-200 bg-stone-50 px-3 py-2 font-mono text-xs text-stone-600 dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-400">{item}</li>)}
          </ul>
        </section>
        <section aria-labelledby="formed-during-use-title" className="p-5">
          <div className="flex flex-wrap items-center justify-between gap-3">
            <h3 id="formed-during-use-title" className="text-sm font-semibold text-stone-900 dark:text-zinc-100">Formed during use</h3>
            <span className="rounded-full bg-amber-50 px-2 py-1 text-xs text-amber-700 dark:bg-amber-950 dark:text-amber-300">live state</span>
          </div>
          <ul className="m-0 mt-4 grid list-none gap-2 p-0">
            {formed.map(item => <li key={item} className="m-0 rounded-lg border border-amber-200 bg-amber-50 px-3 py-2 font-mono text-xs text-amber-800 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300">{item}</li>)}
          </ul>
        </section>
      </div>
      <div className="grid gap-3 border-t border-stone-200 bg-stone-50 p-4 dark:border-zinc-800 dark:bg-zinc-900 sm:grid-cols-3">
        <div className="rounded-lg border border-stone-200 bg-white p-3 text-xs text-stone-600 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-400"><strong className="block text-stone-900 dark:text-zinc-100">Public semantics may be declared</strong><span className="mt-1 block">Action meanings, event labels, and native outcome semantics can belong to the interface.</span></div>
        <div className="rounded-lg border border-stone-200 bg-white p-3 text-xs text-stone-600 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-400"><strong className="block text-stone-900 dark:text-zinc-100">Episode secrets remain outside</strong><span className="mt-1 block">No current hidden-role assignment, target identity, or answer-bearing episode information.</span></div>
        <div className="rounded-lg border border-stone-200 bg-white p-3 text-xs text-stone-600 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-400"><strong className="block text-stone-900 dark:text-zinc-100">The solution is not embedded</strong><span className="mt-1 block">No current episode's correct procedure, target coordinates, or hidden or answer-bearing action-effect mapping.</span></div>
      </div>
      <figcaption id="domain-scope-caption" className="border-t border-stone-200 px-5 py-3 text-xs text-stone-600 dark:border-zinc-800 dark:text-zinc-400">A Domain names the public task interface while live observations and outcomes determine episode-specific structure.</figcaption>
    </figure>;
};

Give Adapt-1 the public task contract your application already has, then send live observations and outcomes. The returned result can be consumed directly without generated language.

<Info>
  **Default path:** define only the public vocabulary, observable inputs, available actions or policies, native outcomes, and result contract the workflow needs. Omit learner settings unless a measured integration requirement justifies an override.
</Info>

<Note title="Returned fields are not a setup checklist">
  The Domain returned by create or read is the resolved contract. It can include defaults filled in by Adapt-1. Send only the Domain fields your integration needs; returned defaults do not need to be copied into the next create request.
</Note>

## Domain contract

A Domain can declare whichever parts of the stable task grammar the workflow uses: entities, relations, signals, event and outcome semantics, action or plan interfaces, and an output contract. Candidate hypotheses, custom rules, query templates, and specialized learner mappings are optional.

When a workflow intentionally configures structured transition learning, choose which request fields are observations, which field identifies the action, and what observable result should be predicted. Configured paths, types, grouping, event boundaries, and support controls define that learner view.

A Domain does not contain the current episode's hidden mapping, correct procedure, target coordinates, solution path, or answer-bearing episode information. Core can begin with no task history inside the declared scope and form task-local structure from the observations and outcomes it receives.

For example, an application can translate an external observation into entities, relations, and measurements, then request a contract-defined relation, compatibility judgment, location, or other structured result. The adapter supplies observable facts; it does not supply the interpretation Core is expected to form.

<DomainScopeFigure />

A stable Domain can declare public meanings and available operations. Live evidence should determine the current roles, useful action, supported hypothesis, and result.

## Structured transitions

Keep three data layers separate:

| Layer                    | Role                                                                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Operational record       | Store all observable data from before and after the event. Also store provenance.                                                         |
| Learner view             | Use observations, the proposed intervention, and permitted derived features available before the observable consequence.                  |
| Application-only context | Keep privileged state, preferred actions, solver output, and downstream judgments outside transition inputs and observation-only targets. |

The target must represent all observable distinctions that Adapt-1 must predict. The target must not state that an action was correct. Use grouping only to separate incompatible transition behavior. Use one joint target if separate fields can make an invalid consequence.

<Warning>
  The API can store a Domain event that the transition learner does not accept.
  Check learner admission and the applicable learner version. Do this before you
  interpret an unchanged prediction.
</Warning>

[Design Domains for transition learning](/docs/neuroadapt/design-transition-domains) covers event boundaries, value geometry, `action_path`, `group_by_paths`, target structure, support, abstention, hypotheses, and read-only calls.

## Causal event schema

A Domain can declare the event schema needed to preserve an exact trace:

```text theme={null}
state observation -> action commitment -> exact execution -> transition -> native outcome
```

It can also declare that a native outcome such as advancement is positive evidence when that meaning is part of the task contract. It cannot predeclare that a particular episode action causes advancement. Adapt-1 can form and reuse that mapping from observed transitions, scoped outcomes, contrasts, and later states.

## Default operating loop

```text theme={null}
declare domain -> add observations/events -> query or select -> execute externally -> record transition/outcome -> add feedback -> query again
```

## Routes

| Step                     | Route                                       | Purpose                                                                     |
| ------------------------ | ------------------------------------------- | --------------------------------------------------------------------------- |
| Create the task contract | `POST /api/v1/domains`                      | Declare the domain and its schema                                           |
| Extend the schema        | `POST /api/v1/domains/{domain_id}/schemas`  | Add domain schema information                                               |
| Add rules                | `POST /api/v1/domains/{domain_id}/rules`    | Register domain rules                                                       |
| Record an event          | `POST /api/v1/domains/{domain_id}/events`   | Add domain-shaped evidence/state                                            |
| Query                    | `POST /api/v1/domains/{domain_id}/query`    | Reason over the available domain state                                      |
| Explain                  | `POST /api/v1/domains/{domain_id}/explain`  | Inspect support, missing evidence, and `conflicts` using the route contract |
| Submit feedback          | `POST /api/v1/domains/{domain_id}/feedback` | Send an outcome signal                                                      |

## Domain definition and lifecycle

A Domain is owner-scoped. The authenticated identity owns its definition, evidence, decisions, and learner state; a body `session_id` does not grant access to another owner's Domain.

| Lifecycle step                                     | UAT endpoint                                                                          |
| -------------------------------------------------- | ------------------------------------------------------------------------------------- |
| List owned Domains                                 | `GET https://rei-neuroadapt-api.reilabs.org/api/v1/domains`                           |
| Read one owned definition                          | `GET https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}`               |
| Reset feedback-policy learned state                | `POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/policy/reset` |
| Delete the Domain, its evidence, and learned state | `DELETE https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}`            |

`POST /schemas` replaces the supplied schema section and `POST /rules` replaces the supplied hypotheses, templates, or learning section. Send the complete desired section rather than a partial patch. Domain routes already scope retrieval to the path `domain_id`, so do not duplicate it in a metadata filter.

Use the reset route only when the intended boundary is feedback-policy learning. Use deletion for a cold Domain evaluation; see [Operations and retries](/docs/neuroadapt/operational-behavior-and-retries) for the reset-scope matrix.

## Response fields

Choose the field that answers the application question. Depending on the route and domain, that may be `items`, `ranked_hypotheses`, `missing_evidence`, `predicted_observations`, `core_support`, or `policy_scores`.

These fields expose the behavioral result of the current domain state. They do not reveal or define all of Core's internal machinery.

## Domain events and adaptive-policy events

`POST /api/v1/domains/{domain_id}/events` records a normal domain event. `POST /api/v1/domains/{domain_id}/adapt/events` updates an online adaptive policy and returns `prediction.<output_key>`.

Use the route whose output contract matches the desired result.

## Domain reuse

Reuse one domain across episodes or deployments that share the same public task semantics. Record any adapter, action dictionary, outcome translation, or workflow hint as part of the information condition. Changing those semantics changes what Adapt-1 is being asked to reason over.