feat(kernel-utils): add described*() combinators for guard+schema authoring (#958)

## Explanation

Adds a `./described` export whose combinators author an `@endo/patterns`
interface guard and a matching `MethodSchema` from a single source, so a
discoverable exo's enforced shape and its `__getDescription__` hint
cannot
drift.

The combinator namespace is exported as `S` (mirroring
`@endo/patterns`'s `M`
and `@endo/eventual-send`'s `E`). `D` was avoided because it reads as
liveslots'
`D()` device operator to readers familiar with that codebase. `S` is the
single
authoring surface — there are no bare combinator function exports:

- Leaves:
`S.string`/`S.number`/`S.boolean`/`S.arrayOf`/`S.record`/`S.object`/`S.nothing`
each yield a `{ pattern, schema }` pair.
- `S.arg` names a positional parameter.
- `S.method` and `S.interface` assemble them into `{ guard, schema }` /
`{ interfaceGuard, schemas }`, ready to splat into
`makeDiscoverableExo`.

Because the enforced pattern and the descriptive schema are projected
from the
same authored leaves, their conformance is a construction invariant.
Method
guards use `M.callWhen(...).returns(...)` (exo methods are invoked
across an
eventual-send boundary) and the interface guard sets `defaultGuards:
'passable'`
so the `__getDescription__` method injected by `makeDiscoverableExo` is
allowed.
Optional arguments must be trailing (enforced by `S.method`).

### Before this PR

```ts
// guard and schema written by hand, independently — nothing keeps them in sync.
const interfaceGuard = M.interface('Math', {
  add: M.callWhen(M.arrayOf(M.number())).returns(M.number()),
});
const schemas = {
  add: {
    description: 'Add a list of numbers.',
    args: { summands: { type: 'array', items: { type: 'number' } } },
    returns: { type: 'number' },
  },
};
// Relax the guard to accept M.string() and the schema still advertises number[]:
// the membrane and the prompt now describe different methods, and nothing catches it.
```

### After this PR

```ts
// one source — the guard and the MethodSchema are projected from the
// same authored leaves, so they cannot drift.
const { interfaceGuard, schemas } = S.interface('Math', {
  add: S.method(
    'Add a list of numbers.',
    [S.arg('summands', S.arrayOf(S.number()))],
    S.number('The sum of the numbers.'),
  ),
});
```

## Test plan

- [x] `yarn workspace @metamask/kernel-utils test:dev:quiet` (304 pass,
incl. 13 new `described` tests)
- [x] `yarn workspace @metamask/kernel-utils build`
- [x] `yarn workspace @metamask/kernel-utils lint`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Additive API and schema metadata; behavior change is limited to
optional-arg validation/conversion where `required` is set.
> 
> **Overview**
> Adds **`@metamask/kernel-utils`** `./described` (and root **`S`**) so
discoverable exos can author **`@endo/patterns`** guards and
**`MethodSchema`** from one definition, avoiding drift between membrane
enforcement and **`__getDescription__`**.
> 
> **`S`** exposes leaves (`string`, `number`, `boolean`, `arrayOf`,
`record`, `object`, `nothing`), **`S.arg`**, **`S.method`** (async
**`M.callWhen`**, trailing optional args), and **`S.interface`** (
**`defaultGuards: 'passable'`** for injected description).
**`MethodSchema`** gains optional **`required`**;
**`methodArgsToStruct`** honors it for Superstruct validation.
**`service-discovery-types`** **`methodSchemaToMethodSpec`** now marks
parameters not in **`required`** as **`optional`**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
af20bba. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: grypez

packages/kernel-utils/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add a `./described` export with a combinator namespace `S` (`S.string`/`S.number`/`S.boolean`/`S.arrayOf`/`S.record`/`S.object`/`S.nothing` leaves, plus `S.arg`/`S.method`/`S.interface`) that authors an `@endo/patterns` interface guard and a matching `MethodSchema` from a single source, so a discoverable exo's enforced shape and its `__getDescription__` hint cannot drift ([#958](https://github.com/MetaMask/ocap-kernel/pull/958))
+- Add an optional `required` field to `MethodSchema` (mirroring `required` on object `JsonSchema`) naming which arguments are required, and a `{ required }` option on `methodArgsToStruct` that validates unlisted arguments as optional, so a method's argument schema can faithfully represent the optional trailing arguments its guard already allows ([#958](https://github.com/MetaMask/ocap-kernel/pull/958))
 - Add `getLibp2pRelayHome()` to the `./nodejs` exports, returning the libp2p relay's bookkeeping directory (default `~/.libp2p-relay`, overridable via `$LIBP2P_RELAY_HOME`) — kept separate from `$OCAP_HOME` so one relay can serve daemons with different OCAP_HOMEs ([#952](https://github.com/MetaMask/ocap-kernel/pull/952))
 - `startRelay()` accepts an optional `publicIp` that is fed to libp2p's `appendAnnounce`, so a relay running on a NAT-backed host can announce its publicly-reachable IPv4 alongside its bound NIC addresses ([#952](https://github.com/MetaMask/ocap-kernel/pull/952))
 

packages/kernel-utils/package.json

@@ -59,6 +59,16 @@
         "default": "./dist/discoverable.cjs"
       }
     },
