refactor: agent-discoverable naming, docs, and file splits

.agents/skills/write-discoverable-code/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: write-discoverable-code
+description: Write Rust/Substrate code so grep-first coding agents can find, parse, and trust it — distinctive names, precise types, definition-site docs, concept-named files. Use when adding or refactoring code in subtensor, or when running a discoverability migration shard.
+---
+
+# Write discoverable code (subtensor)
+
+Coding agents navigate this repo with `rg` / filename search, not a dependency graph. Names and paths are the reverse index. Types and compiler errors are the feedback loop agents cannot skip.
+
+## Naming
+
+1. **Exported / crate-visible symbols: 2–3 words, one domain word.** Prefer `calculate_subnet_emission` over `calculate`. Package/module path counts as a word only when call sites use the qualified path in source (`swap::NewClient`-style); FRAME dispatchables and free functions need the domain word in the identifier itself.
+2. **One spelling per concept.** Follow the glossary in root `AGENTS.md`. Do not introduce `organization` beside `org`, or `network_id` beside `NetUid`.
+3. **Spell out common abbreviations in new helpers.** Prefer `subnet` over `sn`, `rate_limit` over `rl`, and full domain words over opaque stubs (`Custom`, `I`, `Impl` as the only distinguisher). Boolean helpers should read as predicates (`subnet_exists`, `should_accumulate_…`), not `if_*`. Extrinsic-body helpers should not share a `do_*` prefix with the dispatchable — use `perform_*` / a concept verb.
+4. **Files and modules are search terms.** Name files after the concept they own (`smtp_settings.py` → here: `folder_fallbacks.rs`, `hmac_payload_signer.rs`). Prefer `email/message_rendering.rs` over a 5k-line grab-bag. Precompile `INDEX` / Solidity selectors are path-agnostic in the metadata fingerprint, so `foo.rs` → `foo/mod.rs` splits are safe when those values stay put.
+5. **Tests named after source.** `staking/add_stake.rs` → tests that cover it live under a discoverable name (`tests/add_stake.rs` or a module clearly about add-stake). Avoid dumping unrelated cases into one monolith when splitting is cheap.
+6. **Mark legacy `@deprecated` / `#[deprecated]`** when keeping a path temporarily. Prefer deletion.
+
+### Do not rename (Tier A–D)
+
+| Tier | Surface | Why |
+|------|---------|-----|
+| **A** | Storage item **type names**; `construct_runtime!` pallet names and indices | Twox128 storage keys / module prefix |
+| **B** | `call_index` numbers; Event/Error **variant order**; SCALE field **order**; `freeze_struct` layouts | Wire / codec compatibility |
+| **C** | Extrinsic **fn names**; Event/Error **names**; RPC `#[method(name = "…")]` strings; runtime API trait/method names; precompile `INDEX` + Solidity `public("…")` selectors | Clients, SDKs, EVM, explorers |
+| **D** | `WeightInfo` method names (must match calls); applied migration **name strings**; hardcoded `"SubtensorModule"` / pallet prefix strings | Benchmarks, migration idempotency, EVM storage query |
+
+**Never edit** generated [`pallets/subtensor/src/weights.rs`](../../../pallets/subtensor/src/weights.rs).
+
+**Generally safe:** private helpers, `pub(crate)` types not in storage/RPC/metadata, module paths under a pallet, file splits, test helpers, doc comments (see freeze_struct rule).
+
+If a rename would touch files outside your shard, append a line to `refactor/rename-proposals.md` instead of doing it.
+
+## Types
+
+- Annotate inputs/outputs; avoid `any`-equivalent opacity (`impl Trait` only when the trait name is itself a good search term).
+- Prefer newtypes / distinct ID types (`NetUid`, account kinds) over raw `u16`/`AccountId` soup at API boundaries so the compiler catches swaps.
+- Type names obey the same uniqueness rule as function names (`SubnetEmissionResult`, not `Result` aliases that collide).
+
+## Comments
+
+- **One sentence on the definition** — storage item, dispatchable, important helper — saying what the code cannot say (invariants, units, “deliberately does not sanitize”, migration constraints).
+- Agents land on definitions via search; definition-site docs are the highest-leverage docs.
+- Do not restate the signature. Do not invent behavior that is not true.
+
+### freeze_struct caveat
+
+`#[freeze_struct]` blanks doc text before hashing but keeps doc attributes. **Adding or removing** docs on a frozen struct/field requires updating the hash; **editing existing** doc text does not. Only update the hash when the non-doc token stream is unchanged.
+
+## File structure
+
+- Target **≤ ~1000 lines** per file for new splits; existing giants should be split by concept when touched.
+- Split pattern: `foo.rs` → `foo/mod.rs` + `foo/<concept>.rs`. Update `mod` declarations in the owning tree only.
+- Do not create barrel `export *` equivalents that erase names without need; keep re-exports explicit when agents must follow them.
+
+## Deliberate absences
+
+If the codebase intentionally does not do something readers will search for (e.g. “HTML email is not sanitized”), document that at the definition or module the search will hit. Grep cannot prove absence.
+
+## Exit checklist (shard agents)
+
+```bash
+cargo fmt --all
+cargo clippy -p <owned-crates> --all-targets -- --deny warnings
+SKIP_WASM_BUILD=1 cargo nextest run -p <owned-crates>
+./scripts/check_metadata_unchanged.sh
+```
+
+Metadata fingerprint must match `refactor/metadata-baseline.txt`. If it fails, you changed a frozen surface — revert that part.

