refactor(kernel-utils): move sheaf exports to ./sheaf subpath

Sheaf is a large, self-contained subsystem. Keeping it under its own
subpath import reduces coupling on consumers who don't need it, and
keeps the main index focused on general utilities.

- Add @metamask/kernel-utils/sheaf entry point (src/sheaf/index.ts)
- Remove sheaf re-exports from the main index
- Add ./sheaf export to package.json alongside the other subpaths
- Remove sheaf overview from README (belongs in sheaf/README.md)
- Update CHANGELOG: use subpath import, drop internal exports
  (collectSheafGuard, getStalk, guardCoversPoint), add makeSection and
  noopLift, fix MetadataSpec capitalisation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

packages/kernel-utils/CHANGELOG.md

@@ -9,14 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Add sheaf programming module ([#870](https://github.com/MetaMask/ocap-kernel/pull/870))
+- Add `@metamask/kernel-utils/sheaf` subpath export ([#870](https://github.com/MetaMask/ocap-kernel/pull/870))
   - `sheafify()` for building a `Sheaf` capability authority from a collection of `PresheafSection`s, each an exo with optional invocation-dependent metadata
   - `constant()`, `source()`, `callable()` for constructing metadata specs (static value, compartment-evaluated code string, and per-call function respectively)
-  - `proxyLift()`, `withFilter()`, `withRanking()`, `fallthrough()` for composing lifts to route and rank sections at dispatch time
-  - `collectSheafGuard()` for deriving a combined `InterfaceGuard` from all sections in a sheaf
-  - `getStalk()`, `guardCoversPoint()` for section lookup and guard checks
+  - `noopLift()`, `proxyLift()`, `withFilter()`, `withRanking()`, `fallthrough()` for composing lifts to route and rank sections at dispatch time
+  - `makeSection()` for constructing a typed exo section from a guard and handler map
   - `makeRemoteSection()` for wrapping a remote CapTP reference as a `PresheafSection`, fetching its interface guard once at construction and forwarding method calls via `E()`
-  - Types: `Sheaf<M>`, `Section<Core>`, `PresheafSection<M>`, `EvaluatedSection<M>`, `MetaDataSpec<M>`, `Lift<M>`, `LiftContext`, `Presheaf`
+  - Types: `Sheaf<M>`, `Section`, `PresheafSection<M>`, `EvaluatedSection<M>`, `MetadataSpec<M>`, `Lift<M>`, `LiftContext<M>`
 
 ## [0.5.0]
 

packages/kernel-utils/README.md

@@ -26,110 +26,6 @@ or
 npm install --save-dev patch-package
 ```
 
-## Sheaf Module
-
-The sheaf module provides a dispatch abstraction for routing method calls across multiple capability objects (_sections_) that each cover a region of a shared interface.
-
-### Overview
-
-```
-sheafify({ name, sections, compartment? }) → Sheaf
-sheaf.getGlobalSection({ lift }) → section proxy
-sheaf.getSection({ guard, lift }) → section proxy
-```
-
-Each call on the proxy is dispatched to whichever section covers that method. When multiple sections are eligible, a **lift** selects among them. A lift is an `AsyncGenerator` coroutine that yields candidates one at a time and receives the accumulated error history on each resume — enabling retry, fallback, and cost-aware routing without callers needing to know the selection strategy.
-
-### Defining sections
-
-```ts
-import { sheafify, constant, callable } from '@metamask/kernel-utils';
-
-const sheaf = sheafify({
-  name: 'Wallet',
-  sections: [
-    {
-      exo: walletA,
-      metadata: constant({ cost: 10, push: false }),
-    },
-    {
-      exo: walletB,
-      // callable metadata is evaluated per-call with the actual arguments
-      metadata: callable((args) => ({ cost: 1 + 0.1 * (args[0] as number) })),
-    },
-    {
-      exo: walletC,
-      // source metadata is compiled once at sheafify time via the compartment
-      metadata: source(`(args) => ({ cost: 5 + 0.01 * args[0] })`),
-    },
-  ],
-  compartment, // required only when using source-kind metadata
-});
-```
-
-**Metadata kinds:**
-| Kind | When evaluated | Use case |
-|------|---------------|----------|
-| `constant(v)` | Never (static) | Fixed priority or capability flags |
-| `callable(fn)` | Each call | Arg-dependent cost, remaining spend |
-| `source(str)` | Each call (compiled at construction) | Sandboxed cost functions |
-
-### Writing a lift
-
-A lift receives `EvaluatedSection<Partial<M>>[]` (germs) and a context, and yields candidates in preference order. It receives a snapshot of all accumulated errors on each `gen.next(errors)` call.
-
-```ts
-import type { Lift } from '@metamask/kernel-utils';
-
-// Yield cheapest section first; fall back in cost order on failure
-const cheapest: Lift<{ cost: number }> = async function* (germs) {
-  yield* [...germs].sort(
-    (a, b) => (a.metadata?.cost ?? Infinity) - (b.metadata?.cost ?? Infinity),
-  );
-};
-
-const section = sheaf.getGlobalSection({ lift: cheapest });
-```
-
-### Composing lifts
-
-```ts
-import {
-  withFilter,
-  withRanking,
-  fallthrough,
-  proxyLift,
-} from '@metamask/kernel-utils';
-
-// Filter out sections with insufficient remaining spend
-const spendable = withFilter<Cost>(
-  (germ, { args }) =>
-    (germ.metadata?.remainingSpend ?? Infinity) >= (args[0] as number),
-);
-
-// Sort by cost before passing to the inner lift
-const byCost = withRanking<Cost>(
-  (a, b) => (a.metadata?.cost ?? Infinity) - (b.metadata?.cost ?? Infinity),
-);
-
-// Try local sections first, fall through to remote on exhaustion
-const withFallback = fallthrough(localLift, remoteLift);
-
-// Compose: filter → rank → select
-const lift = spendable(byCost(cheapest));
-```
-
-`withFilter` and `withRanking` are pure input transforms that return the inner lift's generator directly. `fallthrough` sequences two lifts via `yield*`, which forwards the error array to each inner lift. `proxyLift` is the primitive for adding logic (logging, circuit-breaking) between yields.
-
-### Error handling
-
-When all candidates are exhausted, `driveLift` throws:
-
-```
-Error: No viable section for <method>
-  cause: [Error: ..., Error: ..., ...]   // all accumulated attempt errors
-```
-
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/kernel-utils/package.json

@@ -79,6 +79,16 @@
         "default": "./dist/nodejs/index.cjs"
       }
     },
+    "./sheaf": {
+      "import": {
+        "types": "./dist/sheaf/index.d.mts",
+        "default": "./dist/sheaf/index.mjs"
+      },
+      "require": {
+        "types": "./dist/sheaf/index.d.cts",
+        "default": "./dist/sheaf/index.cjs"
+      }
+    },
     "./vite-plugins": {
       "import": {
         "types": "./dist/vite-plugins/index.d.mts",

packages/kernel-utils/src/index.test.ts

@@ -13,10 +13,7 @@ describe('index', () => {
       'GET_DESCRIPTION',
       'abortableDelay',
       'calculateReconnectionBackoff',
-      'callable',
-      'constant',
       'delay',
-      'fallthrough',
       'fetchValidatedJson',
       'fromHex',
       'ifDefined',
@@ -33,22 +30,14 @@ describe('index', () => {
       'makeDefaultExo',
       'makeDefaultInterface',
       'makeDiscoverableExo',
-      'makeRemoteSection',
-      'makeSection',
       'mergeDisjointRecords',
       'methodArgsToStruct',
-      'noopLift',
       'prettifySmallcaps',
-      'proxyLift',
       'retry',
       'retryWithBackoff',
-      'sheafify',
-      'source',
       'stringify',
       'toHex',
       'waitUntilQuiescent',
-      'withFilter',
-      'withRanking',
     ]);
   });
 });

packages/kernel-utils/src/index.ts

@@ -44,23 +44,3 @@ export {
   DEFAULT_MAX_DELAY_MS,
 } from './retry.ts';
 export type { RetryBackoffOptions, RetryOnRetryInfo } from './retry.ts';
-export type {
-  Section,
-  PresheafSection,
-  EvaluatedSection,
-  MetadataSpec,
-  Lift,
-  LiftContext,
-  Sheaf,
-} from './sheaf/types.ts';
-export { constant, source, callable } from './sheaf/metadata.ts';
-export { sheafify } from './sheaf/sheafify.ts';
-export {
-  noopLift,
-  proxyLift,
-  withFilter,
-  withRanking,
-  fallthrough,
-} from './sheaf/compose.ts';
-export { makeRemoteSection } from './sheaf/remote.ts';
-export { makeSection } from './sheaf/section.ts';

packages/kernel-utils/src/sheaf/index.ts

@@ -0,0 +1,20 @@
+export type {
+  Section,
+  PresheafSection,
+  EvaluatedSection,
+  MetadataSpec,
+  Lift,
+  LiftContext,
+  Sheaf,
+} from './types.ts';
+export { constant, source, callable } from './metadata.ts';
+export { sheafify } from './sheafify.ts';
+export {
+  noopLift,
+  proxyLift,
+  withFilter,
+  withRanking,
+  fallthrough,
+} from './compose.ts';
+export { makeRemoteSection } from './remote.ts';
+export { makeSection } from './section.ts';