Author a Domain ontology

This guide is the authored ontology path. Use it when task-facing structure should be explicit and reviewed before use. If the task boundary is clear but you want Adapt-1 to form the learner-facing structure from admitted evidence, start with Discovery instead. A Domain is still the stable public contract and scope for the task. Authored ontology is one way to populate that scope, not a requirement for using Domains. This choice does not determine the acquisition schedule: an authored Domain can learn from zero during a run, and a Discovery Domain can form state in a separate acquisition phase before frozen use. A Domain is not a prompt, a task solution, an environment, or a complete architecture description.

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

Start with the application contract you already have. Most Domains should use defaults. Add learner configuration only after the interaction loop is clear in ordinary language. A Domain is not required when the application only needs continuing evidence or constraints without a declared task grammar.

Define five things

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

These five answers are enough to begin. Entities, relations, policies, hypotheses, transition mappings, grouping, and support controls are ways to express the answers when the task needs them. They are not prerequisites for understanding a Domain.

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

This is a design worksheet, not a universal API request body.

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

The selected route returned by Core, the route committed by the application, and the route executed externally are separate records. Preserve all three when validation or overrides can change the value.

Adaptation in three frames

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. A later result is not guaranteed to change or improve after one event. Verify event eligibility, confirm learner admission where exposed, inspect the applicable state change when documented, and preserve the later result separately.

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. It should not declare that a particular current action will cause completion unless that rule is intentionally public task information. A fresh Domain can begin with no accumulated task history. Supplying the vocabulary is not supplying the task-specific mapping. It gives Core the interface needed to participate.

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 should accumulate, but there is no action-outcome learner requirement	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

Ordered data is not automatically sequential learning. Sequential credit fits only 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?

A Domain can use more than one relationship, but each should have a separate evidence and result meaning.

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 any of those meanings must not mix. Inputs coming from the same dataset, application, device, or environment do not require one shared Domain. Different target geometries, feedback meanings, or evaluation boundaries may need isolated state. 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 contract exists, but no prior task events or retained Domain state are inherited
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, not held-out transfer. Cold does not mean no Domain definition. Frozen does not mean no learned state. Transfer does not mean the task contract changed.

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. A successful event write does not prove that every configured learner accepted the event. Advanced workflows should inspect learner admission and the applicable learner version before interpreting an unchanged result.

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	Events are ordered, but an earlier action does not change a later state or need credit from a later outcome	Preserve order without enabling sequential credit
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

Build

Advanced Domain design

Operate

Modalities

Domains

Interval policies

State

System

Spatial Vision API

Define five things

Copy this worksheet

Follow the example through one complete loop

Adaptation in three frames

What belongs in the Domain

Define one complete loop

Choose learning only after the loop exists

One Domain or several

State lifecycle

Minimal route map

Domain smell test

Choose how a Domain learns

Transition learning, advanced

Learn from outcomes

Run an inspectable workflow

​Define five things

​Copy this worksheet

​Follow the example through one complete loop

​Adaptation in three frames

​What belongs in the Domain

​Define one complete loop

​Choose learning only after the loop exists

​One Domain or several

​State lifecycle

​Minimal route map

​Domain smell test

Choose how a Domain learns

Transition learning, advanced

Learn from outcomes

Run an inspectable workflow

Define five things

Copy this worksheet

Follow the example through one complete loop

Adaptation in three frames

What belongs in the Domain

Define one complete loop

Choose learning only after the loop exists

One Domain or several

State lifecycle

Minimal route map

Domain smell test