docs(sdk): document runtime bridge seam, strict mode, and fallback policy

This commit is contained in:
Tom Boucher
2026-05-05 19:29:59 -04:00
parent 1bd11ab699
commit 54b06e653e
4 changed files with 40 additions and 2 deletions

View File

@@ -1,5 +1,8 @@
# Dispatch policy module as single seam for query execution outcomes
- **Status:** Accepted
- **Date:** 2026-05-03
We decided to centralize query dispatch outcomes in one Dispatch Policy Module that returns a structured union result (`ok` success or failure with typed `kind`, `details`, and final `exit_code`) instead of mixing throws and ad-hoc error mapping across CLI and SDK paths. This keeps fallback policy, timeout classification, and exit mapping in one place for better locality, prevents drift between native and fallback behavior, and makes callers thin adapters over a stable interface.
## Amendment (2026-05-03): query seam deepening completion
@@ -24,3 +27,15 @@ Removed wrapper Modules after call-site convergence:
- `query-registry-capability.ts`
This amendment preserves the original ADR direction: keep policy depth high, adapters thin, and locality concentrated in explicit modules.
## Amendment (2026-05-05): SDK Runtime Bridge seam deepening
To make SDK dispatch a cleaner publishable seam, we deepened `GSDTools` dispatch behind one **SDK Runtime Bridge Module** (`sdk/src/query-runtime-bridge.ts`) and converged policy wiring into that seam:
- `GSDTools` callers now route through one runtime bridge Interface for command resolution, execution, and hotpath dispatch.
- Added explicit fallback policy at the seam (`allowFallbackToSubprocess`) instead of implicit transport behavior.
- Added strict native-only enforcement mode (`strictSdk`) so SDK consumers can fail fast when a command lacks a native adapter.
- Added structured bridge observability (`onDispatchEvent`) for dispatch mode, fallback reason, latency, outcome, and error kind.
- Kept transport and command callers as thin adapters over the bridge seam.
This continues the dispatch-policy design goal: deep policy Modules, thin Adapters, and high locality for behavior changes.