feat(kernel-utils): treat {} as empty sheaf metadata

- evaluateMetadata returns a plain object; missing spec and nullish raw → {}
- reject primitives, arrays, and non-plain objects; hint { value: myValue }
- require EvaluatedSection.metadata; MetaData extends Record<string, unknown>
- simplify metadataKey and decomposeMetadata; drop ifDefined in dispatch

Made-with: Cursor

Author: grypez

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

@@ -10,7 +10,10 @@ import {
 
 describe('constant', () => {
   it('returns a constant spec with the given value', () => {
-    expect(constant(42)).toStrictEqual({ kind: 'constant', value: 42 });
+    expect(constant({ n: 42 })).toStrictEqual({
+      kind: 'constant',
+      value: { n: 42 },
+    });
   });
 
   it('evaluateMetadata returns the value regardless of args', () => {
@@ -22,59 +25,109 @@ describe('constant', () => {
 
 describe('callable', () => {
   it('returns a callable spec wrapping the function', () => {
-    const fn = (args: unknown[]) => args[0] as number;
+    const fn = (args: unknown[]) => ({ out: args[0] as number });
     const spec = callable(fn);
     expect(spec).toStrictEqual({ kind: 'callable', fn });
   });
 
   it('evaluateMetadata calls fn with args', () => {
-    const fn = vi.fn((args: unknown[]) => (args[0] as number) * 2);
+    const fn = vi.fn((args: unknown[]) => ({
+      value: (args[0] as number) * 2,
+    }));
     const spec = resolveMetaDataSpec(callable(fn));
-    expect(evaluateMetadata(spec, [5])).toBe(10);
+    expect(evaluateMetadata(spec, [5])).toStrictEqual({ value: 10 });
     expect(fn).toHaveBeenCalledWith([5]);
   });
 });
 
 describe('source', () => {
   it('returns a source spec with the src string', () => {
-    expect(source('(args) => args[0]')).toStrictEqual({
+    expect(source('(args) => ({ x: args[0] })')).toStrictEqual({
       kind: 'source',
-      src: '(args) => args[0]',
+      src: '(args) => ({ x: args[0] })',
     });
   });
 
   it('resolveMetaDataSpec compiles source to callable via compartment', () => {
-    const mockFn = (args: unknown[]) => args[0] as number;
+    const mockFn = (args: unknown[]) => ({ value: args[0] as number });
     const compartment = { evaluate: vi.fn(() => mockFn) };
-    const spec = resolveMetaDataSpec(source('(args) => args[0]'), compartment);
+    const spec = resolveMetaDataSpec(
+      source<{ value: number }>('(args) => ({ value: args[0] })'),
+      compartment,
+    );
     expect(spec.kind).toBe('callable');
-    expect(compartment.evaluate).toHaveBeenCalledWith('(args) => args[0]');
-    expect(evaluateMetadata(spec, [99])).toBe(99);
+    expect(compartment.evaluate).toHaveBeenCalledWith(
+      '(args) => ({ value: args[0] })',
+    );
+    expect(evaluateMetadata(spec, [99])).toStrictEqual({ value: 99 });
   });
 });
 
 describe('resolveMetaDataSpec', () => {
   it('passes constant spec through unchanged', () => {
-    const spec = constant(42);
+    const spec = constant({ answer: 42 });
     expect(resolveMetaDataSpec(spec)).toStrictEqual(spec);
   });
 
   it('passes callable spec through unchanged', () => {
-    const fn = (_args: unknown[]) => 0;
+    const fn = (_args: unknown[]) => ({ count: 0 });
     const spec = callable(fn);
     expect(resolveMetaDataSpec(spec)).toStrictEqual(spec);
   });
 
   it("throws if kind is 'source' and no compartment supplied", () => {
-    expect(() => resolveMetaDataSpec(source('() => 0'))).toThrow(
+    expect(() => resolveMetaDataSpec(source('() => ({})'))).toThrow(
       "compartment required to evaluate 'source' metadata",
     );
   });
 });
 
 describe('evaluateMetadata', () => {
-  it('returns undefined when spec is undefined', () => {
-    expect(evaluateMetadata(undefined, [])).toBeUndefined();
-    expect(evaluateMetadata(undefined, [1, 2])).toBeUndefined();
+  it('returns empty object when spec is undefined', () => {
+    expect(evaluateMetadata(undefined, [])).toStrictEqual({});
+    expect(evaluateMetadata(undefined, [1, 2])).toStrictEqual({});
+  });
+
+  it('normalizes null from callable to empty object', () => {
+    const spec = resolveMetaDataSpec(
+      callable(
+        ((_args: unknown[]) => null) as unknown as (
+          args: unknown[],
+        ) => Record<string, unknown>,
+      ),
+    );
+    expect(evaluateMetadata(spec, [])).toStrictEqual({});
+  });
+
+  it('throws when callable returns a primitive', () => {
+    const spec = resolveMetaDataSpec(
+      callable(
+        ((_args: unknown[]) => 7) as unknown as (
+          args: unknown[],
+        ) => Record<string, unknown>,
+      ),
+    );
+    expect(() => evaluateMetadata(spec, [])).toThrow(/cannot be a primitive/u);
+    expect(() => evaluateMetadata(spec, [])).toThrow(/value: myValue/u);
+  });
+
+  it('throws when callable returns an array', () => {
+    const spec = resolveMetaDataSpec(
+      callable(((_args: unknown[]) => [1, 2]) as unknown as (
+        args: unknown[],
+      ) => Record<string, unknown>),
+    );
+    expect(() => evaluateMetadata(spec, [])).toThrow(/cannot be an array/u);
+  });
+
+  it('throws when callable returns a Date', () => {
+    const spec = resolveMetaDataSpec(
+      callable(
+        ((_args: unknown[]) => new Date()) as unknown as (
+          args: unknown[],
+        ) => Record<string, unknown>,
+      ),
+    );
+    expect(() => evaluateMetadata(spec, [])).toThrow(/must be a plain object/u);
   });
 });

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

@@ -5,36 +5,77 @@
 import type { MetaDataSpec } from './types.ts';
 
 /** Resolved spec: 'source' has been compiled away; only constant or callable remain. */
-export type ResolvedMetaDataSpec<M> =
+export type ResolvedMetaDataSpec<M extends Record<string, unknown>> =
   | { kind: 'constant'; value: M }
   | { kind: 'callable'; fn: (args: unknown[]) => M };
 
+const metadataPlainObjectHint =
+  'Sheaf metadata must be a plain object; use e.g. { value: myValue } if you need to attach a primitive.';
+
+const isPlainObjectRecord = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+};
+
+/**
+ * Normalize evaluated metadata: empty sentinel is `{}`; invalid shapes throw.
+ *
+ * @param raw - Result from constant value or callable, before validation.
+ * @returns A plain object suitable for stalk metadata.
+ */
+const normalizeEvaluatedSheafMetadata = (
+  raw: unknown,
+): Record<string, unknown> => {
+  if (raw === undefined || raw === null) {
+    return {};
+  }
+  if (typeof raw !== 'object') {
+    throw new Error(
+      `sheafify: metadata cannot be a primitive (${typeof raw}). ${metadataPlainObjectHint}`,
+    );
+  }
+  if (Array.isArray(raw)) {
+    throw new Error(
+      `sheafify: metadata cannot be an array. ${metadataPlainObjectHint}`,
+    );
+  }
+  if (!isPlainObjectRecord(raw)) {
+    throw new Error(
+      `sheafify: metadata must be a plain object. ${metadataPlainObjectHint}`,
+    );
+  }
+  return raw as Record<string, unknown>;
+};
+
 /**
  * Wrap a static value as a constant metadata spec.
  *
  * @param value - The static metadata value.
  * @returns A constant MetaDataSpec wrapping the value.
  */
-export const constant = <M>(value: M): MetaDataSpec<M> =>
-  harden({ kind: 'constant', value });
+export const constant = <M extends Record<string, unknown>>(
+  value: M,
+): MetaDataSpec<M> => harden({ kind: 'constant', value });
 
 /**
  * Wrap JS function source. Evaluated in a Compartment at sheafify construction time.
  *
  * @param src - JS source string of the form `(args) => M`.
  * @returns A source MetaDataSpec wrapping the source string.
  */
-export const source = <M>(src: string): MetaDataSpec<M> =>
-  harden({ kind: 'source', src });
+export const source = <M extends Record<string, unknown>>(
+  src: string,
+): MetaDataSpec<M> => harden({ kind: 'source', src });
 
 /**
  * Wrap a live function as a callable metadata spec.
  *
  * @param fn - Function from invocation args to metadata value.
- * @returns A callable MetaDataSpec wrapping the function.
+ * @returns A callable metadata spec.
  */
-export const callable = <M>(fn: (args: unknown[]) => M): MetaDataSpec<M> =>
-  harden({ kind: 'callable', fn });
+export const callable = <M extends Record<string, unknown>>(
+  fn: (args: unknown[]) => M,
+): MetaDataSpec<M> => harden({ kind: 'callable', fn });
 
 /**
  * Compile a 'source' spec to 'callable' using the supplied compartment.
@@ -45,7 +86,7 @@ export const callable = <M>(fn: (args: unknown[]) => M): MetaDataSpec<M> =>
  * @param compartment.evaluate - Evaluate a JS source string and return the result.
  * @returns A ResolvedMetaDataSpec with no 'source' variant.
  */
-export const resolveMetaDataSpec = <M>(
+export const resolveMetaDataSpec = <M extends Record<string, unknown>>(
   spec: MetaDataSpec<M>,
   compartment?: { evaluate: (src: string) => unknown },
 ): ResolvedMetaDataSpec<M> => {
@@ -65,21 +106,22 @@ export const resolveMetaDataSpec = <M>(
 
 /**
  * Evaluate a resolved metadata spec against the invocation args.
- * Returns undefined if spec is undefined (no metadata on the section).
+ *
+ * Missing spec yields `{}` (no metadata). Callable/constant results must be plain objects;
+ * `undefined`/`null` from the producer normalize to `{}`. Primitives, arrays, and non-plain
+ * objects throw with guidance to use an explicit record such as `{ value: myValue }`.
  *
  * @param spec - The resolved spec to evaluate, or undefined.
  * @param args - The invocation arguments.
- * @returns The evaluated metadata value, or undefined.
+ * @returns The evaluated metadata object (possibly empty).
  */
-export const evaluateMetadata = <M>(
-  spec: ResolvedMetaDataSpec<M> | undefined,
+export const evaluateMetadata = <MetaData extends Record<string, unknown>>(
+  spec: ResolvedMetaDataSpec<MetaData> | undefined,
   args: unknown[],
-): M | undefined => {
+): MetaData => {
   if (spec === undefined) {
-    return undefined;
-  }
-  if (spec.kind === 'constant') {
-    return spec.value;
+    return {} as MetaData;
   }
-  return spec.fn(args);
+  const raw = spec.kind === 'constant' ? spec.value : spec.fn(args);
+  return normalizeEvaluatedSheafMetadata(raw) as MetaData;
 };

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

@@ -448,6 +448,43 @@ describe('sheafify', () => {
     expect(liftCalled).toBe(false);
   });
 
+  it('collapses no-metadata and empty-object metadata as equivalent', async () => {
+    type Meta = Record<string, never>;
+    let liftCalled = false;
+
+    const sections: PresheafSection<Meta>[] = [
+      {
+        exo: makeExo(
+          'Wallet:0',
+          M.interface('Wallet:0', {
+            getBalance: M.call(M.string()).returns(M.number()),
+          }),
+          { getBalance: (_acct: string) => 100 },
+        ) as unknown as Section,
+      },
+      {
+        exo: makeExo(
+          'Wallet:1',
+          M.interface('Wallet:1', {
+            getBalance: M.call(M.string()).returns(M.number()),
+          }),
+          { getBalance: (_acct: string) => 42 },
+        ) as unknown as Section,
+        metadata: constant({}),
+      },
+    ];
+
+    const wallet = sheafify({ name: 'Wallet', sections }).getGlobalSection({
+      lift: async (_germs) => {
+        liftCalled = true;
+        return Promise.resolve(0);
+      },
+    });
+    await E(wallet).getBalance('alice');
+
+    expect(liftCalled).toBe(false);
+  });
+
   it('mixed sections participate in lift', async () => {
     const argmin: Lift<{ cost: number }> = async (germs) =>
       Promise.resolve(