docs: reconcile module.toml schema docs with the actual parser#349
Merged
Conversation
Closes #63. Three manifest features these docs described don't exist in crates/nexum-runtime/src/manifest/types.rs - verified against the current Manifest/CapabilitiesSection structs before editing: - `[chains].required`/`.optional` - no `chains` field on Manifest; chain ids are declared per-`[[subscription]]` instead. - `topics = [...]` on a chain-log subscription - the real field is `event_signature: Option<String>`, a single optional string. - `[capabilities.identity].methods` - CapabilitiesSection has only required/optional/http; no identity sub-config exists. Fixed in both docs/02-modules-events-packaging.md (the primary manifest reference) and docs/migration/0.1-to-0.2.md, which repeated the same three fictions (plus a `denied = []` capabilities field, also not on CapabilitiesSection) in the same code blocks. Added a short note explaining why [module.resources] and [chains] silently dropped out of the migration diff example, since removing lines from a "what changed" diff without comment reads as an oversight. Not fixed here: docs/migration/0.1-to-0.2.md separately claims the 0.2 manifest filename is nexum.toml throughout (8 occurrences) - the opposite of ADR-0001's actual rename to module.toml. That's a bigger, differently-scoped fix; filed as #339 rather than folded in here.
- "the module fails to load" named the wrong lifecycle stage: traced the actual boot sequence (crates/nexum-runtime/src/builder.rs) and an unconfigured chain fails when subscriptions open (open_block_streams/open_chain_log_streams), which runs strictly after Supervisor::boot (Load+Init), not during Load. Reworded to "the engine bails at boot, before any events dispatch" - accurate without naming a specific state-machine stage. - "Two 0.1 fields dropped..." asserted these were real fields in 0.1 without verification; grepped docs/01-runtime-environment.md and found zero occurrences of either. Reworded to state only what's verified: they're not part of 0.2's schema, no claim about 0.1.
mfw78
added
the
base: develop
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
2 participants
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
Closes #63 — three manifest features these docs described don't exist in
crates/nexum-runtime/src/manifest/types.rs. Verified against the currentManifest/CapabilitiesSectionstructs before editing, not just against the issue's prose:[chains].required/.optional— nochainsfield onManifest; chain ids are declared per-[[subscription]]instead (Block { chain_id },ChainLog { chain_id, .. }).topics = [...]on a chain-log subscription — the real field isevent_signature: Option<String>, a single optional string, not an array.[capabilities.identity].methods—CapabilitiesSectionhas onlyrequired/optional/http; no identity sub-config exists.Where
Both
docs/02-modules-events-packaging.md(the primary manifest reference — the file the issue is really about) anddocs/migration/0.1-to-0.2.md, which repeats the same three fictions in its own example code blocks. While already editing that migration-guide block I found one more sibling fiction in the identical[capabilities]example — adenied = []field, also absent fromCapabilitiesSection— and removed it too. Added a short explanatory sentence for why[module.resources]and[chains]silently drop out of the "what changed" diff example, since deleting lines from a migration diff with no comment reads as an oversight rather than a deliberate correction.Deliberately not fixed here
docs/migration/0.1-to-0.2.mdseparately claims throughout (8 occurrences, including its own top-of-file TL;DR table) that the 0.2 manifest filename isnexum.toml— the opposite of what ADR-0001 actually did (renamed it tomodule.toml, which is what the code and every shipped module use). That's a bigger, differently-shaped fix than #63 asked for, so I filed it separately as #339 rather than folding an 8-occurrence whole-file rename into this PR.Testing
Docs-only change; no build/test impact. Verified every removed/changed field against the current parser source before editing.