feat(kernel-utils): add sheaf programming module

[grypez]

Introduce operational presheaf + sheafify for guard-based dispatch:

• Section/guard types, presheaf construction, stalk filtering
• Late decider (lift) selects winner when multiple sections match
• Modular sheaf/ directory with single-concern files and e2e tests

---

Note

Medium Risk
Adds a brand-new authority-management/routing library (sheafify) that controls which capability handler is invoked at runtime based on guards and policy, so correctness issues could affect dispatch behavior. Risk is mitigated by being a new, isolated package with extensive unit/e2e coverage.

Overview
Introduces a new publishable package, @metamask/sheaves, providing guard-based capability dispatch via sheafify({ name, providers, compartment? }), including metadata evaluation (constant/callable/source), candidate collapsing by metadata equivalence, constraint/option decomposition, and a policy-driven retry loop with accumulated error history.

Adds policy composition utilities (noopPolicy, withFilter, withRanking, fallthrough, proxyPolicy), remote-provider wrapping (makeRemoteSection), guard union/asyncification utilities, and comprehensive unit/e2e tests plus documentation and package/build wiring (tsconfig references, vitest config, typedoc, yarn workspace entry, licenses/changelog/README).

^{Reviewed by Cursor Bugbot for commit cc25c7f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	71.96% ⬆️ +0.53%	8503 / 11816
🔵	Statements	71.79% ⬆️ +0.53%	8644 / 12040
🔵	Functions	72.83% ⬆️ +0.58%	2054 / 2820
🔵	Branches	65.58% ⬆️ +0.49%	3434 / 5236

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/sheaves/src/compose.ts	94.44%	100%	90.9%	94.44%	16
packages/sheaves/src/guard.ts	98.59%	96.15%	100%	98.52%	109
packages/sheaves/src/index.ts	100%	100%	100%	100%
packages/sheaves/src/metadata.ts	100%	100%	100%	100%
packages/sheaves/src/remote.ts	100%	100%	100%	100%
packages/sheaves/src/section.ts	100%	100%	100%	100%
packages/sheaves/src/sheafify.ts	93.69%	82.92%	100%	93.63%	39, 42, 52, 120, 163, 247, 277-282
packages/sheaves/src/stalk.ts	88.23%	86.66%	100%	88.23%	31, 69
packages/sheaves/src/types.ts	100%	100%	100%	100%

Generated in workflow #4409 for commit cc25c7f by the Vitest Coverage Report Action

[rekmarks]

I think this is a promising direction for composing object capabilities that we should continue to experiment with. Some notes:

• The terminology is abstruse for the algebraic topologically challenged. I propose an alternative here
• Sheaves should be in their own package @metamask/sheaves. We'll have to cut a release once this is merged.

[grypez]

I think this is a promising direction for composing object capabilities that we should continue to experiment with. Some notes:

• The terminology is abstruse for the algebraic topologically challenged. I propose an alternative here
• Sheaves should be in their own package @metamask/sheaves. We'll have to cut a release once this is merged.

Suggestions applied, except any renaming suggestion that included 'tags' in the new name.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit cc25c7f. Configure here.}

[cursor]

Prototype chain causes incorrect metadata stripping in decompose

Medium Severity

The decomposeMetadata function uses key in constraints to decide which metadata keys to keep on stripped candidates. Because constraints is a plain {} inheriting from Object.prototype, any metadata key matching a prototype property name (e.g., constructor, toString, valueOf, hasOwnProperty) will be incorrectly treated as a constraint and silently dropped from all candidates — even when it was never added to constraints and carries distinguishing values. The policy then receives candidates missing that metadata, leading to incorrect dispatch decisions. Using Object.hasOwn(constraints, key) instead of key in constraints would fix this.

 

^{Reviewed by Cursor Bugbot for commit cc25c7f. Configure here.}