refactor(sheaves): revert section → handler rename

Restores the original section vocabulary in the package: type Handler
becomes Section, makeHandler becomes makeSection, the field on Provider
and Candidate becomes exo, and the internal helper invokeHandler
becomes invokeExo. Error messages, doc comments, README, USAGE.md,
POLICY.md, and CHANGELOG are updated to match. The presheaf → provider,
lift → policy, and germ → candidate renames from the prior terminology
refactor are kept in place.

Author: grypez

packages/sheaves/CHANGELOG.md

@@ -14,11 +14,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release, extracted from `@metamask/kernel-utils`.
 - `sheafify({ name, providers })` — constructs a sheaf authority manager over a
   set of capability providers.
-- `Provider<M>` type — an input to `sheafify`: a `{ handler, metadata? }` pair
-  where `handler` is an exo and `metadata` is an optional `MetadataSpec<M>`.
-- `Candidate<M>` type — a post-evaluation entry in the stalk: `{ handler,
+- `Provider<M>` type — an input to `sheafify`: a `{ exo, metadata? }` pair
+  where `exo` is a `Section` and `metadata` is an optional `MetadataSpec<M>`.
+- `Candidate<M>` type — a post-evaluation entry in the stalk: `{ exo,
 metadata }` with metadata already resolved from its spec.
-- `Handler` type — an exo capability covering a region of the interface
+- `Section` type — an exo capability covering a region of the interface
   topology.
 - `Policy<M>` type — an `async function*` coroutine that receives candidates
   and yields them in preference order; drives the sheaf dispatch loop.
@@ -31,7 +31,7 @@ constraints }`.
   compartment at `sheafify` construction time.
 - `callable(fn)` — callable metadata spec; evaluated per-dispatch with the
   invocation arguments.
-- `makeHandler(name, guard, methods)` — creates a named, guarded exo handler.
+- `makeSection(name, guard, handlers)` — creates a named, guarded `Section` from a method-handler map.
 - `makeRemoteSection(tag, remoteRef, metadata?)` — builds a provider that
   wraps a remote capability, fetching its interface guard via `E`.
 - `noopPolicy` — a policy that yields candidates in the order received.

packages/sheaves/README.md

@@ -3,7 +3,7 @@
 Runtime capability routing adapted from sheaf theory in algebraic topology.
 
 `sheafify({ name, providers })` produces a **sheaf** — an authority manager
-over a collection of capability providers. The sheaf produces dispatch handlers via
+over a collection of capability providers. The sheaf produces dispatch sections via
 `getSection`, each of which routes invocations through the provider set.
 
 See [USAGE.md](./USAGE.md) for annotated examples and [POLICY.md](./POLICY.md) for
@@ -21,8 +21,8 @@ npm install @metamask/sheaves
 
 ## Concepts
 
-**Provider** (`Provider`) — The input data: a capability handler paired with
-operational metadata, assigned over the open set defined by the handler's guard.
+**Provider** (`Provider`) — The input data: a capability `Section` (exo) paired with
+operational metadata, assigned over the open set defined by the exo's guard.
 This is an element of the presheaf F = F_sem x F_op.
 
 > A `getBalance(string)` provider with `{ cost: 100 }` is one provider. A
@@ -63,14 +63,14 @@ context.
 
 **Sheaf** — The authority manager returned by `sheafify`. Holds the provider
 data (frozen at construction time) and exposes factory methods that
-produce dispatch handlers on demand.
+produce dispatch sections on demand.
 
 ```
 const sheaf = sheafify({ name: 'Wallet', providers });
 ```
 
-- `sheaf.getSection({ guard, lift })` — produce a dispatch handler
-- `sheaf.getDiscoverableSection({ guard, lift, schema })` — same, but the handler exposes its guard
+- `sheaf.getSection({ guard, lift })` — produce a dispatch section
+- `sheaf.getDiscoverableSection({ guard, lift, schema })` — same, but the section exposes its guard
 
 ## Dispatch pipeline
 
@@ -83,7 +83,7 @@ collapseEquivalent(stalk)            locality condition (quotient by metadata)
 decomposeMetadata(collapsed)         restriction map (constraints / options)
 policy(candidates, { method, args,   operational selection (extra-theoretic)
                   constraints })
