docs: trim platform generalisation and linker seam to current contract - #600
Merged
Conversation
Rewrite docs/08 as a terse description of the shipped layered WIT model: keep the Layer 1/2/3 world model, the verified universal interface signatures, the venue-adapter Layer 3 mechanics, and the complete WIT package layout; collapse the mobile, WebView, and super-app targets and their per-primitive implementation tables to one sentence each; cut the motivation essay, the host adapter specification, and the summary. Reduce the 0.2 status banner to one line and point the SDK and taxonomy topics at their owning docs. Rewrite docs/design/linker-extension-seam.md against the current Extension trait: drop the retired cow-api / shepherd-cow-host / CowBackend example, describe namespace, capabilities, link, service, provider, admit and event members, the HostServices and ExtState reach paths, and the videre venue platform as the live extension the shepherd binary registers. Align the reproduced WIT with wit/: chain request-batch takes rpc-request and returns rpc-result, the event variant carries custom, and identity and chain are stated at their actual reference-host behaviour. Part of #598.
mfw78
force-pushed
the
docs/598-platform-design
branch
from
July 25, 2026 03:13
56ed3a0 to
7b19512
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
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
Trim the two platform-design docs to a terse description of the shipped contract.
docs/08-platform-generalisation.md(1015 -> 312 lines): keep the Layer 1/2/3 world model, the universal interface signatures (verified againstwit/nexum-host), the venue-adapter Layer 3 mechanics, and the complete WIT package layout. Collapse the mobile, WebView, and super-app targets and their per-primitive implementation tables to one sentence each. Cut the motivation essay, the "key insight", the host adapter specification, and the summary. Reduce the 0.2 status banner to one line, and point the SDK and six-primitive taxonomy at their owning docs (05 and 00).docs/design/linker-extension-seam.md(121 -> 89 lines): rewrite against the currentExtensiontrait. Drop the retiredcow-api/shepherd-cow-host/CowBackendexample, and describe the trait's real members (namespace, capabilities, link, service, provider, admit predicates, event sources), theHostServicesandExtStatereach paths, and the videre venue platform as the live extension theshepherdbinary registers.Why
Both docs were design essays written before the code landed and had drifted from
dev/m1: they described the pre-venue-adaptercow-apiworld extension and anExtensionstruct that is now a trait, and they reproduced stale WIT. Part of the #598 cruft sweep.Testing
Documentation only, no build. Verified every retained WIT block and behavioural claim against
wit/andcrates/at thedev/m1tip; confirmed no other doc links to the trimmed sections (the#layer-3-domain-extensions-venue-adaptersanchor is preserved for docs 00 and 05). Purged em dashes.AI Assistance
Documentation-only sweep; claims verified against the worktree at the dev/m1 tip, no build required.
Deviations flagged
Substantive mismatches between the prior doc 08 and the current reference-server host, now stated at actual behaviour in the doc:
chaindoes not delegate signing toidentity. The old doc claimedchain::requesthandleseth_sendTransactionby callingidentity::signand broadcasting the signed transaction. The reference host does the opposite:crates/nexum-runtime/src/host/impls/chain.rs:19-25resolves only a read-only method surface and refuses every signing or mutating method (eth_sendTransaction,eth_sign,personal_sign,eth_sendRawTransaction,eth_accounts) with adeniedfault (chain.rs:319-336).identityis an unimplemented stub. The old doc described a working key-management interface backed by Keystore/KMS/HSM.crates/nexum-runtime/src/host/impls/identity.rs:10-28:accounts()returns an empty roster andsign/sign-typed-datareturn theunsupportedfault; a keystore backend is deferred.