feat: new ResidentBytes trait for types which can approximate their resident memory size (stack+heap)

[cylewitruk-stacks]

Description

Introduces a new ResidentBytes trait which is implemented for all types used within Contract/ContractContext and yields either exact or close approximations of their stack [+heap] size ("resident size in bytes"), which is used by #7082 as part of size-informed cache admittance/eviction policy (limiting its in-memory size).

This is a precursor to Clarity contract AST (Contract) caching, where it's important that we are able to restrict the cache's overall actual memory usage. This PR provides the trait and necessary implementations, but does not wire it up.

Includes heuristics for BTreeMap/BTreeSet/HashMap/HashSet, based on current std impls, to conservatively approximate their overhead.

Applicable issues

• Part of #126

Checklist

• Test coverage for new or modified code paths
• Changelog is updated

[Copilot]

Pull request overview

Adds a new ResidentBytes trait (stack + heap “resident size” estimate) and implements it across Clarity contract/context-related types to enable future memory-bounded caching.

Changes:

• Introduces clarity-types::resident_bytes::ResidentBytes with heuristic implementations for common container types and Clarity core types.
• Implements ResidentBytes for key VM structures (Contract, ContractContext, function signatures/callables, token/map/var metadata).
• Adds targeted unit tests validating that resident byte accounting covers all ContractContext fields and grows with richer contracts.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
stacks-common/src/util/macros.rs	Extends guarded_string! types with heap_capacity() to support resident-size estimation.
clarity/src/vm/types/signatures.rs	Implements ResidentBytes for FunctionSignature.
clarity/src/vm/database/structures.rs	Implements ResidentBytes for contract metadata structs (FT/NFT/map/var metadata).
clarity/src/vm/contracts.rs	Implements ResidentBytes for Contract and adds contract-level resident-bytes tests.
clarity/src/vm/contexts.rs	Implements ResidentBytes for ContractContext.
clarity/src/vm/callables.rs	Implements ResidentBytes for DefinedFunction.
clarity-types/src/types/mod.rs	Adds heap_capacity() to FunctionIdentifier for resident-size estimation.
clarity-types/src/resident_bytes.rs	New module defining ResidentBytes, container heuristics, Clarity type impls, and extensive tests.
clarity-types/src/lib.rs	Exports the new resident_bytes module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

Coverage Report for CI Build 25789425370

Coverage increased (+0.02%) to 85.734%

Details

• Coverage increased (+0.02%) from the base build.
• Patch coverage: 11 uncovered changes across 2 files (939 of 950 lines covered, 98.84%).
• 5397 coverage regressions across 96 files.

Uncovered Changes

File	Changed	Covered	%
clarity-types/src/resident_bytes.rs	655	645	98.47%
clarity/src/vm/contracts.rs	174	173	99.43%

Coverage Regressions

5397 previously-covered lines in 96 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
stackslib/src/config/mod.rs	358	69.04%
stackslib/src/chainstate/stacks/index/storage.rs	262	80.55%
stackslib/src/chainstate/stacks/miner.rs	238	83.35%
stackslib/src/net/inv/epoch2x.rs	223	79.38%
stackslib/src/chainstate/stacks/db/transactions.rs	203	97.13%
stackslib/src/net/chat.rs	202	92.95%
stackslib/src/chainstate/stacks/db/mod.rs	196	86.23%
stackslib/src/chainstate/stacks/index/trie_sql.rs	190	69.7%
stackslib/src/core/mempool.rs	170	86.87%
stackslib/src/chainstate/stacks/index/node.rs	160	87.35%

---

Coverage Stats

Relevant Lines:	220615
Covered Lines:	189143
Line Coverage:	85.73%
Coverage Strength:	18998116.27 hits per line

---

💛 - Coveralls

[federico-stacks]

Implementation looks good. I’ve only added a few minor comments with possible improvements.

Also, regarding the Coveralls report: we could improve coverage for structure.rs and signature.rs modules

[federico-stacks]

LGTM!