-dispatch to chosen.handler           evaluation
+dispatch to chosen.exo           evaluation
 ```
 
 The pipeline short-circuits at two points: if only one provider matches the

packages/sheaves/documents/POLICY.md

@@ -27,13 +27,13 @@ The sheaf drives it with the following protocol:
    new object with the same shape will throw with a message like "Policy yielded
    an unrecognized candidate". Sorting with `[...candidates].sort(...)` is safe
    because sort preserves references; mapping to new objects is not.
-3. **Attempt** — the sheaf calls the candidate's handler method.
+3. **Attempt** — the sheaf calls the candidate's exo method.
 4. **Success** — the result is returned; the generator is abandoned.
 5. **Failure** — the sheaf calls `gen.next(errors)`, passing the ordered list
    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 throws
-   `new Error('No viable handler for <method>', { cause: errors })` where
+   `new Error('No viable section for <method>', { cause: errors })` where
    `errors` is the full accumulated list of every failure so far.
 
 Most policies express a fixed priority order and can ignore the error input:
@@ -87,11 +87,11 @@ Encode each provider's cost as `callable` metadata evaluated at dispatch time:
 ```ts
 const providers: Provider<SwapMeta>[] = [
   {
-    handler: providerAHandler,
+    exo: providerASection,
     metadata: callable((args) => ({ cost: providerACost(Number(args[0])) })),
   },
   {
-    handler: providerBHandler,
+    exo: providerBSection,
     metadata: callable((args) => ({ cost: providerBCost(Number(args[0])) })),
   },
 ];

packages/sheaves/documents/USAGE.md

@@ -8,25 +8,25 @@ policy as a placeholder:
 
 ```ts
 import { M } from '@endo/patterns';
-import { sheafify, makeHandler, noopPolicy } from '@metamask/sheaves';
+import { sheafify, makeSection, noopPolicy } from '@metamask/sheaves';
 
 const priceGuard = M.interface('PriceService', {
   getPrice: M.callWhen(M.await(M.string())).returns(M.await(M.number())),
 });
 
-const priceHandler = makeHandler('PriceService', priceGuard, {
+const priceSection = makeSection('PriceService', priceGuard, {
   async getPrice(token) {
     return fetchPrice(token);
   },
 });
 
 const sheaf = sheafify({
   name: 'PriceService',
-  providers: [{ handler: priceHandler }],
+  providers: [{ exo: priceSection }],
 });
 
 const section = sheaf.getSection({ guard: priceGuard, lift: noopPolicy });
-// section is a dispatch handler; call it like any capability
+// section is a dispatch section; call it like any capability
 const price = await E(section).getPrice('ETH');
 ```
 
