docs: deprecate init_module, document explicit initialize pattern

[gregnazario]

Summary

Deprecates the Move init_module function across the docs and steers readers to a guarded public entry fun initialize pattern. init_module is being removed because it causes issues in the VM.

Changes

• Canonical reference (modules-on-aptos.mdx EN+ZH): deprecation banner + a new "Recommended: explicit initialize entry function" section documenting the replacement with both guards (publisher-address authorization assert + !exists<> once-guard) and the separate-transaction operational caveat.
• Solidity→Move comparison guides (billboard module-initialization.mdx, dutch-auction initialization.mdx, both EN+ZH): init_module fully scrubbed and replaced with initialize; frontmatter descriptions and prose updated. The dutch-auction sample uses the guide's existing error::permission_denied(ENOT_OWNER) convention.
• Tutorials (first-coin.mdx, first-fungible-asset.mdx, EN only): deprecation callouts added. Their init_module code samples are intentionally kept because they mirror runnable examples in aptos-labs/aptos-core (moon_coin.move, fa_coin.move) — see follow-ups.

Replacement pattern

public entry fun initialize(publisher: &signer) {
    assert!(signer::address_of(publisher) == @my_addr, error::permission_denied(ENOT_AUTHORIZED));
    assert!(!exists<ModuleData>(@my_addr), error::already_exists(EALREADY_INITIALIZED));
    move_to(publisher, ModuleData { /* ... */ });
}

The two guards recover the once-only and publisher-only guarantees that init_module provided automatically.

Verification

• pnpm lint clean; pnpm check 0 errors / 0 warnings (2 pre-existing unrelated hints)
• pnpm test tests/agent-discovery.test.ts tests/markdown-negotiation.test.ts → 42/42 pass
• Pre-push hook: astro check, full build, and link validation all green
• Audit: init_module now appears only in the reference (as legacy/deprecated) and the two tutorials (samples + callouts); both ethereum-to-aptos guides are fully scrubbed

Follow-ups (out of scope, noted in the plan)

• aptos-core companion PR: once moon_coin.move / fa_coin.move migrate to initialize, swap the tutorial samples and drop the "will be updated once that example is migrated" line from both callouts.
• Reference link: add an AIP/reference link to the deprecation callouts once one is public.

Note

This branch also contains the design spec and implementation plan under docs/superpowers/ (commits e0c4253, 9c3f55d). If you don't want those planning artifacts in the repo, I can drop those two commits before merge.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aptos-docs	Ready	Preview, Comment	Jul 13, 2026 7:40pm

[georgemitenkov]

nit: I would say, "In move, initialization is an explicit action invoked by developer, giving them more control. An explicit public entry fun initialize needs to be called..."

basically adding some motivation that explicit init is not too bad: it gives you control on the order of initialization, and aligns with decoupled code-data paradigm in Move.

[GotenJBZ]

Nit2:
No need for public, let's use entry fun initialize

[georgemitenkov]

Also it has no ordering semantics which inits run first? "Adds complexity for the VM"?

[georgemitenkov]

Same as for src/content/docs/build/guides/first-coin.mdx

[georgemitenkov]

Can we list more reasons here:

• No clear linking semantics (old or new code?)
• No initialization order
• Adds significant complexity to the VM