feat(sdk/fresh): type-safe desktop bindings over oRPC MessagePort

[rickylabs]

Summary

Implement issue #842: a type-safe Deno Desktop bind-channel adapter that presents the structural MessagePort surface shipped oRPC expects, reuses NetScript's existing service contracts across the window boundary, and remains inert outside Desktop.

Closes #842
Part of #840

Closing-keyword decision: Closes #842 is retained. The live #842 issue has two acceptance boxes, and this PR proves both: (1) typed round-trip with native/procedure error shape, Uint8Array, and per-window isolation; (2) browser/Aspire no-op parity plus clean SDK/Fresh JSR surfaces. Issue #457's packaged desktop deploy-E2E remains open and unchecked; it is a separate deployment gate and is not an acceptance box in #842.

Scope

• @netscript/sdk/desktop: isolated bind-channel client/server port shim, oRPC RPCLink, and typed ServiceClient<TContract>
• @netscript/fresh/desktop: Desktop-gated RPCHandler.upgrade(port) and per-window bind/unbind lifecycle
• default string/binary transport, byte-preserving Uint8Array, native/procedure error mapping
• per-window isolation and browser/Aspire zero-side-effect no-op
• public consumer fixtures, JSR/doc rubric, full package tests, quality and architecture gates

Primary archetype: 4 — Public DSL / Builder, with adapter/runtime subtype gates and the frontend no-op overlay.

Harness

Run: .llm/runs/beta11-cli--orchestrator/slices/g3-842-bindings/

• Research complete
• Plan + Design checkpoint complete
• Tier-A group Plan-Gate PASS — D1–D16 locked
• Slice 1 — SDK shim/link/client
• Tier-A slice 1 review PASS
• Slice 2 — Fresh binding + acceptance matrix
• Tier-A slice 2 review PASS
• Slice 3 — consumer/JSR closeout
• Tier-A slice 3 review PASS
• IMPL-EVAL PASS
• CI green

Definition of Done

• Existing NetScript/oRPC contract types the Desktop client without bindings.d.ts
• Native and procedure errors expose name, message, and stack
• Uint8Array crosses the SDK shim and Fresh/oRPC procedure boundary byte-for-byte
• Two same-named Fresh window bindings remain isolated
• Browser/Aspire capability shapes perform no binding side effect
• Full SDK and Fresh test directories pass in the final slice
• SDK and Fresh public self-subpath consumer fixtures compile
• New SDK/Fresh entrypoints are independently doc clean
• Both raw package publish dry-runs pass with intended file lists and no slow-type diagnostic
• Exact/focused quality:scan, focused/root arch:check, specifier guard, and release text-import preflight pass
• Packaged native desktop deploy-E2E — explicitly deferred to open issue test(deploy): single-artifact deploy-e2e — install → update → rollback (Windows + Linux) #457

Final validation

Final commit: 007f2be299b482e682888cd85858be3151f67bef

• full SDK tests: 36 passed / 0 failed
• full Fresh tests: 206 passed / 0 failed
• SDK wrappers: 75 files; check/lint/fmt zero findings
• Fresh wrappers: 170 files; check/lint/fmt zero findings
• SDK and Fresh desktop entrypoint doc lint: zero findings each
• full-package doc baselines unchanged: SDK 1 unrelated transitive finding; Fresh 40 unrelated findings
• both raw publish dry-runs: PASS; no slow-type diagnostics
• Fresh compile-only consumer fixture explicitly excluded from published files
• exact and combined SDK/Fresh quality scans: PASS
• focused SDK/Fresh and root architecture checks: exit 0 with bounded existing warnings
• emitted-JSR-specifier guard: PASS
• release text/import-attribute/file-URL/self-import preflight: PASS
• no compatibility cast; no experimental_transfer; no published text/JSON import attributes

Drift / debt

The feature branch was synchronized to integration e6e1be08 after G2 landed. Existing SDK/Fresh documentation and doctrine warnings remain precisely bounded in the run artifacts. The new desktop entrypoints contribute zero doc findings and introduce no new architecture debt.

IMPLEMENTATION COMPLETE. Awaiting Tier-A slice-3 review and supervisor-dispatched separate-session IMPL-EVAL. Do not merge until CI is green and the required opposite-family evaluation passes. No release publish or milestone 13 closure is authorized by this PR.

[rickylabs]

[PHASE: PLAN]

Plan & Design — READY FOR REVIEW

G3 #842 research, plan, and the Design checkpoint are complete. No product implementation file exists, and the implementation hard stop remains active.

Scope locked

