Orchard SDKs v1 — TypeScript + Python, byte-equal by construction
Published 2026-05-28 · 6 min read
The FAI Orchard SDKs hit v1.0 today. Two packages, one promise: any program you write against `@frootai/sdk-orchard` (TypeScript / Node) will produce byte-equal results to the same program written against `frootai-sdk-orchard` (Python).
This isn't a marketing claim. It's a tested invariant.
What "byte-equal" actually means here
27 contract assertions run as part of CI on every release. Each assertion asks the question: "given these inputs, do both SDKs emit identical output bytes?" — and the answer must be yes, or the release fails.
The contract surface covers:
- Pagination cursors: a cursor returned by the TS SDK must decode identically in the Python SDK, and round-trip through both for at least 3 pages without drift
- Error envelopes: `OrchardError` has the same shape, same `code` strings, same `request_id` propagation
- Date serialization: ISO 8601 with millisecond precision and `Z` suffix on both
- Floating-point coercion: server returns integer ranks, both SDKs preserve as integer (no silent `Number` ↔ `int` drift)
- String collation: `localeCompare` (TS) and `unicodedata.normalize`
- sort (Python) produce identical orderings for any input
- Empty-state shapes: `{items: [], cursor: null}` on both, never `undefined` vs `None` divergence
The full 27-assertion list is in the conformance certificate JSON schema at /schema/conformance-certificate-v1.json.
Why this matters for agent workflows
Modern agent workflows often switch runtimes mid-flow:
- A user opens Cursor → invokes `orchard.search` via the npm MCP server
- Cursor returns a cursor (the pagination kind, not the editor)
- The user runs a downstream Python notebook to `orchard.show` each result
- The notebook hits the Python SDK with the cursor from step 2
If those two SDKs disagree on cursor shape, the workflow breaks at step 4.
By making byte-equal a tested invariant — not a hope — we guarantee mid-flow runtime switches work.
Same release, two ecosystems, same hour
Both SDKs publish from the same monorepo on the same Git tag:
```bash git tag orchard-v1.0.0-mcp git push --tags
→ npm publish + PyPI publish fire in parallel from the same workflow
```
Both publish with provenance:
- npm: Sigstore + publish attestations (verifiable with `npm audit signatures`)
- PyPI: PEP 740 attestations on every wheel + sdist (verifiable on pypi.org)
The cross-runtime conformance certificate is uploaded as a workflow artifact, SHA-256-fingerprinted, and linked from the GitHub Release body.
Zero runtime deps
Both SDKs ship with zero `dependencies` at runtime. The only production deps are the language standard libraries — `fetch` (now universal in Node) and `httpx`/`anyio` (which moved into Python's core orbit). Tarballs are sub-128-KiB on both ecosystems.
This makes the SDKs auditable by humans without a transitive-dep nightmare.
What's next
Phase A11 brings:
- Recorded GIF demos for each MCP client
- Smithery + Glama verified-publisher badges
- Per-Variety regional accelerator hubs
- Enterprise SSO MFA (step-up auth via RFC 9470)
- Agent skill marketplace
For now:
```bash npm install @frootai/[email protected]
or
pip install frootai-sdk-orchard==1.0.0 ```
Try it. The byte-equal promise is real.
— The FrootAI team
Related: