JS client parity with Python: Node + browser + WASM integration plan

[haydnv]

Summary

Upgrade the JavaScript client so it reaches functional parity with the Python client for the supported TinyChain surface, with one consistent integration path across:

• Node.js runtime (server/SSR/proxy use cases)
• browser runtime (ESM + web app hydration)
• WASM-backed library workflows (including loading/installing a Library artifact and route invocation semantics)

This issue defines:

1. what is already complete on the backend vs still planned,
2. where JS differs from Python today,
3. how JS must integrate with the web client in Node and browser contexts,
4. concrete milestones and acceptance criteria.

---

Backend Status: Complete vs Planned

Complete (available now; client can target immediately)

• Canonical runtime URI namespaces and contracts are defined and stable (/state, /class, /lib, /service, /host, /healthz).
• tc-server currently serves /lib, /service, and /host with HTTP/PyO3/WASM adapter feature gates.
• WASM library install model and manifest expectations are documented and enforced:
  • Python Library.__json__ layout is canonical.
  • WASM method entries must include route/export mapping (wasm_export semantics).
• Python client already supports canonical library install paths and WASM install via tc.install(..., wasm=...).
• Web scaffold is wired to consume @tinychain/js and validates minimal request path (GET /healthz) across SSR + browser hydration.

Planned / In progress (must be reflected in JS parity planning)

• Full v1-equivalent transaction guarantees in tc-server remain roadmap work.
• Tensor route ownership is migrating to tc-collection as canonical owner (transitional compatibility in tc-state).
• Transactional tensor orchestration over fensor and integration with backend tensor storage/index work are roadmap items.
• Browser/WS transport expansion is planned; JS must maintain deterministic HTTP fallback semantics.

---

Current Gap: Python vs JavaScript

Python currently provides (baseline target)

• High-level Library authoring model and route decorators.
• Canonical install helpers for remote and WASM library flows.
• Host abstractions, URI builders, backend context switching, deferred planning.
• Rich symbolic tensor method surface and experimental autodiff package flow.
• Broader end-to-end examples and integration tests (including WASM-related flows).

JavaScript currently provides

• Minimal HTTP client wrapper (createTinyChainClient) with request and get.
• Local package consumed by web scaffold.

Missing in JavaScript (parity gaps)

• No JS Library authoring/install/runtime helper surface equivalent to Python.
• No parity tensor API and no autodiff-facing contract.
• No parity route/manifest helper layer.
• No parity fixture matrix proving behavioral equivalence with Python.
• No documented end-to-end Node + browser + WASM flow equivalent to Python examples.

---

Integration Requirements (Node + Browser + Web)

Node.js requirements

• Support canonical TinyChain client operations with server credentials held server-side only.
• Support install/runtime flows equivalent to Python where credentials and policy allow.
• Provide stable integration for SSR/proxy handlers used by client/web.

Browser requirements

• Browser-safe configuration only (no privileged token leakage).
• Same high-level request semantics for supported operations as Node.
• Deterministic fallback behavior when optional transports are unavailable.

Web client contract

• Keep client/js as the protocol/runtime implementation layer.
• Keep client/web as integration scaffold (SSR shell + hydration + initial state contract).
• Add parity integration tests that verify equivalent behavior between server and browser adapters for supported flows.

---

WASM + Library + Tensor/ha-ndarray Alignment

Define one canonical JS story for loading/using WASM-backed TinyChain libraries:

• Build/import a WASM binary plus canonical Library manifest metadata.
• Install/invoke through TinyChain runtime APIs without introducing non-canonical payload formats.
• Ensure route/export mapping semantics match backend expectations.
• Ensure tensor-oriented workflows remain aligned with backend ownership boundaries (collection-owned tensor semantics, transactional storage roadmap).
• Explicitly document what is supported now vs blocked on backend milestones.

---

Milestones

1. Parity matrix import (JS vs Python)

   • Import Python capability matrix and tag each row: implemented, planned, blocked-on-backend, out-of-scope.

