feat(kernel-utils): metadata as polynomials of invocation data

Add MetaDataSpec<M> discriminated union (constant | source | callable) so
that sheaf metadata can vary with call arguments rather than being static.

- constant(v)   — static value, evaluated once
- source(s)     — JS source string compiled via Compartment at sheafify
                  construction time, called at dispatch time
- callable(fn)  — live function called at dispatch time

PresheafSection.metadata changes from M to MetaDataSpec<M> (breaking).
A new EvaluatedSection<M> type carries post-evaluation metadata and is
what Lift receives as its germs array.  EvaluatedSection is distinct from
PresheafSection because the "germ" in the sheaf-theoretic sense only
exists after quotienting by the metadata-equivalence relation (the
collapseEquivalent step); EvaluatedSection describes the pre-collapse
stage where the spec has been applied to the invocation args.

getStalk is generalised to <T extends { exo: Section }> so it works over
ResolvedSection (the internal post-resolution type) without a cast.

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

Author: grypez

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

@@ -12,7 +12,9 @@ describe('index', () => {
       'GET_DESCRIPTION',
       'abortableDelay',
       'calculateReconnectionBackoff',
+      'callable',
       'collectSheafGuard',
+      'constant',
       'delay',
       'fetchValidatedJson',
       'fromHex',
@@ -34,6 +36,7 @@ describe('index', () => {
       'retry',
       'retryWithBackoff',
       'sheafify',
+      'source',
       'stringify',
       'toHex',
       'waitUntilQuiescent',

packages/kernel-utils/src/index.ts

@@ -40,11 +40,14 @@ export type { RetryBackoffOptions, RetryOnRetryInfo } from './retry.ts';
 export type {
   Section,
   PresheafSection,
+  EvaluatedSection,
+  MetaDataSpec,
   Lift,
   LiftContext,
   Presheaf,
   Sheaf,
 } from './sheaf/types.ts';
+export { constant, source, callable } from './sheaf/metadata.ts';
 export { sheafify } from './sheaf/sheafify.ts';
 export { collectSheafGuard } from './sheaf/guard.ts';
 export { getStalk, guardCoversPoint } from './sheaf/stalk.ts';

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

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import {
+  callable,
+  constant,
+  evaluateMetadata,
+  resolveMetaDataSpec,
+  source,
+} from './metadata.ts';
+
+describe('constant', () => {
+  it('returns a constant spec with the given value', () => {
+    expect(constant(42)).toStrictEqual({ kind: 'constant', value: 42 });
+  });
+
+  it('evaluateMetadata returns the value regardless of args', () => {
+    const spec = resolveMetaDataSpec(constant({ cost: 7 }));
+    expect(evaluateMetadata(spec, [])).toStrictEqual({ cost: 7 });
+    expect(evaluateMetadata(spec, [1, 2, 3])).toStrictEqual({ cost: 7 });
+  });
+});
+
+describe('callable', () => {
+  it('returns a callable spec wrapping the function', () => {
+    const fn = (args: unknown[]) => 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 spec = resolveMetaDataSpec(callable(fn));
+    expect(evaluateMetadata(spec, [5])).toBe(10);
+    expect(fn).toHaveBeenCalledWith([5]);
+  });
+});
+
+describe('source', () => {
+  it('returns a source spec with the src string', () => {
+    expect(source('(args) => args[0]')).toStrictEqual({
+      kind: 'source',
+      src: '(args) => args[0]',
+    });
+  });
+
+  it('resolveMetaDataSpec compiles source to callable via compartment', () => {
+    const mockFn = (args: unknown[]) => args[0] as number;
+    const compartment = { evaluate: vi.fn(() => mockFn) };
+    const spec = resolveMetaDataSpec(source('(args) => args[0]'), compartment);
+    expect(spec.kind).toBe('callable');
+    expect(compartment.evaluate).toHaveBeenCalledWith('(args) => args[0]');
+    expect(evaluateMetadata(spec, [99])).toBe(99);
+  });
+});
+
+describe('resolveMetaDataSpec', () => {
+  it('passes constant spec through unchanged', () => {
+    const spec = constant(42);
+    expect(resolveMetaDataSpec(spec)).toStrictEqual(spec);
+  });
+
+  it('passes callable spec through unchanged', () => {
+    const fn = (_args: unknown[]) => 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(
+      "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();
+  });
+});

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

@@ -0,0 +1,85 @@
+/**
+ * MetaDataSpec constructors and evaluation helpers.
+ */
+
+import type { MetaDataSpec } from './types.ts';
+
+/** Resolved spec: 'source' has been compiled away; only constant or callable remain. */
+export type ResolvedMetaDataSpec<M> =
+  | { kind: 'constant'; value: M }
+  | { kind: 'callable'; fn: (args: unknown[]) => M };
+
+/**
+ * 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 });
+
+/**
+ * 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 });
+
+/**
+ * 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.
+ */
+export const callable = <M>(fn: (args: unknown[]) => M): MetaDataSpec<M> =>
+  harden({ kind: 'callable', fn });
+
+/**
+ * Compile a 'source' spec to 'callable' using the supplied compartment.
+ * 'constant' and 'callable' pass through unchanged.
+ *
+ * @param spec - The MetaDataSpec to resolve.
+ * @param compartment - Compartment used to evaluate 'source' specs. Required when spec is 'source'.
+ * @param compartment.evaluate - Evaluate a JS source string and return the result.
+ * @returns A ResolvedMetaDataSpec with no 'source' variant.
+ */
+export const resolveMetaDataSpec = <M>(
+  spec: MetaDataSpec<M>,
+  compartment?: { evaluate: (src: string) => unknown },
+): ResolvedMetaDataSpec<M> => {
+  if (spec.kind === 'source') {
+    if (!compartment) {
+      throw new Error(
+        `sheafify: compartment required to evaluate 'source' metadata`,
+      );
+    }
+    return {
+      kind: 'callable',
+      fn: compartment.evaluate(spec.src) as (args: unknown[]) => M,
+    };
+  }
+  return spec;
+};
+
+/**
+ * Evaluate a resolved metadata spec against the invocation args.
+ * Returns undefined if spec is undefined (no metadata on the section).
+ *
+ * @param spec - The resolved spec to evaluate, or undefined.
+ * @param args - The invocation arguments.
+ * @returns The evaluated metadata value, or undefined.
+ */
+export const evaluateMetadata = <M>(
+  spec: ResolvedMetaDataSpec<M> | undefined,
+  args: unknown[],
+): M | undefined => {
+  if (spec === undefined) {
+    return undefined;
+  }
+  if (spec.kind === 'constant') {
+    return spec.value;
+  }
+  return spec.fn(args);
+};