@@ -54,8 +54,8 @@ const preferFast: Policy<WalletMeta> = async function* (candidates) {
 const sheaf = sheafify<WalletMeta>({
   name: 'Wallet',
   providers: [
-    { handler: fastHandler, metadata: constant({ mode: 'fast' }) },
-    { handler: reliableHandler, metadata: constant({ mode: 'reliable' }) },
+    { exo: fastSection, metadata: constant({ mode: 'fast' }) },
+    { exo: reliableSection, metadata: constant({ mode: 'reliable' }) },
   ],
 });
 
@@ -86,7 +86,7 @@ callable((args) => ({ cost: Number(args[0]) > 9000 ? 'high' : 'low' }));
 
 ## Discoverable sections
 
-`getDiscoverableSection` works like `getSection` but the returned handler
+`getDiscoverableSection` works like `getSection` but the returned section
 exposes its guard — it can be introspected by the caller to discover what
 methods and argument shapes it accepts. Use this when the recipient needs to
 advertise capability to a third party. It requires a `schema` map describing
@@ -120,13 +120,13 @@ global variants are the right choice.
 
 `makeRemoteSection` wraps a CapTP remote reference as a `Provider`, fetching
 the remote's guard once at construction and forwarding all calls via `E()`.
-This lets you mix local handlers and remote capabilities in the same sheaf:
+This lets you mix local sections and remote capabilities in the same sheaf:
 
 ```ts
-import { makeHandler, makeRemoteSection, constant } from '@metamask/sheaves';
+import { makeSection, makeRemoteSection, constant } from '@metamask/sheaves';
 
 const remoteProvider = await makeRemoteSection(
-  'RemoteWallet', // name for the wrapper handler
+  'RemoteWallet', // name for the wrapper section
   remoteCapRef, // CapTP reference
   constant({ mode: 'remote' }), // optional metadata
 );

packages/sheaves/src/compose.test.ts

@@ -16,7 +16,7 @@ type Meta = { id: string; cost: number };
 type C = Candidate<Partial<Meta>>;
 
 const makeCandidate = (id: string, cost = 0): C => ({
-  handler: {} as C['handler'],
+  exo: {} as C['exo'],
   metadata: { id, cost },
 });
 

packages/sheaves/src/guard.test.ts

@@ -6,25 +6,25 @@ import {
   getInterfaceMethodGuards,
   getMethodPayload,
 } from './guard.ts';
-import { makeHandler } from './section.ts';
+import { makeSection } from './section.ts';
 import { guardCoversPoint } from './stalk.ts';
 
 describe('collectSheafGuard', () => {
   it('variable arity: add with 1, 2, and 3 args', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'Calc:0',
         M.interface('Calc:0', { add: M.call(M.number()).returns(M.number()) }),
         { add: (a: number) => a },
       ),
-      makeHandler(
+      makeSection(
         'Calc:1',
         M.interface('Calc:1', {
           add: M.call(M.number(), M.number()).returns(M.number()),
         }),
         { add: (a: number, b: number) => a + b },
       ),
-      makeHandler(
+      makeSection(
         'Calc:2',
         M.interface('Calc:2', {
           add: M.call(M.number(), M.number(), M.number()).returns(M.number()),
@@ -44,12 +44,12 @@ describe('collectSheafGuard', () => {
 
   it('return guard union', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'S:0',
         M.interface('S:0', { f: M.call(M.eq(0)).returns(M.eq(0)) }),
         { f: (_: number) => 0 },
       ),
-      makeHandler(
+      makeSection(
         'S:1',
         M.interface('S:1', { f: M.call(M.eq(1)).returns(M.eq(1)) }),
         { f: (_: number) => 1 },
@@ -67,7 +67,7 @@ describe('collectSheafGuard', () => {
 
   it('section with its own optional args: optional preserved in union', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'Greeter',
         M.interface('Greeter', {
           greet: M.callWhen(M.string())
@@ -88,7 +88,7 @@ describe('collectSheafGuard', () => {
 
   it('rest arg guard preserved in collected union', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'Logger',
         M.interface('Logger', {
           log: M.call(M.string()).rest(M.string()).returns(M.any()),
@@ -108,14 +108,14 @@ describe('collectSheafGuard', () => {
 
   it('rest arg guards unioned across sections', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'A',
         M.interface('A', {
           log: M.call(M.string()).rest(M.string()).returns(M.any()),
         }),
         { log: (..._args: string[]) => undefined },
       ),
-      makeHandler(
+      makeSection(
         'B',
         M.interface('B', {
           log: M.call(M.string()).rest(M.number()).returns(M.any()),
@@ -137,12 +137,12 @@ describe('collectSheafGuard', () => {
     // number of strings via rest. A call ['hello'] is covered by B — the
     // collected guard must pass it too.
     const sections = [
-      makeHandler(
+      makeSection(
         'AB:0',
         M.interface('AB:0', { f: M.call(M.number()).returns(M.any()) }),
         { f: (_: number) => undefined },
       ),
-      makeHandler(
+      makeSection(
         'AB:1',
         M.interface('AB:1', { f: M.call().rest(M.string()).returns(M.any()) }),
         { f: (..._args: string[]) => undefined },
@@ -158,7 +158,7 @@ describe('collectSheafGuard', () => {
 
   it('multi-method guard collection', () => {
     const sections = [
-      makeHandler(
+      makeSection(
         'Multi:0',
         M.interface('Multi:0', {
           translate: M.call(M.string(), M.string()).returns(M.string()),
@@ -167,7 +167,7 @@ describe('collectSheafGuard', () => {
           translate: (from: string, to: string) => `${from}->${to}`,
         },
       ),
-      makeHandler(
+      makeSection(
         'Multi:1',
         M.interface('Multi:1', {
           translate: M.call(M.string(), M.string()).returns(M.string()),

packages/sheaves/src/guard.ts

@@ -7,7 +7,7 @@ import {
 } from '@endo/patterns';
 import type { InterfaceGuard, MethodGuard, Pattern } from '@endo/patterns';
 
-import type { Handler } from './types.ts';
+import type { Section } from './types.ts';
 
 export type MethodGuardPayload = {
   argGuards: Pattern[];
@@ -87,23 +87,23 @@ const unionGuard = (guards: Pattern[]): Pattern => {
 };
 
 /**
- * Compute the union of all handler guards — the open set covered by the sheafified facade.
+ * Compute the union of all section guards — the open set covered by the sheafified facade.
  *
- * For each method name across all handlers, collects the arg guards at each
- * position and produces a union via M.or. Handlers with fewer args than
+ * For each method name across all sections, collects the arg guards at each
+ * position and produces a union via M.or. Sections with fewer args than
  * the maximum contribute to required args; the remainder become optional.
  *
  * @param name - The name for the collected interface guard.
- * @param handlers - The handlers whose guards are collected.
- * @returns An interface guard covering all handlers.
+ * @param sections - The sections whose guards are collected.
+ * @returns An interface guard covering all sections.
  */
 export const collectSheafGuard = <Core extends Methods>(
   name: string,
-  handlers: Handler<Core>[],
+  sections: Section<Core>[],
 ): InterfaceGuard => {
   const payloadsByMethod = new Map<string, MethodGuardPayload[]>();
 
-  for (const section of handlers) {
+  for (const section of sections) {
     const interfaceGuard = section[GET_INTERFACE_GUARD]?.();
     if (!interfaceGuard) {
       continue;

packages/sheaves/src/index.ts

@@ -1,5 +1,5 @@
 export type {
-  Handler,
+  Section,
   Provider,
   Candidate,
   MetadataSpec,
@@ -17,4 +17,4 @@ export {
   fallthrough,
 } from './compose.ts';
 export { makeRemoteSection } from './remote.ts';
-export { makeHandler } from './section.ts';
+export { makeSection } from './section.ts';