@ontrails/core 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/trail.js.map

@@ -1 +1 @@
-{"version":3,"file":"trail.js","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AAqGA,MAAM,UAAU,KAAK,CACnB,QAA8D,EAC9D,SAA2B;IAE3B,MAAM,QAAQ,GACZ,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;QACnC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAE1C,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IAElD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,cAAc,EAAE,KAAK,EAAE,KAAQ,EAAE,GAAiB,EAAE,EAAE,CACpD,MAAM,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC;QAClC,IAAI,EAAE,OAAgB;KACvB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AA+GA,MAAM,UAAU,KAAK,CACnB,QAA8D,EAC9D,SAA2B;IAE3B,MAAM,QAAQ,GACZ,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;QACnC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAE1C,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IAE7E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7C,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,MAAM,EAAE,SAAS,IAAI,OAAO;QAC5B,IAAI,EAAE,OAAgB;QACtB,GAAG,EAAE,KAAK,EAAE,KAAQ,EAAE,GAAiB,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC;KAClE,CAAC,CAAC;AACL,CAAC"}

package/dist/type-utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+import type { Result } from './result.js';
+import type { AnyTrail, Trail } from './trail.js';
+/** Extract the input type from a Trail. */
+export type TrailInput<T extends AnyTrail> = T extends Trail<infer I, any> ? I : never;
+/** Extract the output type from a Trail. */
+export type TrailOutput<T extends AnyTrail> = T extends Trail<any, infer O> ? O : never;
+/**
+ * Extracts the full `Result<Output, Error>` type from a trail definition.
+ *
+ * @example
+ * ```typescript
+ * type SearchResult = TrailResult<typeof searchTrail>;
+ * // Result<{ results: Item[]; count: number }, Error>
+ * ```
+ */
+export type TrailResult<T extends AnyTrail> = Result<TrailOutput<T>, Error>;
+/** Get the input Zod schema from a trail, preserving the specific schema type. */
+export declare const inputOf: <T extends AnyTrail>(trail: T) => T["input"];
+/** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */
+export declare const outputOf: <T extends AnyTrail>(trail: T) => T["output"];
+//# sourceMappingURL=type-utils.d.ts.map

package/dist/type-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAQ5E,kFAAkF;AAClF,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,OAAO,CACnD,CAAC;AAEd,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,QAAQ,CACpD,CAAC"}

package/dist/type-utils.js

@@ -0,0 +1,12 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+/* oxlint-enable no-explicit-any */
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+/** Get the input Zod schema from a trail, preserving the specific schema type. */
+export const inputOf = (trail) => trail.input;
+/** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */
+export const outputOf = (trail) => trail.output;
+//# sourceMappingURL=type-utils.js.map

package/dist/type-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8BH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAqB,KAAQ,EAAc,EAAE,CAClE,KAAK,CAAC,KAAK,CAAC;AAEd,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAqB,KAAQ,EAAe,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC"}

package/dist/types.d.ts

@@ -40,7 +40,6 @@ export interface TrailContext {
     readonly progress?: ProgressCallback | undefined;
     readonly cwd?: string | undefined;
     readonly env?: Record<string, string | undefined> | undefined;
-    readonly [key: string]: unknown;
+    readonly extensions?: Readonly<Record<string, unknown>> | undefined;
 }
-export type Surface = 'cli' | 'mcp' | 'http' | 'ws';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validate-topo.d.ts

@@ -1,7 +1,7 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks hike follows references, example input validity, event origin
+ * Checks trail follow references, example input validity, event origin
  * references, and output schema completeness. Returns a Result with all
  * issues collected into a single ValidationError.
  */
