feat(kernel-utils): add getDiscoverableSection, deprecate global section methods

Adds getDiscoverableSection and getDiscoverableGlobalSection to the Sheaf API
so callers can attach a MethodSchema (for __getDescription__) to the
caller-facing dispatch section rather than inside individual capability wrappers.
Marks getGlobalSection and getDiscoverableGlobalSection as @deprecated —
callers should supply an explicit InterfaceGuard via getSection/getDiscoverableSection
instead of relying on the auto-computed union.

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

Author: grypez

packages/kernel-utils/src/sheaf/sheafify.test.ts

@@ -2,6 +2,7 @@ import { makeExo, GET_INTERFACE_GUARD } from '@endo/exo';
 import { M, getInterfaceGuardPayload } from '@endo/patterns';
 import { describe, it, expect } from 'vitest';
 
+import { GET_DESCRIPTION } from '../discoverable.ts';
 import { constant } from './metadata.ts';
 import { sheafify } from './sheafify.ts';
 import type {
@@ -614,6 +615,63 @@ describe('sheafify', () => {
     expect(methodGuards).toHaveProperty('getBalance');
   });
 
+  it('getDiscoverableGlobalSection exposes __getDescription__', async () => {
+    const schema = {
+      getBalance: {
+        description: 'Get account balance.',
+        args: { acct: { type: 'string' as const, description: 'Account id.' } },
+        returns: { type: 'number' as const, description: 'Balance.' },
+      },
+    };
+    const sections: PresheafSection<Record<string, never>>[] = [
+      {
+        exo: makeExo(
+          'Wallet:0',
+          M.interface('Wallet:0', {
+            getBalance: M.call(M.string()).returns(M.number()),
+          }),
+          { getBalance: (_acct: string) => 42 },
+        ) as unknown as Section,
+      },
+    ];
+
+    const section = sheafify({
+      name: 'Wallet',
+      sections,
+    }).getDiscoverableGlobalSection({
+      async *lift(germs) {
+        yield germs[0]!;
+      },
+      schema,
+    });
+
+    expect(E(section)[GET_DESCRIPTION]()).toStrictEqual(schema);
+  });
+
+  it('getSection does not expose __getDescription__', () => {
+    const sections: PresheafSection<Record<string, never>>[] = [
+      {
+        exo: makeExo(
+          'Wallet:0',
+          M.interface('Wallet:0', {
+            getBalance: M.call(M.string()).returns(M.number()),
+          }),
+          { getBalance: (_acct: string) => 42 },
+        ) as unknown as Section,
+      },
+    ];
+
+    const section = sheafify({ name: 'Wallet', sections }).getGlobalSection({
+      async *lift(germs) {
+        yield germs[0]!;
+      },
+    });
+
+    expect(
+      (section as Record<string, unknown>)[GET_DESCRIPTION],
+    ).toBeUndefined();
+  });
+
   it('getExported excludes revoked sections', () => {
     const sections: PresheafSection<{ cost: number }>[] = [
       {

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

@@ -20,6 +20,8 @@ import {
 } from '@endo/patterns';
 import type { InterfaceGuard, MethodGuard } from '@endo/patterns';
 
+import { makeDiscoverableExo } from '../discoverable.ts';
+import type { MethodSchema } from '../schema.ts';
 import { stringify } from '../stringify.ts';
 import { driveLift } from './drive.ts';
 import { collectSheafGuard } from './guard.ts';
@@ -210,12 +212,14 @@ export const sheafify = <
   );
   const grants: Grant[] = [];
 
-  const getSection = ({
+  const buildSection = ({
     guard,
     lift,
+    schema,
   }: {
     guard: InterfaceGuard;
     lift: Lift<MetaData>;
+    schema?: Record<string, MethodSchema>;
   }): object => {
     const resolvedGuard = guard;
 
@@ -286,11 +290,14 @@ export const sheafify = <
       handlers[method] = async (...args: unknown[]) => dispatch(method, args);
     }
 
-    const exo = makeExo(
-      `${name}:section`,
-      asyncGuard,
-      handlers,
-    ) as unknown as Section;
+    const exo = (schema === undefined
+      ? makeExo(`${name}:section`, asyncGuard, handlers)
+      : makeDiscoverableExo(
+          `${name}:section`,
+          handlers,
+          schema,
+          asyncGuard,
+        )) as unknown as Section;
 
     grants.push({
       exo,
@@ -304,15 +311,40 @@ export const sheafify = <
     return exo;
   };
 
-  const getGlobalSection = ({ lift }: { lift: Lift<MetaData> }): object => {
-    return getSection({
-      guard: collectSheafGuard(
-        name,
-        frozenSections.map(({ exo }) => exo),
-      ),
-      lift,
-    });
-  };
+  const unionGuard = (): InterfaceGuard =>
+    collectSheafGuard(
+      name,
+      frozenSections.map(({ exo }) => exo),
+    );
+
+  const getSection = ({
+    guard,
+    lift,
+  }: {
+    guard: InterfaceGuard;
+    lift: Lift<MetaData>;
+  }): object => buildSection({ guard, lift });
+
+  const getDiscoverableSection = ({
+    guard,
+    lift,
+    schema,
+  }: {
+    guard: InterfaceGuard;
+    lift: Lift<MetaData>;
+    schema: Record<string, MethodSchema>;
+  }): object => buildSection({ guard, lift, schema });
+
+  const getGlobalSection = ({ lift }: { lift: Lift<MetaData> }): object =>
+    buildSection({ guard: unionGuard(), lift });
+
+  const getDiscoverableGlobalSection = ({
+    lift,
+    schema,
+  }: {
+    lift: Lift<MetaData>;
+    schema: Record<string, MethodSchema>;
+  }): object => buildSection({ guard: unionGuard(), lift, schema });
 
   const revokePoint = (method: string, ...args: unknown[]): void => {
     for (const grant of grants) {
@@ -342,7 +374,9 @@ export const sheafify = <
 
   return {
     getSection,
+    getDiscoverableSection,
     getGlobalSection,
+    getDiscoverableGlobalSection,
     revokePoint,
     getExported,
     revokeAll,

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

@@ -10,6 +10,8 @@
 import type { GET_INTERFACE_GUARD, Methods } from '@endo/exo';
 import type { InterfaceGuard } from '@endo/patterns';
 
+import type { MethodSchema } from '../schema.ts';
+
 /** A section: a capability covering a region of the interface topology. */
 export type Section<Core extends Methods = Methods> = Partial<Core> & {
   [K in typeof GET_INTERFACE_GUARD]?: (() => InterfaceGuard) | undefined;
@@ -98,8 +100,27 @@ export type Presheaf<MetaData extends Record<string, unknown>> =
 export type Sheaf<MetaData extends Record<string, unknown>> = {
   /** Produce a revocable dispatch exo over the given guard. */
   getSection: (opts: { guard: InterfaceGuard; lift: Lift<MetaData> }) => object;
-  /** Produce a revocable dispatch exo over the full union guard of all presheaf sections. */
+  /** Produce a revocable discoverable dispatch exo over the given guard. */
+  getDiscoverableSection: (opts: {
+    guard: InterfaceGuard;
+    lift: Lift<MetaData>;
+    schema: Record<string, MethodSchema>;
+  }) => object;
+  /**
+   * Produce a revocable dispatch exo over the full union guard of all presheaf sections.
+   *
+   * @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.
+   *
+   * @deprecated Provide an explicit guard via getDiscoverableSection instead.
+   */
+  getDiscoverableGlobalSection: (opts: {
+    lift: Lift<MetaData>;
+    schema: Record<string, MethodSchema>;
+  }) => object;
   /** Revoke every granted section whose guard covers the point (method, ...args). */
   revokePoint: (method: string, ...args: unknown[]) => void;
   /** Union guard of all active (non-revoked) granted sections, or undefined. */