docs(sheaves): update USAGE.md and POLICY.md terminology

Author: grypez

packages/sheaves/documents/POLICY.md

@@ -1,8 +1,8 @@
 # Policy
 
 The policy is the caller-supplied selection coroutine in the sheaf dispatch
-pipeline. It runs when the stalk at an invocation point contains more than one
-candidate and the sheaf has no data to resolve the ambiguity on its own. The
+pipeline. It runs when more than one candidate matches an invocation and the sheaf
+has no data to resolve the ambiguity on its own. The
 caller is responsible for writing a policy that is correct for the providers it
 will receive.
 
@@ -70,9 +70,9 @@ type PolicyContext<M> = {
 };
 ```
 
-**`constraints`** are metadata keys whose values are the same on every
-candidate in the stalk. Because all candidates agree on these keys, they carry
-no information useful for choosing between them — the sheaf strips them from
+**`constraints`** are metadata keys whose values are the same across every
+candidate. Because all candidates agree on these keys, they carry no
+information useful for choosing between them — the sheaf strips them from
 each candidate and delivers them separately. A policy that needs to know, say,
 the agreed `protocol` version reads it from `context.constraints.protocol`
 rather than from any individual candidate.

packages/sheaves/documents/USAGE.md

@@ -2,60 +2,60 @@
 
 ## Single provider
 
-When there is only one section per invocation point, no lift is needed — the
-dispatch short-circuits before the lift is ever called. Provide a no-op lift
-as a placeholder:
+When there is only one provider per invocation point, no policy is needed —
+the dispatch short-circuits before the policy is ever called. Provide a no-op
+policy as a placeholder:
 
 ```ts
 import { M } from '@endo/patterns';
-import { sheafify, makeSection, noopLift } from '@metamask/kernel-utils';
+import { sheafify, makeHandler, noopPolicy } from '@metamask/sheaves';
 
 const priceGuard = M.interface('PriceService', {
   getPrice: M.callWhen(M.await(M.string())).returns(M.await(M.number())),
 });
 