+    "./described": {
+      "import": {
+        "types": "./dist/described.d.mts",
+        "default": "./dist/described.mjs"
+      },
+      "require": {
+        "types": "./dist/described.d.cts",
+        "default": "./dist/described.cjs"
+      }
+    },
     "./libp2p": {
       "import": {
         "types": "./dist/libp2p-relay.d.mts",

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

@@ -0,0 +1,201 @@
+import {
+  matches,
+  getInterfaceGuardPayload,
+  getMethodGuardPayload,
+} from '@endo/patterns';
+import { describe, expect, it } from 'vitest';
+
+import { S } from './described.ts';
+
+type MethodGuardPayload = {
+  argGuards: unknown[];
+  optionalArgGuards?: unknown[];
+  returnGuard: unknown;
+};
+
+const payloadOf = (guard: unknown): MethodGuardPayload =>
+  getMethodGuardPayload(guard as never) as unknown as MethodGuardPayload;
+
+describe('leaves', () => {
+  it.each([
+    {
+      name: 'string',
+      described: S.string('a word'),
+      schema: { type: 'string', description: 'a word' },
+      ok: 'hello',
+      bad: 42,
+    },
+    {
+      name: 'number',
+      described: S.number(),
+      schema: { type: 'number' },
+      ok: 42,
+      bad: 'hello',
+    },
+    {
+      name: 'boolean',
+      described: S.boolean(),
+      schema: { type: 'boolean' },
+      ok: true,
+      bad: 1,
+    },
+  ])(
+    'builds a $name leaf whose pattern and schema agree',
+    ({ described, schema, ok, bad }) => {
+      expect(described.schema).toStrictEqual(schema);
+      expect(matches(ok, described.pattern)).toBe(true);
+      expect(matches(bad, described.pattern)).toBe(false);
+    },
+  );
+
+  it('builds an arrayOf leaf', () => {
+    const described = S.arrayOf(S.number(), 'the summands');
+    expect(described.schema).toStrictEqual({
+      type: 'array',
+      items: { type: 'number' },
+      description: 'the summands',
+    });
+    expect(matches([1, 2, 3], described.pattern)).toBe(true);
+    expect(matches(['a'], described.pattern)).toBe(false);
+  });
+
+  it('builds an open record leaf that allows any keys', () => {
+    const described = S.record('attachments');
+    expect(described.schema).toStrictEqual({
+      type: 'object',
+      properties: {},
+      additionalProperties: true,
+      description: 'attachments',
+    });
+    expect(matches({ anything: 1, goes: 'here' }, described.pattern)).toBe(
+      true,
+    );
+    expect(matches(42, described.pattern)).toBe(false);
+  });
+
+  it('builds a closed object leaf with required and optional properties', () => {
+    const described = S.object(
+      { id: S.string(), label: S.string() },
+      { optional: ['label'] },
+    );
+    expect(described.schema).toStrictEqual({
+      type: 'object',
+      properties: { id: { type: 'string' }, label: { type: 'string' } },
+      required: ['id'],
+      additionalProperties: false,
+    });
+    expect(matches({ id: 'x' }, described.pattern)).toBe(true);
+    expect(matches({ id: 'x', label: 'y' }, described.pattern)).toBe(true);
+    expect(matches({ label: 'y' }, described.pattern)).toBe(false);
+  });
+
+  it('rejects extra keys on a closed object leaf', () => {
+    const described = S.object({ id: S.string() });
+    expect(matches({ id: 'x' }, described.pattern)).toBe(true);
+    expect(matches({ id: 'x', extra: 1 }, described.pattern)).toBe(false);
+  });
+
+  it('builds a void return leaf with no schema', () => {
+    const described = S.nothing();
+    expect(described.schema).toBeUndefined();
+    expect(matches(undefined, described.pattern)).toBe(true);
+    expect(matches('something', described.pattern)).toBe(false);
+  });
+});
+
+describe('S.method', () => {
+  it('builds a guard and schema from named args', () => {
+    const method = S.method(
+      'Add a list of numbers.',
+      [S.arg('summands', S.arrayOf(S.number()))],
+      S.number('The sum of the numbers.'),
+    );
+    expect(method.schema).toStrictEqual({
+      description: 'Add a list of numbers.',
+      args: { summands: { type: 'array', items: { type: 'number' } } },
+      required: ['summands'],
+      returns: { type: 'number', description: 'The sum of the numbers.' },
+    });
+    const payload = payloadOf(method.guard);
+    expect(payload.argGuards).toHaveLength(1);
+    expect(payload.optionalArgGuards ?? []).toHaveLength(0);
+  });
+
+  it('omits `returns` from the schema for a void method', () => {
+    const method = S.method(
+      'Return a final response.',
+      [S.arg('final', S.string())],
+      S.nothing(),
+    );
+    expect(method.schema.returns).toBeUndefined();
+    expect('returns' in method.schema).toBe(false);
+  });
+
+  it('places optional args in the guard as trailing optionals', () => {
+    const method = S.method(
+      'Return a final response.',
+      [
+        S.arg('final', S.string()),
+        S.arg('attachments', S.record(), { optional: true }),
+      ],
+      S.nothing(),
+    );
+    const payload = payloadOf(method.guard);
+    expect(payload.argGuards).toHaveLength(1);
+    expect(payload.optionalArgGuards).toHaveLength(1);
+    expect(method.schema.args).toStrictEqual({
+      final: { type: 'string' },
+      attachments: {
+        type: 'object',
+        properties: {},
+        additionalProperties: true,
+      },
+    });
+    // The optional arg is omitted from `required`, so the schema's enforced
+    // shape matches the guard's optional trailing arg.
+    expect(method.schema.required).toStrictEqual(['final']);
+  });
+
+  it('handles a no-arg method', () => {
+    const method = S.method('Get the moon phase.', [], S.string());
+    expect(method.schema.args).toStrictEqual({});
+    expect(payloadOf(method.guard).argGuards).toHaveLength(0);
+  });
+
+  it('throws when an optional argument precedes a required one', () => {
+    expect(() =>
+      S.method(
+        'bad',
+        [S.arg('a', S.string(), { optional: true }), S.arg('b', S.string())],
+        S.nothing(),
+      ),
+    ).toThrow(/optional arguments must be trailing/u);
+  });
+});
+
+describe('S.interface', () => {
+  it('collects method guards and schemas, defaulting unlisted methods to passable', () => {
+    const { interfaceGuard, schemas } = S.interface('Math', {
+      add: S.method(
+        'Add a list of numbers.',
+        [S.arg('summands', S.arrayOf(S.number()))],
+        S.number('The sum of the numbers.'),
+      ),
+      count: S.method(
+        'Count characters.',
+        [S.arg('word', S.string('The string to measure.'))],
+        S.number(),
+      ),
+    });
+
+    expect(Object.keys(schemas)).toStrictEqual(['add', 'count']);
+    const payload = getInterfaceGuardPayload(interfaceGuard) as unknown as {
+      interfaceName: string;
+      methodGuards: Record<string, unknown>;
+      defaultGuards?: string;
+    };
+    expect(payload.interfaceName).toBe('Math');
+    expect(Object.keys(payload.methodGuards)).toStrictEqual(['add', 'count']);
+    expect(payload.defaultGuards).toBe('passable');
+  });
+});