SPOKE Protocol

English

简体中文

English

简体中文

Appearance

Package quick-start ​

SPOKE ships consumer packages on lockstep SemVer — generated wire types, hand-written operations libraries, and Connect session clients (language-native TypeScript client, Rust reference, and native bindings). Pin all surfaces you use to the same X.Y.Z.

TypeScript (npm) ​

bash
pnpm add @42ch/[email protected] @42ch/[email protected]
  • @42ch/spoke-schemas — generated wire types (import KnowledgeEntry, TimelineEvent, PromoteRequest, AssemblePacket, HostCapabilityManifest, … from the package root).
  • @42ch/spoke-operations — pure helpers, capability-sliced adapter ports, and orchestrate* entrypoints.

Rust (crates.io) ​

bash
cargo add [email protected] [email protected]
toml
[dependencies]
spoke-schemas = "X.Y.Z"
spoke-operations = "X.Y.Z"
  • spoke-schemas — generated Rust wire types from the same JSON Schema SSOT.
  • spoke-operations — port traits + orchestrate_* (re-exports spoke_schemas).

Connect ​

Connect session clients ship alongside the wire/operations packages at the same lockstep SemVer:

bash
pnpm add @42ch/[email protected]
  • @42ch/spoke-connect — TypeScript language-native client.
  • @42ch/spoke-connect/remote — the RemoteAdapter subpath: dial a remote peer over a consumer Transport and route across multiple peers (see RemoteAdapter over a Transport).
bash
cargo add [email protected]
  • spoke-connect — Rust reference crate (libp2p transport + uniffi binding surface).

Native bindings for host languages (C# NuGet 42ch.Spoke.Connect, Kotlin Maven dev.42ch:spoke-connect, Swift SPM SpokeConnect, Go module github.com/42ch-dev/spoke/crates/spoke-connect/bindings/go, Python PyPI spoke-connect) and for C and C++ (hand-written C ABI, git) embed the shared session core via FFI — see Native bindings and Connect from C and C++.

C and C++ (git) ​

bash
git clone --branch vX.Y.Z --depth 1 https://github.com/42ch-dev/spoke.git
git lfs install   # once per machine
git lfs pull      # fetch the carrier libraries; a fresh clone smudges them automatically
  • crates/spoke-connect/bindings/cpp/include/spoke_connect.h — the hand-written C ABI header.
  • crates/spoke-connect/bindings/cpp/include/spoke_connect.hpp — the C++17 header-only convenience layer.
  • crates/spoke-connect/bindings/cpp/native/osx-arm64/libspoke_connect_capi.dylib — the macOS arm64 carrier.
  • crates/spoke-connect/bindings/cpp/native/win-x64/spoke_connect_capi.dll — the Windows x64 carrier.
  • crates/spoke-connect/bindings/cpp/native/win-x64/spoke_connect_capi.dll.lib — the Rust-produced import library the Windows x64 link step consumes.

The committed C/C++ carriers target macOS arm64 (osx-arm64) and Windows x64 (win-x64). Take spoke_connect.h, spoke_connect.hpp, and the native files for your target from the same repository tag vX.Y.Z — resolution is a tag checkout, while cargo add spoke-connect installs the crates.io crate. Full guide: Connect from C and C++.

Integrator path ​

  1. Import wire types from the schemas package.
  2. Implement the port families for the capabilities you claim on one adapter type (BaselineAdapter … FullAdapter).
  3. Call the matching orchestrator (orchestrateUpsert, orchestratePromote, orchestrateExtract, …) — pure gates run, and the persistence-bearing paths write through your ports. The optional ke-extraction path takes a standalone ExtractionPort plus an async extractor callback and returns provisional candidates for later admission through promote.
  4. Walk the committed "Mira at Harbor" graph and the reference ToyWorldAdapter in fixtures/toy-world/ (TypeScript adapter + Rust fixture crate).

Version policy ​

All packages bump together (lockstep SemVer); annotated tags vX.Y.Z match. See Version & release for the pin guide.

More resources ​