-const priceExo = makeSection('PriceService', priceGuard, {
+const priceHandler = makeHandler('PriceService', priceGuard, {
   async getPrice(token) {
     return fetchPrice(token);
   },
 });
 
 const sheaf = sheafify({
   name: 'PriceService',
-  sections: [{ exo: priceExo }],
+  providers: [{ handler: priceHandler }],
 });
 
-const section = sheaf.getSection({ guard: priceGuard, lift: noopLift });
-// section is a dispatch exo; call it like any capability
+const section = sheaf.getSection({ guard: priceGuard, lift: noopPolicy });
+// section is a dispatch handler; call it like any capability
 const price = await E(section).getPrice('ETH');
 ```
 
-## Multiple providers with a lift
+## Multiple providers with a policy
 
-When the stalk at a given invocation point contains more than one germ, the
-sheaf calls the lift to choose. The lift is an `async function*` coroutine that
-yields candidates in preference order; it receives accumulated errors as the
-argument to each subsequent `.next()` so it can adapt its ranking.
+When more than one candidate matches an invocation, the sheaf calls the policy
+to choose. The policy is an `async function*` coroutine that yields candidates
+in preference order; it receives accumulated errors as the argument to each
+subsequent `.next()` so it can adapt its ranking.
 
 The idiomatic pattern is a generator that `yield*`s candidates filtered by
 metadata, expressing priority tiers in source order:
 
 ```ts
-import { sheafify, constant } from '@metamask/kernel-utils';
-import type { Lift } from '@metamask/kernel-utils';
+import { sheafify, constant } from '@metamask/sheaves';
+import type { Policy } from '@metamask/sheaves';
 
 type WalletMeta = { mode: 'fast' | 'reliable' };
 
-const preferFast: Lift<WalletMeta> = async function* (germs) {
-  yield* germs.filter((g) => g.metadata?.mode === 'fast');
-  yield* germs.filter((g) => g.metadata?.mode === 'reliable');
+const preferFast: Policy<WalletMeta> = async function* (candidates) {
+  yield* candidates.filter((c) => c.metadata?.mode === 'fast');
+  yield* candidates.filter((c) => c.metadata?.mode === 'reliable');
 };
 
 const sheaf = sheafify<WalletMeta>({
   name: 'Wallet',
-  sections: [
-    { exo: fastExo, metadata: constant({ mode: 'fast' }) },
-    { exo: reliableExo, metadata: constant({ mode: 'reliable' }) },
+  providers: [
+    { handler: fastHandler, metadata: constant({ mode: 'fast' }) },
+    { handler: reliableHandler, metadata: constant({ mode: 'reliable' }) },
   ],
 });
 
@@ -65,12 +65,12 @@ const section = sheaf.getSection({ guard: clientGuard, lift: preferFast });
 
 The sheaf drives the generator: it primes it with `gen.next([])`, calls the
 chosen candidate, then passes any thrown errors back as `gen.next(errors)` so
-the lift can adapt before yielding the next candidate.
+the policy can adapt before yielding the next candidate.
 
 Use the `constant`, `source`, or `callable` helpers to build metadata specs:
 
 ```ts
-import { constant, source, callable } from '@metamask/kernel-utils';
+import { constant, source, callable } from '@metamask/sheaves';
 
 // static value known at construction time
 constant({ mode: 'fast' });
@@ -86,10 +86,11 @@ callable((args) => ({ cost: Number(args[0]) > 9000 ? 'high' : 'low' }));
 
 ## Discoverable sections
 
-`getDiscoverableSection` works like `getSection` but the returned exo 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 each method:
+`getDiscoverableSection` works like `getSection` but the returned handler
+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
+each method:
 
 ```ts
 import type { MethodSchema } from '@metamask/kernel-utils';
@@ -108,60 +109,56 @@ const section = sheaf.getDiscoverableSection({
 `getSection` is the non-discoverable variant (no `schema` required).
 
 `getGlobalSection` and `getDiscoverableGlobalSection` derive the guard
-automatically from the union of all presheaf sections. They are `@deprecated`
-as a nudge toward explicit guards once the caller knows the section set —
-explicit guards make the capability's scope visible at the call site. When
-sections are assembled dynamically (e.g., rebuilt at runtime from a set of
-grants that changes) and the union guard isn't known until after `sheafify`
-runs, the global variants are the right choice.
+automatically from the union of all providers. They are `@deprecated` as a
+nudge toward explicit guards once the caller knows the provider set — explicit
+guards make the capability's scope visible at the call site. When providers are
+assembled dynamically (e.g., rebuilt at runtime from a set of grants that
+changes) and the union guard isn't known until after `sheafify` runs, the
+global variants are the right choice.
 
-## Remote sections
+## Remote providers
 
-`makeRemoteSection` wraps a CapTP remote reference as a `PresheafSection`,
-fetching the remote's guard once at construction and forwarding all calls via
-`E()`. This lets you mix local exos and remote capabilities in the same sheaf:
+`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:
 
 ```ts
-import {
-  makeSection,
-  makeRemoteSection,
-  constant,
-} from '@metamask/kernel-utils';
+import { makeHandler, makeRemoteSection, constant } from '@metamask/sheaves';
 
-const remoteSection = await makeRemoteSection(
-  'RemoteWallet', // name for the wrapper exo
+const remoteProvider = await makeRemoteSection(
+  'RemoteWallet', // name for the wrapper handler
   remoteCapRef, // CapTP reference
   constant({ mode: 'remote' }), // optional metadata
 );
 
 const sheaf = sheafify({
   name: 'Mixed',
-  sections: [localSection, remoteSection],
+  providers: [localProvider, remoteProvider],
 });
 ```
 
-## Lift composition
+## Policy composition
 
-`@metamask/kernel-utils` exports helpers for building lifts from composable
-parts, useful when lift logic would otherwise be duplicated across callers:
+`@metamask/sheaves` exports helpers for building policies from composable
+parts, useful when policy logic would otherwise be duplicated across callers:
 
 ```ts
 import {
-  proxyLift,
+  proxyPolicy,
   withFilter,
   withRanking,
   fallthrough,
-} from '@metamask/kernel-utils';
+} from '@metamask/sheaves';
 ```
 
-- **`withRanking(comparator)(inner)`** — sort germs by comparator before
+- **`withRanking(comparator)(inner)`** — sort candidates by comparator before
   passing to `inner`
-- **`withFilter(predicate)(inner)`** — remove germs that fail `predicate`
+- **`withFilter(predicate)(inner)`** — remove candidates that fail `predicate`
   before passing to `inner`
-- **`fallthrough(liftA, liftB)`** — try all candidates from `liftA` first;
-  if all fail, try `liftB`
-- **`proxyLift(gen)`** — forward yielded candidates up and error arrays down
+- **`fallthrough(policyA, policyB)`** — try all candidates from `policyA`
+  first; if all fail, try `policyB`
+- **`proxyPolicy(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` —
+  composition (`fallthrough`, `withFilter`) you do not need `proxyPolicy` —
   `yield*` forwards `.next(value)` to the delegated iterator automatically.