Skip to content

docs: trim platform generalisation and linker seam to current contract - #600

Merged
mfw78 merged 3 commits into
dev/m1from
docs/598-platform-design
Jul 25, 2026
Merged

docs: trim platform generalisation and linker seam to current contract#600
mfw78 merged 3 commits into
dev/m1from
docs/598-platform-design

Conversation

@mfw78

@mfw78 mfw78 commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

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 against wit/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 current Extension trait. Drop the retired cow-api / shepherd-cow-host / CowBackend example, and describe the trait's real members (namespace, capabilities, link, service, provider, admit predicates, event sources), the HostServices and ExtState reach paths, and the videre venue platform as the live extension the shepherd binary registers.

Why

Both docs were design essays written before the code landed and had drifted from dev/m1: they described the pre-venue-adapter cow-api world extension and an Extension struct 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/ and crates/ at the dev/m1 tip; confirmed no other doc links to the trimmed sections (the #layer-3-domain-extensions-venue-adapters anchor 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:

  • chain does not delegate signing to identity. The old doc claimed chain::request handles eth_sendTransaction by calling identity::sign and broadcasting the signed transaction. The reference host does the opposite: crates/nexum-runtime/src/host/impls/chain.rs:19-25 resolves only a read-only method surface and refuses every signing or mutating method (eth_sendTransaction, eth_sign, personal_sign, eth_sendRawTransaction, eth_accounts) with a denied fault (chain.rs:319-336).
  • identity is 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 and sign / sign-typed-data return the unsupported fault; a keystore backend is deferred.

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
mfw78 force-pushed the docs/598-platform-design branch from 56ed3a0 to 7b19512 Compare July 25, 2026 03:13
mfw78 added 2 commits July 25, 2026 03:30
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.
@mfw78
mfw78 merged commit dd3f69d into dev/m1 Jul 25, 2026
7 checks passed
@mfw78
mfw78 deleted the docs/598-platform-design branch July 25, 2026 06:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant