調整指南

把 Heddle 調整至既有技術棧

Heddle 的傳輸層中立託管邊界是受支援基礎。若某個框架尚無受維護的可執行 adapter，應保留此邊界，不要機械式複製 Express 參考。

客製化深度

自訂傳輸

託管深度

既有伺服器或客戶端技術棧

文件狀態

調整指南

前置假設

產品已經有應保留的 server framework、transport、identity model 或 frontend architecture。
你可以把 active run 的所有操作路由到擁有者行程，或提供共享傳遞基礎設施。
你會驗證不受信任的 payload，並只公開經授權的欄位。

Heddle 負責

傳輸層中立的對話與 run service。
穩定 run ID、依序 sequence、有界重播、明確取消、核准與單一終結事件。
當符合所選 transport 時，可選用可重用的 Node SSE 與 browser REST/SSE mechanics。

產品端負責

Framework adapter、route 或 procedure design、authentication、authorization 與對外 schema。
Transport handle、delivery guarantee、process routing、draining 與 distributed infrastructure。
Client state、rendering、recovery persistence、retry UX 與 application-specific result。

保留生命週期，不要照搬範例框架

每一個 adapter 都必須保留同一套順序：

驗證呼叫者身分。
解析經授權的產品對話位址。
啟動一個回合並回傳穩定的 runId。
使用最後完整接受的 afterSequence 訂閱。
傳送單調遞增的依序 event，且只重播較新的 event。
訂閱端斷線只影響該訂閱端。
對確切 run 公開明確的 cancel 與 approval resolution。
只傳送一個 result、cancelled 或 error terminal。
在 settlement 時 refresh 或 reconcile durable conversation 與 product state。

不要建立第二個 run ID、另一條 event bus、interface-specific completion flag 或 browser-only conversation history。這些 abstraction 會複製 Heddle 已擁有的語意，造成 reconnect 或 cancellation 不一致。

伺服器框架指南

Fastify 或使用 Node HTTP 的 Nest

把 ConversationRunService 留在 application layer。Route hook 先驗證身分與授權，再呼叫 service。若 framework 提供相容的 Node request/response object，可組合 streamConversationRunSse；否則請透過 framework streaming API 實作相同的 sequence 與 disconnect rule。Heddle 目前沒有提供受維護的 Fastify 或 Nest router。

tRPC

把 start 與 cancel 公開為 mutation，把 ordered run activity 公開為帶有 runId 與 afterSequence 的 subscription 或 stream。Terminal 發布前先把 internal result 投影成 public schema。不要包裝 Express router，也不要 serialize Heddle internal session object。

Hono 或 Fetch API server

使用傳輸層中立的 hosted service，並透過平台的 Request、Response 與 stream primitive 實作串流。Node SSE helper 以 Node response semantics 為目標，不要假設它可以原封不動地用在 edge 或 worker runtime。

WebSocket

Subscription message 應帶有 runId 與最後接受的 sequence。保留標準 run envelope。Socket 關閉仍不代表取消；cancel 必須是明確且經授權的 message。重新連線必須要求 replay，不可啟動另一個 turn。

Electron 或原生 IPC

把 engine 與 run service 留在受信任的 backend process。透過 IPC 傳送 accepted run reference 與 public event envelope。Renderer 即使在本機，也不應因此收到 Node credential、internal tool payload、trace 或 storage path。

Queue 與 worker

Queue 可以分派 execution，但宿主必須決定 active run 位於何處、subscribe/cancel operation 如何到達它、worker 如何排空，以及 event 是否需要 durable delivery。Process-local replay service 不是 distributed broker。

前端指南

請在產品既有的 query 或 state architecture 下方使用 @roackb2/heddle-remote。React 是參考，不是必要條件。Vue、Svelte、Solid、mobile、desktop 與 state-machine client 都應保留 durable conversation read、live run subscription 與 local presentation state 的分工。

非 JavaScript client 可以實作文件化 JSON envelope 與 sequence rule，但 Heddle 目前沒有為其他語言提供官方 client。請把這條路徑標示為 adaptation，並為 parsing、duplicate suppression、sequence gap、terminal handling 與 reconnect 加入 conformance test。

多行程與 serverless 宿主

接受 run 前，先決定哪個 process 在整個生命週期擁有它。後續 subscribe、cancel 與 approval request 都必須到達該 owner。若 request 可能落到任意 instance，請加入符合產品需求的 sticky routing、shared run directory 或 durable event infrastructure。也要定義 draining：停止接受新工作、保留或轉移 active ownership，並讓 terminal projection 在關閉前完成。

這些都是宿主架構責任。Heddle 刻意不替產品選擇 Redis、Kafka、workflow engine 或其他 broker。

Adapter 驗證

交付前請證明：第二個回合重用同一個 Heddle session；斷線不會取消；從 sequence N 重新連線不會重啟 turn 或重複先前 event；另一個 authenticated scope 無法 subscribe 或 cancel；明確 cancellation 會產生 cancelled terminal；只有預期的 public field 會跨越邊界。