@@ -16,7 +16,7 @@ export interface TopoIssue {
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follows references, example inputs, event origins, and output
+ * Checks follow references, example inputs, event origins, and output
  * schema presence. Returns `Result.ok()` when no issues are found, or
  * `Result.err(ValidationError)` with all issues in the error context.
  */

package/dist/validate-topo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-topo.d.ts","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAoGD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAmBrE,CAAC"}
+{"version":3,"file":"validate-topo.d.ts","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiKD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAmBrE,CAAC"}

package/dist/validate-topo.js

@@ -1,7 +1,7 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks hike follows references, example input validity, event origin
+ * Checks trail follow references, example input validity, event origin
  * references, and output schema completeness. Returns a Result with all
  * issues collected into a single ValidationError.
  */
@@ -11,13 +11,62 @@ import { validateInput } from './validation.js';
 // ---------------------------------------------------------------------------
 // Validators
 // ---------------------------------------------------------------------------
-const checkFollows = (hikes, topo) => {
+const WHITE = 0;
+const GRAY = 1;
+const BLACK = 2;
+/** Build an adjacency list and initial color map from trails with follow. */
+const buildFollowGraph = (trails) => {
+    const graph = new Map();
+    for (const [id, t] of trails) {
+        if (t.follow.length > 0) {
+            graph.set(id, t.follow);
+        }
+    }
+    const color = new Map();
+    for (const id of graph.keys()) {
+        color.set(id, WHITE);
+    }
+    return { color, graph };
+};
+/** Detect multi-node cycles in the trail follow graph via DFS. */
+const detectFollowCycles = (trails) => {
+    const issues = [];
+    const { color, graph } = buildFollowGraph(trails);
+    const dfs = (node, path) => {
+        color.set(node, GRAY);
+        for (const next of graph.get(node) ?? []) {
+            if (!graph.has(next)) {
+                continue;
+            }
+            const c = color.get(next) ?? WHITE;
+            if (c === GRAY) {
+                const cycle = [...path.slice(path.indexOf(next)), next];
+                issues.push({
+                    message: `Cycle detected: ${cycle.join(' → ')}`,
+                    rule: 'follow-cycle',
+                    trailId: next,
+                });
+            }
+            else if (c === WHITE) {
+                dfs(next, [...path, next]);
+            }
+        }
+        color.set(node, BLACK);
+    };
+    for (const id of graph.keys()) {
+        if (color.get(id) === WHITE) {
+            dfs(id, [id]);
+        }
+    }
+    return issues;
+};
+const checkFollows = (trails, topo) => {
     const issues = [];
-    for (const [id, hike] of hikes) {
-        for (const followId of hike.follows) {
+    for (const [id, trail] of trails) {
+        for (const followId of trail.follow) {
             if (followId === id) {
                 issues.push({
-                    message: `Hike follows itself`,
+                    message: `Trail follows itself`,
                     rule: 'no-self-follow',
                     trailId: id,
                 });
@@ -25,18 +74,19 @@ const checkFollows = (hikes, topo) => {
             else if (!topo.has(followId)) {
                 issues.push({
                     message: `Follows "${followId}" which is not in the topo`,
-                    rule: 'follows-exist',
+                    rule: 'follow-exists',
                     trailId: id,
                 });
             }
         }
     }
+    issues.push(...detectFollowCycles(trails));
     return issues;
 };
 const checkOneExample = (id, example, inputSchema, hasOutput) => {
     const issues = [];
     const result = validateInput(inputSchema, example.input);
-    if (result.isErr() && example.error === undefined) {
+    if (result.isErr() && example.error !== 'ValidationError') {
         issues.push({
             message: `Example "${example.name}" input does not parse against schema`,
             rule: 'example-input-valid',
@@ -88,13 +138,13 @@ const checkEventOrigins = (events, topo) => {
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follows references, example inputs, event origins, and output
+ * Checks follow references, example inputs, event origins, and output
  * schema presence. Returns `Result.ok()` when no issues are found, or
  * `Result.err(ValidationError)` with all issues in the error context.
  */
 export const validateTopo = (topo) => {
     const issues = [
-        ...checkFollows(topo.hikes, topo),
+        ...checkFollows(topo.trails, topo),
         ...checkExamples(topo.trails),
         ...checkEventOrigins(topo.events, topo),
     ];

package/dist/validate-topo.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.10",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -16,6 +16,6 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "zod": "catalog:"
+    "zod": "^4.3.5"
   }
 }

package/src/__tests__/context.test.ts

@@ -48,14 +48,13 @@ describe('createTrailContext', () => {
     expect(ctx.workspaceRoot).toBe('/tmp');
   });
 
-  test('TrailContext is extensible with custom fields', () => {
+  test('TrailContext supports extensions for custom fields', () => {
     const ctx: TrailContext = createTrailContext({
-      customField: 42,
-      nested: { key: 'value' },
+      extensions: { customField: 42, nested: { key: 'value' } },
     });
 
-    expect(ctx['customField']).toBe(42);
-    expect(ctx['nested']).toEqual({ key: 'value' });
+    expect(ctx.extensions?.['customField']).toBe(42);
+    expect(ctx.extensions?.['nested']).toEqual({ key: 'value' });
   });
 
   test('each call generates a unique requestId', () => {

package/src/__tests__/derive.test.ts

@@ -77,6 +77,50 @@ describe('derive', () => {
     });
   });
 
+  describe('array types', () => {
+    test('z.array(z.string()) derives string[] field', () => {
+      const schema = z.object({ names: z.array(z.string()) });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'names',
+        options: undefined,
+        required: true,
+        type: 'string[]',
+      });
+    });
+
+    test('z.array(z.number()) derives number[] field', () => {
+      const schema = z.object({ scores: z.array(z.number()) });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'scores',
+        options: undefined,
+        required: true,
+        type: 'number[]',
+      });
+    });
+
+    test('optional z.array(z.string()) marks not required', () => {
+      const schema = z.object({ tags: z.array(z.string()).optional() });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'tags',
+        required: false,
+        type: 'string[]',
+      });
+    });
+
+    test('z.array(z.string()) with default sets default value', () => {
+      const schema = z.object({
+        items: z.array(z.string()).default(['a', 'b']),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.required).toBe(false);
+      expect(fields[0]?.type).toBe('string[]');
+      expect(fields[0]?.default).toEqual(['a', 'b']);
+    });
+  });
+
   describe('modifiers', () => {
     test('.describe() sets label', () => {
       const schema = z.object({

package/src/__tests__/dispatch.test.ts

@@ -0,0 +1,154 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { dispatch } from '../dispatch';
+import { InternalError, NotFoundError, ValidationError } from '../errors';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { topo } from '../topo';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  input: z.object({ value: z.string() }),
+  output: z.object({ value: z.string() }),
+  run: (input) => Result.ok({ value: input.value }),
+});
+
+const throwingTrail = trail('throws', {
+  input: z.object({}),
+  run: () => {
+    throw new Error('kaboom');
+  },
+});
+
+const testTopo = topo('test', { echoTrail, throwingTrail });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('dispatch', () => {
+  describe('happy path', () => {
+    test('dispatches by ID and returns Result.ok with expected value', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 'hello' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ value: 'hello' });
+    });
+  });
+
+  describe('not found', () => {
+    test('returns NotFoundError for unknown trail ID', async () => {
+      const result = await dispatch(testTopo, 'nonexistent', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(NotFoundError);
+      expect(result.error.message).toContain('nonexistent');
+      expect(result.error.message).toContain('test');
+    });
+  });
+
+  describe('validation', () => {
+    test('returns ValidationError for invalid input', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 42 });
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+
+  describe('layers', () => {
+    test('layer composition works through dispatch', async () => {
+      const log: string[] = [];
+      const layer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            log.push('before');
+            const r = await impl(input, ctx);
+            log.push('after');
+            return r;
+          };
+        },
+      };
+
+      const result = await dispatch(
+        testTopo,
+        'echo',
+        { value: 'x' },
+        { layers: [layer] }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(log).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('context', () => {
+    test('context overrides work through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('ctx-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('ctx-test', { ctxTrail });
+      await dispatch(
+        ctxTopo,
+        'ctx-dispatch-test',
+        {},
+        { ctx: { requestId: 'override-id' } }
+      );
+
+      expect(capturedCtx?.requestId).toBe('override-id');
+    });
+
+    test('createContext factory works through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('factory-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('factory-test', { ctxTrail });
+      const customCtx: TrailContext = {
+        cwd: '/custom',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await dispatch(
+        ctxTopo,
+        'factory-dispatch-test',
+        {},
+        { createContext: () => customCtx }
+      );
+
+      expect(capturedCtx?.requestId).toBe('factory-id');
+      expect(capturedCtx?.cwd).toBe('/custom');
+    });
+  });
+
+  describe('error handling', () => {
+    test('never throws — exceptions become InternalError', async () => {
+      const result = await dispatch(testTopo, 'throws', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toBe('kaboom');
+    });
+  });
+});

package/src/__tests__/event.test.ts

@@ -12,7 +12,7 @@ const payloadSchema = z.object({
 const userAction = event('user.action', {
   description: 'A user performed an action',
   from: ['auth.login', 'auth.signup'],
-  markers: { domain: 'auth', priority: 1 },
+  metadata: { domain: 'auth', priority: 1 },
   payload: payloadSchema,
 });
 
@@ -45,7 +45,7 @@ describe('event() basics', () => {
   });
 });
 
-describe('event() from and markers', () => {
+describe('event() from and metadata', () => {
   test('preserves from', () => {
     expect(userAction.from).toEqual(['auth.login', 'auth.signup']);
   });
@@ -54,8 +54,8 @@ describe('event() from and markers', () => {
     expect(Object.isFrozen(userAction.from)).toBe(true);
   });
 
-  test('preserves markers', () => {
-    expect(userAction.markers).toEqual({ domain: 'auth', priority: 1 });
+  test('preserves metadata', () => {
+    expect(userAction.metadata).toEqual({ domain: 'auth', priority: 1 });
   });
 
   test('optional fields default to undefined', () => {
@@ -64,7 +64,7 @@ describe('event() from and markers', () => {
     });
     expect(minimal.description).toBeUndefined();
     expect(minimal.from).toBeUndefined();
-    expect(minimal.markers).toBeUndefined();
+    expect(minimal.metadata).toBeUndefined();
   });
 });