Author a Domain contract

Both authored and Discovery setups use a Domain to define the public task contract and scope its evidence and learned state. Use this guide to author explicit, reviewed learner-facing structure. Use Discovery when eligible inputs, representations, or supported bindings should form from admitted evidence. Choose the acquisition schedule separately. An authored Domain can begin with empty task-specific learned state, and a Discovery Domain can acquire state before frozen use.

Domain contract + current observation -> Core result
Core result -> external use or execution -> observable consequence
observable consequence -> later Domain behavior may change

Describe the application interaction before configuring learners. Use defaults until the task requires additional configuration. For continuing evidence or constraints without a declared task grammar, use the State gateway.

Define the interaction

Question	What to write
What stays stable?	Public object and field meanings, available operations, native outcomes, result schema, and episode boundaries
What is observable before the result?	Only the information the application can know at query time
What should Core return?	One machine-readable result the application can consume
What happens outside Core?	The commitment, execution, display, validation, or downstream use of that result
What can teach later behavior?	An observable transition, native outcome, correction, or feedback signal returned to the same scope

Use entities, relations, policies, hypotheses, transition mappings, grouping, and support controls as needed to express the contract. For Domain policy selection, declare each selectable option in the top-level hypotheses array when creating the Domain. Give competing options the same relation and each option a unique, non-null policy identifier. See Declare policy choices for a minimal example and the feedback loop.

Design examples and checks

Copy this worksheet

Domain scope:
Public vocabulary:
Observed before the result:
Available choices:
Result Core should return:
Observable consequence or feedback:
Episode, reset, and evaluation boundary:

Example:

Domain scope: route work items through one operating process
Public vocabulary: work item, queue, route, completed, failed
Observed before the result: item type, queue state, available routes
Available choices: route_a, route_b, defer
Result Core should return: selected route with ranked alternatives
Observable consequence or feedback: completion state and measured delay
Episode, reset, and evaluation boundary: one item; retained Domain state continues across items

Translate the completed worksheet into the fields accepted by the relevant API request.

Follow the example through one complete loop

The worksheet above describes one work-routing Domain. The complete interaction keeps the Domain, the current observation, the Core result, and the external consequence separate.

Stage	Work-routing example	Owner
Domain definition	Work item, queue, route, completed, failed, result shape, and item boundary	Application defines the public contract
Current observation	Item type, queue state, and currently available routes	External system exposes it; application maps it
Core result	Selected route with ranked alternatives	Core
Application commitment	Record the route actually accepted after validation or override	Application
External execution	Send the item through the committed route	Application and external routing system
Observable consequence	Completion state and measured delay	External system produces it; application measures it
Return path	Record the applicable consequence or feedback in the same Domain scope	Application
Later query	Supply the next current observation and request another route	Core can use relevant retained Domain state

Preserve the returned route and record any validation or override before execution, so feedback can identify the route that actually ran.

Inspect an update

Frame	What is available	What the frame shows
Cold result	Domain contract and current observation, with no inherited task events or retained Domain state	What the contract returns before task history accumulates
Eligible event or outcome	The committed route, exact external execution, and observable consequence are recorded; admission is confirmed where the route exposes it	What was recorded and whether the applicable state accepted it
Later result	A new current observation and any relevant retained Domain state	Whether later behavior can use the relevant retained state

When applicable evidence is admitted, support, learned relationships, policy or transition state, and a later result may change. The later result may also remain the same.Within the declared lifecycle, the Domain contract, public vocabulary, result type, and ownership boundary stay fixed. External state and external execution remain outside Core.Verify event eligibility and learner admission where exposed. Preserve the documented state changes and the later result to assess whether admitted evidence affected behavior.

What belongs in the Domain

Include public task semantics that remain stable across the intended scope:

Include	Keep out
Entity and field meanings	The correct answer for the current item
Observable relations and measurements	Hidden state unavailable at query time
Available actions or policies	A preferred action inserted by the adapter
Native outcome meanings	The action-effect mapping Core is expected to form
Event and episode boundaries	Oracle trajectories or solved plans
Result type and units	Private evaluator labels or downstream acceptance logic
Public intervention semantics	Target values that should remain withheld

A Domain may declare that completed is a positive native outcome. Include a rule connecting an action to completion only when that rule is public task information. A fresh Domain can expose the task vocabulary with an empty task-specific learning history. Core can then learn the action-effect mapping from admitted evidence.

Define one complete loop

Use the smallest loop that matches the application:

observe
query or select
commit to the value actually used
execute or use it outside Core
observe the consequence
record the transition or submit feedback
query again

Record the returned value, the value the application actually selected, and the exact operation executed. They may differ because of validation, overrides, ties, or downstream constraints.The consequence must be attributable to the applicable event or decision. Do not attach a later outcome to an earlier choice merely because both occurred in the same session.

Choose learning only after the loop exists

