Adaptation guide
Adapt Heddle to the stack you already operate
Heddle's transport-neutral hosted boundary is the supported foundation. Frameworks without a maintained runnable adapter should preserve that boundary rather than copy the Express reference mechanically.
Customization depth
Custom transport
Hosting depth
Existing server or client stack
Documentation status
Adaptation guide
Assumptions
- Your product already has a server framework, transport, identity model, or frontend architecture it should keep.
- You can route all operations for an active run to its owning process or provide shared delivery infrastructure.
- You will validate untrusted payloads and expose only authorized public fields.
- Transport-neutral conversation and run services.
- Stable run IDs, ordered sequences, bounded replay, explicit cancellation, approvals, and one terminal.
- Optional reusable Node SSE and browser REST/SSE mechanics when they match the chosen transport.
- Framework adapter, route or procedure design, authentication, authorization, and public schemas.
- Transport handles, delivery guarantees, process routing, draining, and distributed infrastructure.
- Client state, rendering, recovery persistence, retry UX, and application-specific results.
Preserve the lifecycle, not the sample framework
Every adapter must preserve the same sequence:
- Authenticate the caller.
- Resolve an authorized product conversation address.
- Start a turn and return its stable
runId. - Subscribe with the last fully accepted
afterSequence. - Deliver monotonically ordered events and replay only newer events.
- Treat subscriber disconnect as subscriber-only.
- Expose explicit cancel and approval resolution against the exact run.
- Deliver exactly one result, cancelled, or error terminal.
- Refresh or reconcile durable conversation and product state at settlement.
Do not create a second run ID, separate event bus, interface-specific completion flag, or browser-only conversation history. Those abstractions duplicate semantics already owned by Heddle and make reconnect or cancellation inconsistent.
Server framework guidance
Fastify or Nest on Node HTTP
Keep ConversationRunService in the application layer. Route hooks authenticate and authorize before calling it. If the framework exposes compatible Node request and response objects, compose streamConversationRunSse; otherwise translate the same sequence and disconnect rules through the framework's streaming API. Heddle does not currently ship a maintained Fastify or Nest router.
tRPC
Expose start and cancel as mutations. Expose ordered run activity as a subscription or stream with runId and afterSequence. Project internal results into a public schema before terminal publication. Do not wrap the Express router or serialize Heddle's internal session object.
Hono or Fetch API servers
Use the transport-neutral hosted service and implement streaming with the platform's Request, Response, and stream primitives. The Node SSE helper targets Node response semantics, so do not assume it works unchanged in edge or worker runtimes.
WebSocket
Make subscription messages carry runId and the last accepted sequence. Keep the canonical run envelope intact. A socket closing is still not cancellation; cancel must be an explicit authorized message. Reconnection must request replay rather than start another turn.
Electron or native IPC
Keep the engine and run service in the trusted backend process. Carry accepted run references and public event envelopes over IPC. The renderer must not receive Node credentials, internal tool payloads, traces, or storage paths merely because it is local.
Queues and workers
A queue can dispatch execution, but the host must decide where the active run lives, how subscribe/cancel operations reach it, how workers drain, and whether events need durable delivery. The process-local replay service is not a distributed broker.
Frontend guidance
Use @roackb2/heddle-remote beneath the product's existing query or state architecture. React is a reference, not a requirement. Vue, Svelte, Solid, mobile, desktop, and state-machine clients should all retain the same separation between durable conversation reads, live run subscription, and local presentation state.
A non-JavaScript client can implement the documented JSON envelope and sequence rules, but Heddle currently ships no official client for other languages. Label that path as an adaptation and add conformance tests for parsing, duplicate suppression, sequence gaps, terminal handling, and reconnect.
Multi-process and serverless hosts
Before accepting a run, decide which process owns it for its lifetime. Later subscribe, cancel, and approval requests must reach that owner. If requests may land on any instance, add sticky routing, a shared run directory, or durable event infrastructure appropriate to the product. Also define draining: stop accepting new work, preserve or transfer active ownership, and allow terminal projection to finish before shutdown.
These are host architecture responsibilities. Heddle intentionally does not choose Redis, Kafka, a workflow engine, or another broker on the product's behalf.
Adapter verification
Before handoff, prove that a second turn reuses the same Heddle session; disconnect does not cancel; reconnect after sequence N neither restarts the turn nor duplicates earlier events; another authenticated scope cannot subscribe or cancel; explicit cancellation produces a cancelled terminal; and only intended public fields cross the boundary.