docs: rewrite sdk and rpc namespace docs to shipped contract - #601
Merged
Conversation
Rewrite 07 (rpc namespace) from a pre-code design essay into a terse description of the shipped chain interface: the chain.request / request-batch WIT surface, the closed ChainMethod read-only surface enforced host-side, the separate identity signing interface, the HostTransport / ProviderHost / block_on alloy provider seam, synchronous module handlers, videre:venue as the order-submission path, and the MockHost testing seam. Delete the aspirational cow-api namespace, shepherd-sdk crate, #[shepherd::module] macro, the Cow SDK type, MockProvider and MockCow, and the async-handler / block_on-elimination / provider-injection narrative that never shipped. Fix 05's videre-sdk crate layout: poll_once lives in client.rs, not a non-existent rt.rs, and add the event.rs and value_flow.rs entries. Part of #598.
mfw78
force-pushed
the
docs/598-sdk-rpc-design
branch
from
July 25, 2026 03:12
62b91ba to
851a0e3
Compare
Hard-wrapped prose churns diffs: a one-word edit reflows the whole paragraph. Join each paragraph onto a single logical line and let it soft-wrap. Content unchanged (word and heading counts preserved); code fences, tables, lists, blockquotes and headings untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrite
docs/07-rpc-namespace-design.mdfrom a pre-code design essay (1243 lines) into a terse description of the shippedchaininterface (78 lines), and fix thevidere-sdkcrate-layout drift indocs/05-sdk-design.md.07 now states only the shipped contract: the
chain.request/chain.request-batchWIT surface withrpc-request/rpc-resultrecords, the closedChainMethodread-only surface enforced host-side (off-surface methods refused with adeniedfault), the separateidentitysigning interface, theHostTransport/ProviderHost::provider/block_onalloy provider seam, synchronous module handlers,videre:venueas the order-submission path, and theMockHosttesting seam.Deleted the aspirational material that never shipped: the
cow-apinamespace, theshepherd-sdkcrate,#[shepherd::module], theCowSDK type,MockProvider/MockCow, and the async-handler / block_on-elimination / provider-injection narrative. Also dropped the Problem Statement, Core Insight, What This Replaces, before/after module-author experience, Option A vs Option B, Trade-Offs and Summary sections per the sweep standard.05 fix:
poll_oncelives inclient.rs, not a non-existentrt.rs; added the missingevent.rsandvalue_flow.rslayout entries.Why
Part of the #598 docs cruft-sweep. 07 described an architecture the runtime never shipped (macro-driven
&RootProviderinjection, async dispatch, acow-apihost namespace, a two-cratenexum-sdk/shepherd-sdksplit). The current tree enforces a closedChainMethodread surface innexum-world, dispatches synchronous handlers via#[nexum_sdk::module], and routes order submission through thevidere:venuevenue-adapter contract, not a chain namespace.Testing
Documentation-only. Pure markdown: verified no em dashes, Oxford
-izeprose, every retained claim checked againstcrates/nexum-sdk,crates/nexum-sdk-test,crates/nexum-module-macros,crates/videre-sdk,crates/nexum-runtimeandwit/nexum-hoston this branch; all cross-doc links resolve.AI Assistance
Documentation-only sweep; verification as above (grep-checked style and inbound links, code-checked every retained interface claim).
Part of #598.