Task relationship	Starting point
Evidence and constraints within a declared task contract should remain available for later queries	Ordinary Domain with defaults
A committed choice receives its own attributable outcome	Domain feedback or contextual policy feedback
Current observations and an optional action should predict an observable result	Structured transition learning
Candidate actions should be compared by how they move a bounded public numeric state toward one objective	Bounded transition scoring
A later outcome must revise earlier choices that changed later states	Sequential learning
The mechanism itself should be returned and evaluated	Typed hypotheses with distinguishable observable predictions
One input should produce one independent result with no retained adaptation	Applicable stateless route

Use sequential credit when an earlier action changes the state encountered later and a later outcome should revise that earlier action.

Transition prediction, bounded objective scoring, and action value are different:

transition question: What happens after this input or action?
bounded objective question: How does each candidate move a public state toward the target?
policy question: Was this committed choice useful?

Assign each relationship in a Domain its own evidence and result meanings.

One Domain or several

Reuse one Domain when all of these remain compatible:

Public task semantics.
Result contract and units.
Consequence or feedback meaning.
Event and episode boundary.
State retention and evaluation lifecycle.

Use separate Domains when incompatible target geometries, feedback meanings, or evaluation boundaries require isolated state, including workflows fed by the same source. One Core instance can retain several Domains. Every operation addresses one domain_id, so their evidence and learned state remain separate.

State lifecycle

Name the lifecycle before evaluation:

Lifecycle	Meaning
Cold	The Domain starts with its contract and empty applicable task-specific learned state
Online adaptation	Events, outcomes, or feedback can update state during use
Held-out transfer	State formed from a separate acquisition partition is used on a new item or episode excluded before state formation
Frozen evaluation	Queries are read-only and the applicable learner state must not change
Rebuilt state	A known chronological record is processed into a new Domain or schema revision

State carried from an earlier pass or episode inside the same zero-start run is within-run retention. A cold run begins with its Domain definition in place. Frozen evaluation applies acquired state with writes disabled; held-out transfer evaluates that state on the excluded partition.

Minimal route map

Step	Route	Purpose
Create the contract	`POST /api/v1/domains`	Declare the Domain and schema
Record an event	`POST /api/v1/domains/{domain_id}/events`	Add Domain-shaped evidence or state
Query	`POST /api/v1/domains/{domain_id}/query`	Request the current contract-defined result
Explain	`POST /api/v1/domains/{domain_id}/explain`	Inspect support, missing evidence, conflicts, and applicable diagnostics
Submit feedback	`POST /api/v1/domains/{domain_id}/feedback`	Bind an observable outcome to the applicable decision or event

The Domain returned by create or read is the resolved contract and may include defaults filled by Adapt-1. Send only the fields your integration needs. Returned defaults do not need to be copied into later create requests. Inspect admission for each configured learner and its applicable version after an event write, including when the later result remains unchanged.

Domain smell test

Correct the design before implementation when any of these are true:

Smell	What is wrong	Correction
A withheld answer or hidden mapping is embedded in the Domain	The contract includes information the task expects Core to infer, such as the preferred action, target coordinates, hidden mapping, or solved plan	Keep intentionally public rules and legal choices; remove withheld task information
Post-result information appears in a pre-result input	A consequence, success label, or after-state is available only after the result or action	Keep it on the consequence, event, outcome, or feedback path
Chronology is treated as sequential credit	The declared objective provides each decision with its own attributable outcome	Preserve event order and use the applicable direct-feedback relationship
Incompatible result geometries share one learner target or evaluation contract	Scalars, categories, coordinates, poses, or paths are evaluated as if they had the same meaning	Separate learner views or Domains when result and feedback semantics differ
The state lifecycle is unclear	Cold, adaptive, transfer, frozen, reset, or rebuild stages cannot be distinguished	Name the lifecycle and verify which writes are allowed at each boundary

Choose how a Domain learns

Compare multistep action, hidden-process discovery, and structured prediction patterns.

Transition learning, advanced

Configure an observable before-state, action, target, support, grouping, and abstention contract.

Learn from outcomes

Bind decisions, commitments, execution, consequences, and scoped feedback.

Run an inspectable workflow

Preserve ordered provenance and verify the selected state lifecycle.

Get started

Concepts

Guides

Planning

Discovery

Operations

API reference

Define the interaction

Design examples and checks

What belongs in the Domain

Choose learning only after the loop exists

One Domain or several

State lifecycle

Minimal route map

Choose how a Domain learns

Transition learning, advanced

Learn from outcomes

Run an inspectable workflow

​Define the interaction

​Design examples and checks

​What belongs in the Domain

​Choose learning only after the loop exists

​One Domain or several

​State lifecycle

​Minimal route map

Choose how a Domain learns

Transition learning, advanced

Learn from outcomes

Run an inspectable workflow

Define the interaction

Design examples and checks

What belongs in the Domain

Choose learning only after the loop exists

One Domain or several

State lifecycle

Minimal route map