docs(kernel-utils): documentation pass for sheaf module

- LIFT.md: fix exhaustion description to match actual error shape
- README.md: remove stale "registry" and "tracks" claims post-revocation-removal
- types.ts: remove "revocable" from Sheaf method docs; clarify when to use
  global section variants vs explicit-guard variants
- USAGE.md: use makeSection (public API) in single-provider example; clarify
  proxyLift vs yield* for lift composition

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

Author: grypez

packages/kernel-utils/src/sheaf/LIFT.md

@@ -33,7 +33,8 @@ The sheaf drives it with the following protocol:
    of every error thrown so far (cumulative, not just the last). The coroutine
    receives this as the resolved value of its `yield` expression.
 6. **Exhausted** — if the generator returns without yielding, the sheaf
-   rethrows the last error.
+   throws `new Error('No viable section for <method>', { cause: errors })`
+   where `errors` is the full accumulated list of every failure so far.
 
 Most lifts express a fixed priority order and can ignore the error input:
 

packages/kernel-utils/src/sheaf/README.md

@@ -3,8 +3,8 @@
 Runtime capability routing adapted from sheaf theory in algebraic topology.
 
 `sheafify({ name, sections })` produces a **sheaf** — an authority manager
-over a presheaf of capabilities. The sheaf grants dispatch sections via
-`getSection` and tracks all delegated authority.
+over a presheaf of capabilities. The sheaf produces dispatch sections via
+`getSection`, each of which routes invocations through the presheaf.
 
 See [USAGE.md](./USAGE.md) for annotated examples and [LIFT.md](./LIFT.md) for
 the lift coroutine protocol and semantic equivalence assumption.
@@ -52,7 +52,8 @@ context.
 > identical metadata and collapsed to one representative.
 
 **Sheaf** — The authority manager returned by `sheafify`. Holds the presheaf
-data (captured at construction time) and a registry of all granted sections.
+data (sections frozen at construction time) and exposes factory methods that
+produce dispatch exos on demand.
 
 ```
 const sheaf = sheafify({ name: 'Wallet', sections });

packages/kernel-utils/src/sheaf/USAGE.md

@@ -8,14 +8,13 @@ as a placeholder:
 
 ```ts
 import { M } from '@endo/patterns';
-import { makeDefaultExo } from '<internal>';
-import { sheafify, noopLift } from '@metamask/kernel-utils';
+import { sheafify, makeSection, noopLift } from '@metamask/kernel-utils';
 
 const priceGuard = M.interface('PriceService', {
   getPrice: M.callWhen(M.await(M.string())).returns(M.await(M.number())),
 });
 
-const priceExo = makeDefaultExo('PriceService', priceGuard, {
+const priceExo = makeSection('PriceService', priceGuard, {
   async getPrice(token) {
     return fetchPrice(token);
   },
@@ -161,5 +160,8 @@ import {
   before passing to `inner`
 - **`fallthrough(liftA, liftB)`** — try all candidates from `liftA` first;
   if all fail, try `liftB`
-- **`proxyLift(inner)`** — forward yielded candidates up and error arrays down;
-  useful when wrapping a lift in middleware
+- **`proxyLift(gen)`** — forward yielded candidates up and error arrays down
+  to an already-started generator; useful when you need to add logic between
+  yields (logging, counting, conditional abort). For simple sequential
+  composition (`fallthrough`, `withFilter`) you do not need `proxyLift` —
+  `yield*` forwards `.next(value)` to the delegated iterator automatically.

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

@@ -88,12 +88,12 @@ export type Lift<MetaData extends Record<string, unknown>> = (
 /**
  * A sheaf: an authority manager over a presheaf.
  *
- * Produces revocable dispatch sections via `getSection` and tracks all
- * granted authority for auditing and revocation.
+ * Produces dispatch sections via `getSection`, each routing invocations
+ * through the presheaf sections supplied at construction time.
  */
 export type Sheaf<MetaData extends Record<string, unknown>> = {
   /**
-   * Produce a revocable dispatch exo over the given guard.
+   * Produce a dispatch exo over the given guard.
    *
    * Returns `object` rather than a typed exo because the guard is passed
    * dynamically at call time — TypeScript cannot propagate the method
@@ -102,7 +102,7 @@ export type Sheaf<MetaData extends Record<string, unknown>> = {
    */
   getSection: (opts: { guard: InterfaceGuard; lift: Lift<MetaData> }) => object;
   /**
-   * Produce a revocable discoverable dispatch exo over the given guard.
+   * Produce a discoverable dispatch exo over the given guard.
    *
    * Returns `object` for the same reason as `getSection`.
    */
@@ -112,13 +112,22 @@ export type Sheaf<MetaData extends Record<string, unknown>> = {
     schema: Record<string, MethodSchema>;
   }) => object;
   /**
-   * Produce a revocable dispatch exo over the full union guard of all presheaf sections.
+   * Produce a dispatch exo over the full union guard of all presheaf sections.
+   *
+   * Prefer `getSection` with an explicit guard when the guard is statically
+   * known — it makes the capability's scope visible at the call site. Use the
+   * global variant when sections are assembled dynamically at runtime and the
+   * union guard is not known until after `sheafify` runs.
    *
    * @deprecated Provide an explicit guard via getSection instead.
    */
   getGlobalSection: (opts: { lift: Lift<MetaData> }) => object;
   /**
-   * Produce a revocable discoverable dispatch exo over the full union guard of all presheaf sections.
+   * Produce a discoverable dispatch exo over the full union guard of all presheaf sections.
+   *
+   * Prefer `getDiscoverableSection` with an explicit guard when the guard is
+   * statically known. Use the global variant when sections are assembled
+   * dynamically and the union guard is not known until after `sheafify` runs.
    *
    * @deprecated Provide an explicit guard via getDiscoverableSection instead.
    */