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
Mostly additive new package, but it introduces new dispatch/routing logic (guard matching, metadata evaluation, policy-driven retries) that will affect callers adopting it and could surface subtle runtime edge cases.

Overview
Adds a new @metamask/sheaves package that implements guard-based capability routing via sheafify, producing dispatch sections that select among matching providers using evaluated metadata and a caller-supplied async-generator Policy (including retry with accumulated errors and constraint/option metadata decomposition).

Includes helpers for metadata specs (constant/callable/source with optional compartment compilation), policy composition utilities (noopPolicy, withFilter, withRanking, fallthrough, proxyPolicy), remote-provider wrapping via makeRemoteSection, plus extensive unit/e2e tests and documentation. Wires the package into the monorepo build/test setup (new tsconfig refs, vitest config, lockfile entry) and adds standard package metadata/licensing/changelog.

^{Reviewed by Cursor Bugbot for commit ba12dbe. 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 #4410 for commit ba12dbe 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.}