fix(kernel-utils): make described combinators' schema faithful to their guards

Resolve two review findings on the described() combinators:

- S.object is documented as a closed/shaped object but M.splitRecord defaults
  its rest pattern to M.any(), so neither the pattern nor the schema rejected
  extra keys. Close both: pass an empty-record rest pattern and emit
  additionalProperties: false (which routes jsonSchemaToStruct through its
  strict branch).

- S.method emits optional trailing args via M.callWhen(...).optional(...), but
  MethodSchema could not express optionality, so methodArgsToStruct and
  method-schema-convert treated every arg as required. Add an optional
  `required` field to MethodSchema (mirroring object JsonSchema's `required`),
  populate it from S.method, honor it in methodArgsToStruct via a `{ required }`
  option, and map it to ValueSpec.optional in method-schema-convert.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grypez

packages/kernel-utils/CHANGELOG.md

@@ -10,6 +10,7 @@ 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/src/described.test.ts

@@ -82,12 +82,19 @@ describe('leaves', () => {
       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();
@@ -106,6 +113,7 @@ describe('S.method', () => {
     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);
@@ -143,6 +151,9 @@ describe('S.method', () => {
         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', () => {

packages/kernel-utils/src/described.ts

@@ -135,9 +135,10 @@ const record = (description?: string): Described =>
   });
 
 /**
- * A closed/shaped object leaf: matches a record with the given properties,
- * where keys not listed in `optional` are required. Describes
- * `{ type: 'object', properties, required }`.
+ * A closed/shaped object leaf: matches a record with exactly the given
+ * properties (extra keys are rejected), where keys not listed in `optional` are
+ * required. Describes `{ type: 'object', properties, required,
+ * additionalProperties: false }`.
  *
  * @param properties - The described properties, keyed by name.
  * @param options - Options bag.
@@ -165,9 +166,16 @@ const object = (
     }
   }
   return harden({
-    pattern: M.splitRecord(requiredPatterns, optionalPatterns),
+    // The empty-record rest pattern closes the record: keys beyond those listed
+    // are rejected, matching the schema's `additionalProperties: false`.
+    pattern: M.splitRecord(requiredPatterns, optionalPatterns, {}),
     schema: withDescription(
-      { type: 'object', properties: schemaProperties, required },
+      {
+        type: 'object',
+        properties: schemaProperties,
+        required,
+        additionalProperties: false,
+      },
       description,
     ),
   });
@@ -242,6 +250,7 @@ const describedMethod = (
   const schema: MethodSchema = {
     description,
     args: schemaArgs,
+    required: required.map((each) => each.name),
     ...(returns.schema === undefined ? {} : { returns: returns.schema }),
   };
 

packages/kernel-utils/src/json-schema-to-struct.test.ts

@@ -63,6 +63,19 @@ describe('methodArgsToStruct', () => {
     expect(() => assert({ a: 1 }, struct)).toThrow(/path: b/u);
   });
 
+  it('treats args absent from `required` as optional', () => {
+    const struct = methodArgsToStruct(
+      {
+        final: { type: 'string' },
+        attachments: { type: 'object', properties: {} },
+      },
+      { required: ['final'] },
+    );
+    assert({ final: 'done' }, struct);
+    assert({ final: 'done', attachments: { note: 1 } }, struct);
+    expect(() => assert({ attachments: {} }, struct)).toThrow(/final/u);
+  });
+
   it('accepts an empty args map', () => {
     assert({}, methodArgsToStruct({}));
   });

packages/kernel-utils/src/json-schema-to-struct.ts

@@ -96,13 +96,19 @@ export function jsonSchemaToStruct(schema: JsonSchema): Struct<unknown> {
 
 /**
  * Build a Superstruct object struct for a method/capability `args` map
- * (name → per-argument {@link JsonSchema}). All listed arguments are required.
+ * (name → per-argument {@link JsonSchema}). Arguments not named in
+ * `options.required` are validated as optional; an absent `options.required`
+ * treats every argument as required.
  *
  * @param args - Same shape as {@link MethodSchema.args}.
+ * @param options - Options bag.
+ * @param options.required - Names of the required arguments. Mirrors
+ * {@link MethodSchema.required}; absent means all arguments are required.
  * @returns A struct that validates a plain object with one field per declared argument.
  */
 export function methodArgsToStruct(
   args: Record<string, JsonSchema>,
+  options: { required?: string[] } = {},
 ): Struct<Record<string, unknown>> {
   const entries = Object.entries(args);
   if (entries.length === 0) {
@@ -113,8 +119,12 @@ export function methodArgsToStruct(
       return true;
     }) as Struct<Record<string, unknown>>;
   }
+  const required = new Set(options.required ?? Object.keys(args));
   const shape = Object.fromEntries(
-    entries.map(([name, jsonSchema]) => [name, jsonSchemaToStruct(jsonSchema)]),
+    entries.map(([name, jsonSchema]) => {
+      const fieldStruct = jsonSchemaToStruct(jsonSchema);
+      return [name, required.has(name) ? fieldStruct : optional(fieldStruct)];
+    }),
   );
   return object(shape) as Struct<Record<string, unknown>>;
 }

packages/kernel-utils/src/schema.ts

@@ -50,6 +50,12 @@ export type MethodSchema = {
    * Each argument includes its type and description.
    */
   args: Record<string, JsonSchema>;
+  /**
+   * Names of the required arguments. Mirrors {@link ObjectJsonSchema.required}:
+   * an argument not listed here may be omitted by the caller, and an absent
+   * `required` means every argument in `args` is required.
+   */
+  required?: string[];
   /**
    * Return value schema, including type and description.
    */

packages/service-discovery-types/src/index.test.ts

@@ -228,6 +228,30 @@ describe('methodSchemaToMethodSpec', () => {
     });
   });
 
+  it('marks args absent from `required` as optional parameters', () => {
+    const spec: MethodSpec = methodSchemaToMethodSpec({
+      description: 'send a message',
+      args: {
+        text: { type: 'string' },
+        attachments: { type: 'object', properties: {} },
+      },
+      required: ['text'],
+      returns: { type: 'string' },
+    });
+    expect(spec).toStrictEqual({
+      description: 'send a message',
+      parameters: [
+        { description: 'text', type: { kind: 'string' } },
+        {
+          description: 'attachments',
+          type: { kind: 'object', spec: { properties: {} } },
+          optional: true,
+        },
+      ],
+      returnType: { kind: 'string' },
+    });
+  });
+
   it('defaults returnType to void when unspecified', () => {
     expect(
       methodSchemaToMethodSpec({ description: 'do a thing', args: {} }),

packages/service-discovery-types/src/method-schema-convert.ts

@@ -11,8 +11,6 @@
  *   use the iteration order of the args record, and we drop the names. The
  *   names are preserved as `ValueSpec.description` if no description was
  *   otherwise present, so they remain human-readable.
- * - `MethodSchema` does not mark individual args as optional; the converter
- *   treats all parameters as required.
  * - `JsonSchema` has no notion of `remotable`, `null`, `void`, `bigint`,
  *   `unknown`, or `union`. The converter never emits those kinds.
  */
@@ -94,17 +92,24 @@ export function jsonSchemaToObjectSpec(
  * Because `MethodSchema.args` is a named record while `MethodSpec.parameters`
  * is a positional array, the parameters are emitted in the iteration order of
  * the args record, and each parameter's name is preserved in its
- * `description` field when the source did not supply one.
+ * `description` field when the source did not supply one. An argument absent
+ * from `schema.required` becomes an optional parameter; an absent `required`
+ * treats every parameter as required.
  *
  * @param schema - The source MethodSchema.
  * @returns The equivalent MethodSpec.
  */
 export function methodSchemaToMethodSpec(schema: MethodSchema): MethodSpec {
+  const required = new Set(schema.required ?? Object.keys(schema.args));
   const parameters: ValueSpec[] = [];
   for (const [name, argSchema] of Object.entries(schema.args)) {
     const type = jsonSchemaToTypeSpec(argSchema);
     const description = argSchema.description ?? name;
-    parameters.push({ description, type });
+    const parameter: ValueSpec = { description, type };
+    if (!required.has(name)) {
+      parameter.optional = true;
+    }
+    parameters.push(parameter);
   }
   const returnType: TypeSpec = schema.returns
     ? jsonSchemaToTypeSpec(schema.returns)