Run an inspectable stateful workflow

Define the state lifecycle and preserve an ordered record of Adapt-1 results and observable consequences.

Start one Adapt-1 workflow. Define its state lifecycle and input contract. Keep the calls in order. Record each Core result and external consequence.

This procedure is normal application setup. The application supplies observations and executes operations. Adapt-1 forms and changes task-relevant structure. The selected route returns the result.

Application boundary

Responsibility	Contribution	Data to record
Source system	Native observations and available operations	Exact data available before each Adapt-1 call
Adapter	Optional translation of format, features, or modality	Adapter version and translated fields
Adapt-1	Persistent reasoning, adaptation, prediction, support, or abstention	Complete route response and learner-state metadata
Application commitment	Maps, accepts, defers, selects between equal values, or overrides a returned value	Returned value, selected value, and selection rule
Executor	Applies the physical or software operation	Exact operation and parameters
Consequence source	Supplies the next observation, native consequence, or application feedback	External consequence and information returned to Adapt-1

If source data agrees with the route contract, an adapter is not necessary. If you use an adapter, translate only the observable interface. Do not supply the preferred answer or consequence relation.

State lifecycle

Before the first write, select a new state history or an existing state history.

Lifecycle	Use condition
New state history	The workflow must not inherit accumulated state from another application, tenant, Domain revision, or operational history
Continuing state history	Later interactions must use and change the existing learner state
Rebuilt state history	The application must process a known chronological record into a new Domain or schema revision

Use the clear or reset route for the applicable state. Domain state, session state, and interval-policy state have different scopes. Do not clear state between interactions that share learning.

Use one writer for ordered online state. Concurrent writers can change the event order. This change can affect the evidence available to later calls.

Input contract

Version the parts of the application boundary that determine what Adapt-1 receives:

• Domain and schema.
• Event boundary.
• Input and target paths.
• Numeric normalization and categorical representation.
• Grouping context.
• Adapter or feature extractor.
• Action dictionary.
• Consequence translation.
• response field consumed by the application.

A Domain can declare public action meanings, event types, and output vocabulary. Do not include private target state, the preferred procedure, or the consequence relation to learn.

For transition learning, keep the operational record, learner view, and application-only context separate. See Design Domains for transition learning.

Ordered provenance

Use stable identifiers that the selected request contract accepts. Keep an application interaction record:

{
  "workflow_id": "line-routing-v3",
  "interaction_id": "interaction-0042",
  "event_id": "event-0042",
  "domain_revision": "3",
  "adapter_version": "features-12",
  "result_ref": "result-0042",
  "returned_value": "route_left",
  "selected_value": "route_left",
  "selected_by": "adapt_1",
  "executed_operation": "route_left",
  "observable_consequence": "item_entered_lane_left",
  "feedback_returned": null
}

The JSON object is an application record. It is not a universal API request. Submit only the fields that the selected route accepts.

The important sequence is:

input supplied
-> Adapt-1 result
-> application commitment
-> exact execution
-> observable consequence
-> information returned

If a value changes between steps, keep the original value and the final value.

Transition-event admission

The API can store a Domain event that the structured-transition learner does not accept. Before you use transition output, confirm these contract fields:

• Event or memory ID.
• Required input, target, action, and grouping paths.
• Accepted or skipped learner status.
• Sample-count change.
• Skip reason.
• learner or subsystem version.

Storage does not prove that the transition learner received the observation.

Read-only inspection

Use the applicable Domain query and /explain to examine a result. Include the query and grouping context that the application normally supplies.

If the route supports these fields, disable exploration and memory-state updates:

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

Keep both complete responses. Confirm that the documented learner-state hash and applicable versions do not change during the read-only calls.

Inspect:

• The result used by the application.
• Evidence memory IDs and support.
• Selection or abstention reason.
• Missing evidence and disagreement.
• Hypothesis evidence when configured.
• Domain, schema, model, and subsystem versions.

See Explain and audit a result.

Ambiguous-write recovery

A gateway timeout can occur after the upstream service accepts an event or feedback write. Until the route specifies idempotency:

1. Send stable logical identifiers.
2. Persist the last response confirmed by the client.
3. Examine current state before you repeat a write that can cause two learner-state changes.
4. Resume from the last confirmed logical interaction.

Do not repeat a timed-out event or feedback request without a state check.

See Operate stateful and adaptive workflows.

Generated language

Structured Adapt-1 workflows do not require generated text. If the application generates language, record that operation, latency, and cost separately.

Workflow readiness checklist

• State lifecycle chosen explicitly
• Correct clear or reset route identified
• One writer for ordered state
• Domain, schema, adapter, and action contract versioned
• Application-private information kept outside the learner view
• Stable workflow, interaction, and event identifiers
• Complete route response preserved
• Returned value connected to application commitment
• Exact execution and observable consequence recorded
• Feedback returned to Adapt-1 kept separate from application-only consequence data
• Learner admission confirmed for transition events
• Read-only inspection leaves learner state unchanged
• Ambiguous writes reconciled before resubmission

This workflow keeps Adapt-1 state, inputs, decisions, execution, and consequences clear during operation.