What stays inside the bundle
The Adapter Host owns:
- the public HTTP entry points
- split ingress versus adapter token handling
- connector callback routing
- the route into the Core-backed decision path
- WorkOrder claim and outcome acceptance behavior
Core owns:
- validation of the decision path
- consistency checks across input, state, policy, and decision fields
- the gate between candidate decision and admitted work
Core does not materialize the external effect itself. The host does not invent a target-specific write path on its own.
What belongs in your adapter
Your adapter owns:
- target-specific state extraction
- target-specific policy logic
- target-specific materialization
- outcome reporting after the operation attempt
That means the adapter is where knowledge of your actual system lives. The bundle does not need to know how to open your pull request, move your workflow item, or update your account state. It only needs a bounded contract around the decision and handoff path.
The one flow to keep in your head
That is the architectural reason to build your own adapter instead of pushing target-specific logic into the host or bypassing the host entirely.
Which fields stay stable across the path
These fields are the practical glue for adapter authors:
| Field | Why you care |
|---|---|
| target_adapter | routes work to your adapter |
| target_ref | identifies the concrete target object or environment |
| target_scope | narrows the bounded scope inside the target |
| actor_ref | carries actor context through the decision path |
| task_ref | carries task context through the decision path |
| state_view_ref | binds the state read to the rest of the flow |
| decision_ref / decision_hash | bind the claim and later the outcome |
| work_order_ref / work_order_hash | bind the claimed work |
| lease_id | binds outcome reporting to the active claim |
You do not invent most of these values in the worker. You keep them intact once the host gives them to you.
The split in a concrete example
For a repository adapter:
claims and materializes one repository-side effect
- the host receives the intent and routes the connector calls
- Core validates the input, state, policy, and decision bindings
- the adapter reads repository state, returns a policy candidate, then later
For an ImpactRoom-style reference adapter, the same split holds:
materialization after claim
- the host still owns ingress, claim, lease, and outcome acceptance
- Core still owns decision-path validation
- the adapter owns room state reading, room-side policy rules, and room-side
The target can change completely while the boundary stays the same. That is the point of the split.
What you should not do
If you want the boundary to stay meaningful, avoid these patterns:
- importing private Core or Adapter Host internals into your adapter
- letting the worker materialize directly from raw client intent
- treating policy output as if it were already final admission
- rebuilding your own second decision system next to Core
The cleaner the split stays, the easier the system is to reason about later.