feat(3555): QueryRuntimeBridge.executeForCjs synchronous primitive (Phase 5.0 of #3524)
Phase 5.0 of the CJS↔SDK hard-seam migration (parent #3524). Foundational PR. Ships ONLY the synchronous primitive on the SDK runtime bridge plus pinning tests. Per-family CJS router migrations (state.*, verify.*, init.*, phase.*, phases.*, validate.*, roadmap.*, frontmatter.*, config.*) become follow-up enhancements that each reuse this primitive. ## What landed - sdk/src/runtime-bridge-sync/index.ts (155 lines) — public API. Exports executeForCjs(input: RuntimeBridgeExecuteInput): RuntimeBridgeSyncResult. Synchronous; lazily creates the synckit sync function on first call. - sdk/src/runtime-bridge-sync/worker.ts (167 lines) — synckit worker. Constructs a native-only QueryRuntimeBridge (with allowFallbackToSubprocess: false), awaits its async execute, catches GSDToolsError / GSDError, maps classification to the six ADR-0001 canonical error kinds plus exit code. - sdk/src/runtime-bridge-sync/index.test.ts (197 lines, 8 vitest pinning fixtures) — success path; unknown_command; native_failure (shape); validation_error (shape); shape invariants; idempotency. - tests/runtime-bridge-sync-smoke.test.cjs (99 lines, 4 node:test cases) — proves the primitive works from CJS callers via require(). ## Decisions 1. Synchronous-bridging mechanism: synckit. Disqualified: - deasync: stagnant (68 open issues, single maintainer, last release Nov 2025), private Node API (process.binding('uv')), untested on Node 22, documented deadlocks with modern Promise chains. - Sync-native SDK refactor: technically infeasible — acquireStateLock in state-mutation.ts uses await setTimeout for retry backoff; making that fully sync requires either Atomics.wait (which IS synckit), busy-loop (degrades responsiveness), or breaking 100+ SDK consumers. Synckit (v0.11.12) is pure JS, actively maintained (last push today), stable public APIs (Atomics.wait + SharedArrayBuffer), Node 22 compatible, no native compile. 2. Native-only transport inside the worker. The sync bridge uses allowFallbackToSubprocess: false. Unknown commands surface as unknown_command instead of spawning gsd-sdk. Keeps the worker self-contained and predictable. 3. Worker path resolution. resolveWorkerPath() navigates ../.. from the loaded module URL to land at dist/runtime-bridge-sync/worker.js — works under both vitest (loads src) and CJS consumers (load dist). 4. GSDError.Blocked → validation_error. ADR-0001's 6-kind taxonomy has no `blocked` kind; Blocked classification is mapped onto validation_error since the operational shape matches (prerequisite missing). ## Numbers - 8 SDK vitest pinning tests pass. - 4 CJS smoke tests pass. - Full suite: 9286/9286 pass (baseline 9282; +4 from the new smoke test cases). - SDK vitest unit: 1860/1860 pass. - Performance: 80ms first-call cold latency (Worker startup + bridge construction); 0.1ms steady-state per-call latency (10-call average after warmup). Well within budget for CJS dispatcher overhead. ## Canonical error kind coverage - unknown_command: covered with pinning fixture - native_failure: shape coverage (handler that throws) - validation_error: shape coverage (GSDError.Validation + GSDError.Blocked) - internal_error: shape coverage only (eliciting TypeError reliably from a registered handler requires elaborate fixture) - native_timeout: NOT pinned (no registered handler genuinely times out; classification logic present in worker) - fallback_failure: NOT pinned (subprocess fallback disabled by design in sync bridge) The classification logic is in the worker regardless; per-family migration PRs will exercise the unpinned kinds incidentally. ## Wiring - sdk/package.json: synckit ^0.11.12 added as runtime dependency (not devDependency — it's required at runtime whenever a CJS caller invokes executeForCjs). - sdk/package-lock.json: regenerated. - CONTEXT.md: new "Sync Runtime Bridge Module" entry added after Dispatch Policy Module. Existing "CJS Command Router Adapter Module" entry amended with one sentence pointing at the primitive and the per-family migration roadmap. No generator/freshness check needed for this phase — the primitive IS the SDK (not a generated CJS mirror). Closes #3555.
This commit is contained in:
28
sdk/package-lock.json
generated
28
sdk/package-lock.json
generated
@@ -10,6 +10,7 @@
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "^0.2.84",
|
||||
"synckit": "^0.11.12",
|
||||
"ws": "^8.20.0"
|
||||
},
|
||||
"bin": {
|
||||
@@ -802,6 +803,18 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@pkgr/core": {
|
||||
"version": "0.2.9",
|
||||
"resolved": "https://registry.npmjs.org/@pkgr/core/-/core-0.2.9.tgz",
|
||||
"integrity": "sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": "^12.20.0 || ^14.18.0 || >=16.0.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://opencollective.com/pkgr"
|
||||
}
|
||||
},
|
||||
"node_modules/@rollup/rollup-android-arm-eabi": {
|
||||
"version": "4.60.0",
|
||||
"resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.0.tgz",
|
||||
@@ -1694,6 +1707,21 @@
|
||||
"url": "https://github.com/sponsors/antfu"
|
||||
}
|
||||
},
|
||||
"node_modules/synckit": {
|
||||
"version": "0.11.12",
|
||||
"resolved": "https://registry.npmjs.org/synckit/-/synckit-0.11.12.tgz",
|
||||
"integrity": "sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@pkgr/core": "^0.2.9"
|
||||
},
|
||||
"engines": {
|
||||
"node": "^14.18.0 || >=16.0.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://opencollective.com/synckit"
|
||||
}
|
||||
},
|
||||
"node_modules/tinybench": {
|
||||
"version": "2.9.0",
|
||||
"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
|
||||
|
||||
Reference in New Issue
Block a user