Implement a runtime capability registry for optional GuildPass SDK features

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): compatibility, type-safety, backend, advanced

Background

GuildPass SDK V2 is intentionally being rebuilt incrementally. Different backend deployments or future contract versions may expose different capabilities.

The SDK needs a safe way to represent and query supported capabilities without scattering string comparisons throughout client code.

This issue introduces a standalone runtime capability registry.

Problem

There is currently no canonical representation for SDK capabilities such as membership.read, access.check, or future Stellar-related functionality.

Free-form strings can produce typos, ambiguous feature detection, and inconsistent compatibility behaviour.

Expected Outcome

Implement a typed capability registry that validates capability identifiers, tracks supported versions, and provides deterministic capability checks.

Suggested Implementation

A capability may resemble:

interface CapabilityDefinition {
  id: string;
  version: string;
}

The registry should:

• validate capability identifier syntax;
• reject duplicate capability registrations with conflicting versions;
• expose hasCapability(id);
• expose getCapabilityVersion(id);
• optionally expose version-aware checks such as minimum supported version;
• preserve deterministic capability ordering when listing entries;
• support immutable snapshot creation;
• avoid mutating caller-provided input;
• provide structured errors for malformed or conflicting definitions;
• remain independent of remote discovery or API calls.

If semantic version comparison is implemented, it must be self-contained within this issue rather than depending on another campaign contribution.

Acceptance Criteria

• Valid capability identifiers can be registered.
• Invalid identifiers are rejected.
• Duplicate identical definitions behave according to a documented policy.
• Conflicting duplicate definitions are rejected.
• Capability lookup is deterministic.
• Capability listing has stable ordering.
• Caller input mutation cannot mutate stored registry state.
• Optional version checks are tested if included.
• Unit tests cover valid, duplicate, malformed, ordering, and immutability scenarios.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No API discovery request or server capability endpoint is implemented.

Likely Affected Files/Directories

src/capabilities/ or equivalent focused module
src/types/
tests/

Independence Requirement

This issue must be independently implementable from the current SDK baseline and must not depend on transport, API, or server changes.

[Emmzyemms]

I’m interested in contributing to this issue and believe I can deliver a clean, well-tested solution that aligns with the project’s standards.

[Brainoncrack]

I’m interested in contributing to this issue and believe I can deliver a clean, well-tested solution that aligns with the project’s standards.

[grantfox-oss]

🦊 GrantFox — @Brainoncrack has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #455)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Brainoncrack's PR #485 was approved and merged by @Lakes41.

🏆 @Brainoncrack: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (554 total points). Track your full progress on GrantFox.

👏 Great work, @Brainoncrack! Keep contributing to Adamantine-guild.