AGENTS.md

@@ -0,0 +1,78 @@
+# Agent guide — subtensor
+
+This repository is a Bittensor Substrate node (Rust / FRAME). Agents navigate primarily by text search (`rg`). Write code so names, paths, and definition-site docs are good search terms.
+
+For the full discoverability conventions, load [`.agents/skills/write-discoverable-code/SKILL.md`](.agents/skills/write-discoverable-code/SKILL.md).
+
+## Repo map (search anchors)
+
+| Path | Role |
+|------|------|
+| `pallets/subtensor/` | Core: staking, subnets, emissions, epoch/consensus, registration |
+| `pallets/swap/` | TAO↔alpha AMM / liquidity |
+| `pallets/admin-utils/` | Sudo/admin hyperparameters and toggles |
+| `pallets/limit-orders/` | Signed limit / take-profit / stop-loss orders |
+| `pallets/{commitments,crowdloan,drand,shield,proxy,utility,transaction-fee,alpha-assets}/` | Supporting pallets |
+| `runtime/` | `construct_runtime!`, migrations tuple, `spec_version`, runtime APIs |
+| `node/` | Binary, RPC wiring, chain specs |
+| `precompiles/` | EVM precompiles (addresses + Solidity selectors are frozen) |
+| `common/`, `primitives/`, `support/` | Shared types, math, lints, macros |
+| `sdk/` | Client core + language bindings (metadata-driven) |
+
+Canonical layout doc: [`docs/internals/repo-layout.mdx`](docs/internals/repo-layout.mdx).
+
+## Glossary (one spelling per concept)
+
+| Prefer | Avoid |
+|--------|--------|
+| `netuid` / `NetUid` | `net_uid`, `network_id`, `subnet_id` (for the same type) |
+| `hotkey` / `coldkey` | `hot_key`, `cold_key` |
+| `tao` / `alpha` | inventing synonyms for the same asset |
+| `stake` | mixing `bond` / `delegation` for the same storage amount |
+| `subnet` | `network` when you mean a Bittensor subnet (except historical names); never abbreviate as `sn` in new helpers (`ensure_sn_owner` → `ensure_subnet_owner`) |
+| `uid` | `neuron_index` for the per-subnet uid |
+| `tempo` | `epoch_length` for the subnet tempo parameter |
+| `emission` | `reward_mint` for coinbase emission |
+| `rate_limit` / `rate_limits` | `rl` in identifiers (`record_owner_rl` → `record_owner_rate_limits`) |
+| `*_exists` / `should_*` predicates | `if_*` boolean helpers (`if_subnet_exist` → `subnet_exists`) |
+| `perform_*` / concept verb for extrinsic bodies | bare `do_*` next to a same-named dispatchable (`do_swap_hotkey` → `perform_hotkey_swap`) |
+| domain word in RPC/handler types | opaque `Custom` alone (`SubtensorCustom` → `SubtensorCustomRpc`) |
+
+When a frozen on-chain name already uses a different spelling, keep the frozen name; do not invent a parallel alias.
+
+## Frozen surface (do not rename)
+
+See the Tier A–D table in the write-discoverable-code skill. Short form:
+
+- **Never rename:** storage item type names, `construct_runtime!` pallet names/indices, `call_index` numbers, Event/Error **variant order**, SCALE field order, RPC method strings, runtime API trait/method names, precompile addresses / Solidity selectors, applied migration name strings, `"SubtensorModule"` hardcodes, `WeightInfo` method names.
+- **Do not edit:** [`pallets/subtensor/src/weights.rs`](pallets/subtensor/src/weights.rs) (generated).
+- **Safe:** private/crate helpers, internal types not in storage/RPC, file splits (`foo.rs` → `foo/mod.rs`), test layout, doc comments (with `freeze_struct` caveat below).
+
+Safety oracle: `scripts/check_metadata_unchanged.sh` (docs-stripped structural fingerprint must match `refactor/metadata-baseline.txt`).
+
+## freeze_struct and docs
+
+`#[freeze_struct("…")]` hashes the struct after blanking doc *text*, but **keeps** doc attributes. Therefore:
+
+- Changing the text of an existing `///` comment: safe, no hash update.
+- Adding or removing a doc comment on a frozen struct/field: changes the hash — update the hash **only** when the non-doc token stream is unchanged.
+
+## Swarm / shard rules
+
+During the discoverability migration (`refactor/discoverability`):
+
+1. Own only the files listed in your shard in [`refactor/refactor-manifest.json`](refactor/refactor-manifest.json).
+2. Rename a symbol only if `rg -w OldName` (repo-wide, excl. `target/`/`vendor/`) hits exclusively inside your owned files. Otherwise append to [`refactor/rename-proposals.md`](refactor/rename-proposals.md).
+3. File splits must use `foo.rs` → `foo/mod.rs` (+ siblings) so other shards never need to edit your parent.
+4. Before finishing: `cargo fmt`, clippy `-D warnings` on owned crates, tests on owned crates, and `scripts/check_metadata_unchanged.sh`.
+
+## Local checks
+
+```bash
+just fmt
+just clippy
+SKIP_WASM_BUILD=1 cargo nextest run -p <crate>
+./scripts/check_metadata_unchanged.sh
+```
+
+Runtime PRs normally bump `spec_version`; pure discoverability work that leaves metadata (minus docs) identical should use the `no-spec-version-bump` label and say so in the PR.

chain-extensions/src/contracts_env.rs

@@ -0,0 +1,93 @@
+//! Contracts VM adapter: bridges `pallet-contracts` [`Environment`] to [`SubtensorExtensionEnv`].
+
+use codec::{Decode, MaxEncodedLen};
+use frame_system::RawOrigin;
+use pallet_contracts::chain_extension::{BufInBufOutState, Environment, Ext, InitState};
+use sp_runtime::{DispatchError, Weight};
+use sp_std::marker::PhantomData;
+
+/// Environment surface used by [`crate::SubtensorChainExtension`] dispatch helpers.
+///
+/// Production code uses [`ContractsEnvAdapter`]; unit tests supply an in-memory mock.
+pub(crate) trait SubtensorExtensionEnv<T>
+where
+    T: pallet_contracts::Config,
+{
+    fn func_id(&self) -> u16;
+    fn charge_weight(&mut self, weight: Weight) -> Result<(), DispatchError>;
+    fn read_as<U: Decode + MaxEncodedLen>(&mut self) -> Result<U, DispatchError>;
+    fn write_output(&mut self, data: &[u8]) -> Result<(), DispatchError>;
+    /// Contract address (`ext.address()`), used by non-`Caller*` function ids as the signed origin.
+    fn caller(&mut self) -> T::AccountId;
+    /// Transaction origin (`ext.caller()`), used by `Caller*` function ids.
+    #[allow(dead_code)]
+    fn origin(&mut self) -> pallet_contracts::Origin<T>;
+}
+
+/// Map a `pallet-contracts` origin into a FRAME [`RawOrigin`] for pallet dispatch.
+pub(crate) fn contracts_origin_as_raw<T>(
+    origin: pallet_contracts::Origin<T>,
+) -> RawOrigin<T::AccountId>
+where
+    T: pallet_contracts::Config,
+{
+    match origin {
+        pallet_contracts::Origin::Signed(caller) => RawOrigin::Signed(caller),
+        pallet_contracts::Origin::Root => RawOrigin::Root,
+    }
+}
+
+/// Buf-in/buf-out wrapper around the contracts chain-extension [`Environment`].
+pub(crate) struct ContractsEnvAdapter<'a, 'b, T, E>
+where
+    T: pallet_subtensor::Config + pallet_contracts::Config,
+    E: Ext<T = T>,
+{
+    env: Environment<'a, 'b, E, BufInBufOutState>,
+    _marker: PhantomData<T>,
+}
+
+impl<'a, 'b, T, E> ContractsEnvAdapter<'a, 'b, T, E>
+where
+    T: pallet_subtensor::Config + pallet_contracts::Config,
+    T::AccountId: Clone,
+    E: Ext<T = T>,
+{
+    pub(crate) fn new(env: Environment<'a, 'b, E, InitState>) -> Self {
+        Self {
+            env: env.buf_in_buf_out(),
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl<'a, 'b, T, E> SubtensorExtensionEnv<T> for ContractsEnvAdapter<'a, 'b, T, E>
+where
+    T: pallet_subtensor::Config + pallet_contracts::Config,
+    T::AccountId: Clone,
+    E: Ext<T = T>,
+{
+    fn func_id(&self) -> u16 {
+        self.env.func_id()
+    }
+
+    fn charge_weight(&mut self, weight: Weight) -> Result<(), DispatchError> {
+        self.env.charge_weight(weight).map(|_| ())
+    }
+
+    fn read_as<U: Decode + MaxEncodedLen>(&mut self) -> Result<U, DispatchError> {
+        self.env.read_as()
+    }
+
+    fn write_output(&mut self, data: &[u8]) -> Result<(), DispatchError> {
+        self.env.write(data, false, None)
+    }
+
+    fn caller(&mut self) -> T::AccountId {
+        self.env.ext().address().clone()
+    }
+
+    fn origin(&mut self) -> pallet_contracts::Origin<T> {
+        self.env.ext().caller()
+    }
+}