module-api-architecture

Module & API Architecture

Focus: package boundaries, public surface and deprecation lifecycle, type/import discipline, NodeNext compatibility. The authoritative rules live in AGENTS.md §1 (Architecture), §2 (Forbidden patterns — rule 5: deep cross-package imports), §3 (Type discipline), §4 (Public API & packaging), and §7 (Releases & versioning) — read those first; the bullets below are the application points.

What to flag

Per AGENTS.md §1, §2 (rule 5), and §4 — package boundaries, forbidden deep imports, and the public surface:

• A new deep import across packages — e.g. from "@morpho-org/foo/src/internal/..." instead of going through @morpho-org/foo's src/index.ts. The receiving package's src/index.ts is the only public entry point.
• A new export from src/index.ts (or removal/rename of an existing one) — flag for cross-file impact on consumers; check that downstream code in the monorepo and the JSDoc still match.
• A consumer-facing export added or changed in blue-sdk, blue-sdk-viem, or midnight-sdk without a same-PR audit of the matching morpho-sdk facade subpath. Flag drift between an established raw /blue/<category> or /midnight/<category> surface and its unprefixed facade, protocol-specific unprefixed names without Blue/Midnight qualification, qualified names for genuinely shared symbols, legacy ambiguous names removed without deprecation, and facade expansion into a new upstream surface solely for parity.
• A layering reversal — entity reading state when it should be lazy, action encoding calldata that should belong to a helper, helper depending on an entity, etc. (See the §1 Layering table.)
• A public *Utils factory whose main job is returning a public class instance. Prefer a static method on the class (Offer.create, Group.create, Tree.create) and keep the *Utils namespace for pure object-compatible implementation.
• A class-specific getter or method that reimplements domain logic instead of delegating to a pure *Utils function that accepts readonly plain objects compatible with the class shape.
• A local, non-exported helper introduced with fewer than three call sites. Inline one-off and two-use helpers.
• Duplicate public TypeScript shapes for the same concept. If a domain interface and ABI struct are identical, expect one exported interface reused by both paths; a separate *Struct type needs a real shape difference.
• A new framework import (react, wagmi, redux, ethers) in a core SDK package. Framework adapters live in explicitly named packages (*-wagmi, *-viem); core packages stay framework-free.
• Internal workspace dependencies that do not use workspace: ranges, except peerDependencies: internal peers intentionally use explicit published semver ranges so Changesets does not auto-bump peer dependents. When a package is bumped, check all packages that declare it as a peer dependency; flag missing peer range updates or missing explicit dependent changesets.