2. Core API parity

   • Implement JS parity for canonical request/response/error semantics and manifest/URI helper behavior.

3. Install/runtime parity

   • Add JS equivalents for Library-centric install/runtime flows where supported.

4. Web integration parity

   • Prove Node SSR and browser hydration paths both run through the same JS client contract.

5. WASM flow parity

   • Add canonical JS WASM-backed library install/invoke path and tests.

6. Advanced parity gates

   • Add parity fixture suite against Python for supported tensor/runtime flows.
   • Mark blocked rows with explicit backend dependency references.

---

Acceptance Criteria

• A published JS parity matrix exists and is linked from client/js/ROADMAP.md.
• Every parity row has one owner and one status (implemented, planned, blocked-on-backend, out-of-scope).
• JS and Python pass cross-language fixtures for all rows marked implemented.
• client/web integration tests pass for Node and browser paths using the same JS client contract.
• WASM-backed library flow is documented and tested for currently supported operations.
• Blocked items are explicitly tied to backend roadmap dependencies (transactional guarantees, tensor ownership/storage milestones, transport maturity).

---

Non-goals

• Introducing non-TinyChain transport stacks or bespoke protocol shapes.
• Moving shard/transaction ownership semantics into browser-only logic.
• Shipping UI kits in client/js (belongs in client/web or downstream app kits).

---

Suggested Follow-up Tasks

• Create sub-issues for each milestone with fixture/test ownership.
• Add one status dashboard section in client/js/ROADMAP.md linking sub-issues.
• Add a parity CI lane that runs JS/Python cross-language fixture comparisons for implemented rows.

---

Security parity dependency

JavaScript parity includes the complete TinyChain authorization model; request/response API parity alone is insufficient.

Track the implementation through:

• Cross-runtime security umbrella: TinyChain-Inc/tcv2#48
• Canonical hierarchical permission/capability contract: TinyChain-Inc/tcv2#49
• Rust authoritative enforcement: TinyChain-Inc/tcv2#50
• Node.js server credential and delegation boundaries: TinyChain-Inc/tcv2#51
• Browser/WASM host capability boundaries: TinyChain-Inc/tcv2#52
• JavaScript authorization and manifest parity: TinyChain-Inc/tcv2#53
• Cross-runtime conformance suite: TinyChain-Inc/tcv2#54

Additional JavaScript acceptance criteria

• JS can declare immutable dependency whitelists and requested capabilities
• JS can author canonical owner/group/other hierarchical policies
• JS and Python serialize equivalent manifests and policies canonically
• Node preserves attenuated user authority instead of substituting ambient service authority
• Browser bundles and hydration state contain no privileged Node credentials
• Browser/WASM modules receive only manifest-authorized host imports
• Actual-browser conformance and adversarial tests pass, not only Node emulation
• The Rust server remains authoritative for every protected operation

Tembo-sized implementation issues

• [JS][J1] Publish parity matrix and canonical request, URI, and typed-error core #85 — parity matrix and runtime-neutral request/URI/error core
• [JS][J2] Implement Library, Service, Class manifest authoring and lifecycle helpers #86 — Library/Service/Class authoring and lifecycle helpers
• [JS][J3] Separate Node and browser adapters and validate SSR/hydration #87 — separated Node/browser adapters with SSR/hydration validation
• [JS][J4] Validate canonical WASM Library flow and cross-runtime parity #88 — actual-browser WASM Library flow and cross-runtime parity

Dependency order: #85 → (#86 and #87 in parallel) → #88. UI toolkit code remains in client/web and consumes this client contract; it does not belong in client/js.

automation:
  eligible: false
  executor_profile: tembo
  readiness: rollup
  primary_repository: TinyChain-Inc/client
  base_branch: main
  writable_scope: []
  prerequisites: ["#85", "#86", "#87", "#88"]
  concurrency_group: js-parity-rollup
  required_commands: []
  external_actions: none
  draft_pr_only: true
  completion_authority: human