• SDK @netscript/sdk/desktop: per-window bind-channel client/server port shim, oRPC RPCLink, and existing ServiceClient<TContract> composition
• Fresh @netscript/fresh/desktop: Desktop-gated RPCHandler.upgrade(port) plus bind/unbind lifecycle
• full-duplex send / long-poll receive / close protocol with no process-global state
• default oRPC string/binary serialization; no experimental_transfer
• typed round-trip, native/procedure {name,message,stack}, Uint8Array, two-window isolation, and browser/Aspire no-op
• full SDK/Fresh test directories and per-slice JSR/quality/architecture gates

Planning commits

• 2bdd88249a8e0cb0879645e7fda5cbf380e86656 — research, plan, Design checkpoint, baselines, drift, and pending PLAN-EVAL placeholder
• 056a743d97eb9fa688422de0a5c5061e2e22a9f1 — PR metadata and supervisor handoff reconciliation

Artifacts

• research.md
• plan.md
• worklog.md — Design checkpoint
• plan-eval.md — pending supervisor evaluator

Baseline evidence

Gate	Result
Seven run artifacts	formatted; diff-clean; no template placeholders
Product/package diff	none
SDK raw publish dry-run	PASS; no actual slow-type diagnostic
Fresh raw publish dry-run	PASS; no actual slow-type diagnostic
SDK doc lint	one unrelated transitive private-ref baseline; new G2 entrypoint clean
Fresh doc lint	existing 40-finding baseline recorded; new desktop entrypoint must be independently zero
Installed oRPC surface	1.14.6 client/server MessagePort declarations and implementation inspected with deno doc
Branch base	synchronized to integration e6e1be08, including G2 #841

Supervisor action

Please run the separate-session PLAN-EVAL under the harness protocol and record PASS or FAIL_PLAN in plan-eval.md and on this PR. This implementation session has not dispatched an evaluator or review.

HARD STOP: no implementation slice starts before the group Plan-Gate records PASS. No merge, release publish, or milestone 13 closure is being performed.

[rickylabs]

IMPL — Slice 1 SDK transport — READY FOR TIER-A REVIEW

Scope: completed the locked SDK slice only: @netscript/sdk/desktop bind-channel client/server shim, native binding resolver and error normalization, oRPC RPCLink, typed contract-derived client, symmetric Uint8Array value serializer, public docs, and consumer/type fixtures.

Commit: a77b210c2a91d1c49e95017257dbee4cf7a6cb98
Push: HEAD:refs/heads/feat/desktop-frontend-842-bindings

Gate evidence

• deno task --cwd packages/sdk test — PASS, full directory, 36 passed / 0 failed
• scoped SDK check/lint/fmt wrappers — PASS, 75 files / 0 findings
• exact deno task quality:scan — PASS, 0 repository findings
• focused deno task quality:scan --root packages/sdk — PASS, 0 findings; two documented negative-fixture allowances
• focused SDK doctrine check + root arch:check — PASS (exit 0; bounded baseline warnings only)
• deno doc --lint packages/sdk/src/desktop/mod.ts — PASS
• SDK JSR audit + raw publish dry-run — PASS
• no published text/JSON import attributes; no experimental_transfer

D7 review bar

The adapter gives oRPC a real platform MessagePort. The test assigns that endpoint directly to the installed oRPC SupportedMessagePort type with no cast. The link factory likewise exposes a package-owned structural link surface; there is no compatibility cast in production or acceptance tests.

Acceptance covered in this slice

• typed oRPC round-trip from an existing contract, with no bindings.d.ts
• string and byte-for-byte Uint8Array payloads
• native {name,message,stack} rejection rehydration
• one receive pump, FIFO delivery, exact-once close
• two same-protocol server instances remain isolated

The PR retains Closes #842 because all issue acceptance gates are owned by this PR's locked slices; the body now states that rationale and leaves the Fresh/no-op gates visibly unchecked until slices 2–3.

PAUSED: awaiting supervisor Tier-A slice-1 review. I have not dispatched an evaluator, merged, published, or closed the milestone.

[rickylabs]

IMPL — Slice 2 Fresh Desktop runtime — READY FOR TIER-A REVIEW

Scope: completed the locked Fresh slice: @netscript/fresh/desktop structural Desktop capability gate, package-owned router/window contract, RPCHandler.upgrade composition, per-window bind ownership, explicit bound/disabled lifecycle, and memoized close/unbind.

Commit: 71efb7890abfa28a77fe2ad83c62b4679e1e93f0
Push: HEAD:refs/heads/feat/desktop-frontend-842-bindings

Gate evidence

• deno task --cwd packages/fresh test — PASS, full src + tests, 206 passed / 0 failed
• deno task --cwd packages/sdk test — PASS, full directory, 36 passed / 0 failed
• scoped Fresh check/lint/fmt wrappers — PASS, 169 files / 0 findings
• exact and Fresh-focused quality:scan — PASS, no new findings
• focused Fresh doctrine + root arch:check — PASS (exit 0; bounded existing warnings)
• deno doc --lint packages/fresh/src/runtime/desktop/mod.ts — PASS, zero findings
• structured full Fresh doc scan — unchanged baseline: 40 unrelated findings; desktop contributes zero
• Fresh raw publish dry-run — PASS, intended production files; tests excluded; no slow-type finding
• NetScript emitted-JSR-specifier guard — PASS
• no casts in the Fresh Desktop implementation, no text/JSON import attributes, no experimental_transfer

D11–D13 behavior

• capability detection happens before server construction or native registration
• oRPC upgrades the real SDK MessagePort before window.bind
• each bind call owns one independent server port; two same-named windows remain isolated
• browser, Aspire-like Deno, and missing-window shapes return inert lifecycle handles with zero bind/unbind calls
• cleanup closes the SDK port and memoizes native unbind, so concurrent/repeated close() calls unbind once
• bind failure closes the already-upgraded server before rethrowing

Acceptance covered

The full Fresh task proves typed strings, byte-for-byte Uint8Array, oRPC procedure error name/message/stack, two-window isolation, browser/Aspire no-op parity, binding-name validation, and lifecycle cleanup. Combined SDK native-error mapping remains covered by the full SDK task.

Post-slice reconciliation confirmed issue #842 and PR #853 are open/draft on milestone 13 with sole status:impl; Closes #842 remains correct because slice 3 owns only the planned consumer/JSR closeout.

PAUSED: awaiting supervisor Tier-A slice-2 review. No evaluator was dispatched; no merge, release, or milestone-close action was taken.

[rickylabs]

[PHASE: IMPLEMENTATION] IMPLEMENTATION COMPLETE — READY FOR TIER-A S3 REVIEW / SUPERVISOR IMPL-EVAL

S3 scope

Final consumer/docs/JSR closeout is complete at 007f2be299b482e682888cd85858be3151f67bef and pushed with the explicit refspec HEAD:refs/heads/feat/desktop-frontend-842-bindings.

• added a compile-only Fresh consumer fixture that imports the public @netscript/fresh/desktop self-subpath and context-types an oRPC router
• added paired SDK/Fresh desktop usage and lifecycle documentation
• excluded the compile-only Fresh fixture from the published package
• completed the two-package JSR evidence set and final acceptance mapping
• preserved D7: structural oRPC port compatibility with no compatibility cast
• preserved the locked serialization design: top-level Uint8Array frames and no experimental_transfer

Final gate evidence

• SDK full test directory/task: 36 passed, 0 failed
• Fresh full test directory/task: 206 passed, 0 failed
• SDK scoped check/lint/fmt wrappers: 75 files, zero findings
• Fresh scoped check/lint/fmt wrappers: 170 files, zero findings
• SDK desktop entrypoint deno doc --lint: zero findings
• Fresh desktop entrypoint deno doc --lint: zero findings
• full-package doc baselines unchanged: SDK 1 unrelated transitive finding; Fresh 40 unrelated findings
• SDK raw publish dry-run: PASS, intended files, no slow-type diagnostic
• Fresh raw publish dry-run: PASS, intended files, no slow-type diagnostic
• Fresh consumer fixture exclusion from publish list: confirmed
• exact feature and combined SDK/Fresh quality:scan: PASS
• focused SDK/Fresh and root arch:check: exit 0, bounded pre-existing warnings only
• emitted JSR specifier guard: PASS
• release preflight for text/import attributes, file URLs, and self-imports: PASS
• published-code scan: no compatibility cast, no experimental_transfer, and no text/JSON import attributes

Acceptance and closing-keyword decision

The PR retains Closes #842. The live issue has two acceptance boxes and both are provably covered here:

1. typed round-trip, native/procedure error shape { name, message, stack }, byte-preserving Uint8Array, and per-window isolation
2. browser/Aspire zero-side-effect no-op parity plus clean SDK/Fresh public and JSR surfaces

The packaged native desktop deploy-E2E tracked by #457 remains open and unchecked. It is a separate deployment gate, not an acceptance checkbox in #842; this PR does not claim or mutate that gate.

Handoff

The PR is now ready for review with sole status status:impl-eval. Awaiting Tier-A S3 review and the supervisor-dispatched, separate-session IMPL-EVAL.

No evaluator was self-dispatched. No merge, release publish, tag, canary/stable cut, or milestone closure was performed.