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

package/src/topo.ts

@@ -4,7 +4,6 @@
 
 import { ValidationError } from './errors.js';
 import type { AnyEvent } from './event.js';
-import type { AnyHike } from './hike.js';
 import type { AnyTrail } from './trail.js';
 
 // ---------------------------------------------------------------------------
@@ -14,11 +13,12 @@ import type { AnyTrail } from './trail.js';
 export interface Topo {
   readonly name: string;
   readonly trails: ReadonlyMap<string, AnyTrail>;
-  readonly hikes: ReadonlyMap<string, AnyHike>;
   readonly events: ReadonlyMap<string, AnyEvent>;
-  get(id: string): AnyTrail | AnyHike | undefined;
+  readonly count: number;
+  get(id: string): AnyTrail | undefined;
   has(id: string): boolean;
-  list(): (AnyTrail | AnyHike)[];
+  ids(): string[];
+  list(): AnyTrail[];
   listEvents(): AnyEvent[];
 }
 
@@ -26,14 +26,14 @@ export interface Topo {
 // Kind discriminant check
 // ---------------------------------------------------------------------------
 
-type Registrable = AnyTrail | AnyHike | AnyEvent;
+type Registrable = AnyTrail | AnyEvent;
 
 const isRegistrable = (value: unknown): value is Registrable => {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
   const { kind } = value as Record<string, unknown>;
-  return kind === 'trail' || kind === 'hike' || kind === 'event';
+  return kind === 'trail' || kind === 'event';
 };
 
 // ---------------------------------------------------------------------------
@@ -43,20 +43,23 @@ const isRegistrable = (value: unknown): value is Registrable => {
 const createTopo = (
   name: string,
   trails: ReadonlyMap<string, AnyTrail>,
-  hikes: ReadonlyMap<string, AnyHike>,
   events: ReadonlyMap<string, AnyEvent>
 ): Topo => ({
+  count: trails.size,
   events,
-  get(id: string): AnyTrail | AnyHike | undefined {
-    return trails.get(id) ?? hikes.get(id);
+  get(id: string): AnyTrail | undefined {
+    return trails.get(id);
   },
   has(id: string): boolean {
-    return trails.has(id) || hikes.has(id);
+    return trails.has(id);
   },
-  hikes,
 
-  list(): (AnyTrail | AnyHike)[] {
-    return [...trails.values(), ...hikes.values()];
+  ids(): string[] {
+    return [...trails.keys()];
+  },
+
+  list(): AnyTrail[] {
+    return [...trails.values()];
   },
 
   listEvents(): AnyEvent[] {
@@ -76,7 +79,6 @@ const createTopo = (
 const register = (
   value: Registrable,
   trails: Map<string, AnyTrail>,
-  hikes: Map<string, AnyHike>,
   events: Map<string, AnyEvent>
 ): void => {
   const { id } = value as { id: string };
@@ -87,12 +89,6 @@ const register = (
       }
       events.set(id, value as AnyEvent);
     },
-    hike: () => {
-      if (hikes.has(id)) {
-        throw new ValidationError(`Duplicate hike ID: "${id}"`);
-      }
-      hikes.set(id, value as AnyHike);
-    },
     trail: () => {
       if (trails.has(id)) {
         throw new ValidationError(`Duplicate trail ID: "${id}"`);
@@ -108,16 +104,15 @@ export const topo = (
   ...modules: Record<string, unknown>[]
 ): Topo => {
   const trails = new Map<string, AnyTrail>();
-  const hikes = new Map<string, AnyHike>();
   const events = new Map<string, AnyEvent>();
 
   for (const mod of modules) {
     for (const value of Object.values(mod)) {
       if (isRegistrable(value)) {
-        register(value, trails, hikes, events);
+        register(value, trails, events);
       }
     }
   }
 
-  return createTopo(name, trails, hikes, events);
+  return createTopo(name, trails, events);
 };

package/src/trail.ts

@@ -39,34 +39,44 @@ export interface TrailSpec<I, O> {
   /** Zod schema for validating output (optional — some trails are fire-and-forget) */
   readonly output?: z.ZodType<O> | undefined;
   /** The pure function that does the work (sync or async authoring) */
-  readonly implementation: Implementation<I, O>;
+  readonly run: Implementation<I, O>;
   /** Human-readable description */
   readonly description?: string | undefined;
   /** Named examples for docs and testing */
   readonly examples?: readonly TrailExample<I, O>[] | undefined;
-  /** Trail is read-only (no side effects) */
-  readonly readOnly?: boolean | undefined;
-  /** Trail is destructive (deletes or overwrites data) */
-  readonly destructive?: boolean | undefined;
+  /** What this trail does to the world: read, write (default), or destroy */
+  readonly intent?: 'read' | 'write' | 'destroy' | undefined;
   /** Trail is idempotent (safe to retry) */
   readonly idempotent?: boolean | undefined;
   /** Arbitrary metadata for tooling and filtering */
-  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
   /** Named sets of downstream trail IDs that may be invoked */
   readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
   /** Per-field overrides for deriveFields() (labels, hints, options) */
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
+  /** IDs of downstream trails this trail may invoke via ctx.follow() */
+  readonly follow?: readonly string[] | undefined;
 }
 
 // ---------------------------------------------------------------------------
 // Trail (the frozen runtime object)
 // ---------------------------------------------------------------------------
 
+/** Intent describes what a trail does to the world */
+export type Intent = 'read' | 'write' | 'destroy';
+
 /** A fully-defined trail — the unit of work in the Trails system */
-export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
+export interface Trail<I, O> extends Omit<
+  TrailSpec<I, O>,
+  'run' | 'follow' | 'intent'
+> {
   readonly kind: 'trail';
   readonly id: string;
-  readonly implementation: Implementation<I, O>;
+  readonly run: Implementation<I, O>;
+  /** IDs of downstream trails this trail may invoke via ctx.follow() (always present, default []) */
+  readonly follow: readonly string[];
+  /** What this trail does to the world (always present, default 'write') */
+  readonly intent: Intent;
 }
 
 // ---------------------------------------------------------------------------
@@ -84,14 +94,14 @@ export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
  * // ID as first argument (recommended for human authoring)
  * const show = trail("entity.show", {
  *   input: z.object({ name: z.string() }),
- *   implementation: (input) => Result.ok(entity),
+ *   run: (input) => Result.ok(entity),
  * });
  *
  * // Full spec object (for programmatic generation)
  * const show = trail({
  *   id: "entity.show",
  *   input: z.object({ name: z.string() }),
- *   implementation: (input) => Result.ok(entity),
+ *   run: (input) => Result.ok(entity),
  * });
  * ```
  */
@@ -112,14 +122,15 @@ export function trail<I, O>(
     throw new TypeError('trail() requires a spec when an id is provided');
   }
 
-  const { implementation, ...spec } = resolved.spec;
+  const { run, follow: rawFollow, intent: rawIntent, ...spec } = resolved.spec;
 
   return Object.freeze({
     ...spec,
+    follow: Object.freeze([...(rawFollow ?? [])]),
     id: resolved.id,
-    implementation: async (input: I, ctx: TrailContext) =>
-      await implementation(input, ctx),
+    intent: rawIntent ?? 'write',
     kind: 'trail' as const,
+    run: async (input: I, ctx: TrailContext) => await run(input, ctx),
   });
 }
 

package/src/type-utils.ts

@@ -0,0 +1,45 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+
+import type { Result } from './result.js';
+import type { AnyTrail, Trail } from './trail.js';
+
+// ---------------------------------------------------------------------------
+// Utility types
+// ---------------------------------------------------------------------------
+
+/* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
+
+/** 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>;
+
+/* oxlint-enable no-explicit-any */
+
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+
+/** Get the input Zod schema from a trail, preserving the specific schema type. */
+export const inputOf = <T extends AnyTrail>(trail: T): T['input'] =>
+  trail.input;
+
+/** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */
+export const outputOf = <T extends AnyTrail>(trail: T): T['output'] =>
+  trail.output;

package/src/types.ts

@@ -52,7 +52,5 @@ 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';

package/src/validate-topo.ts

@@ -1,14 +1,13 @@
 /**
  * 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.
  */
 
 import { ValidationError } from './errors.js';
 import type { AnyEvent } from './event.js';
-import type { AnyHike } from './hike.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
@@ -28,28 +27,89 @@ export interface TopoIssue {
 // Validators
 // ---------------------------------------------------------------------------
 
+const WHITE = 0;
+const GRAY = 1;
+const BLACK = 2;
+
+/** Build an adjacency list and initial color map from trails with follow. */
+const buildFollowGraph = (
+  trails: ReadonlyMap<string, AnyTrail>
+): {
+  graph: Map<string, readonly string[]>;
+  color: Map<string, number>;
+} => {
+  const graph = new Map<string, readonly string[]>();
+  for (const [id, t] of trails) {
+    if (t.follow.length > 0) {
+      graph.set(id, t.follow);
+    }
+  }
+  const color = new Map<string, number>();
+  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: ReadonlyMap<string, AnyTrail>
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  const { color, graph } = buildFollowGraph(trails);
+
+  const dfs = (node: string, path: string[]): void => {
+    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 = (
-  hikes: ReadonlyMap<string, AnyHike>,
+  trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
-  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,
         });
       } 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;
 };
 
@@ -66,7 +126,7 @@ const checkOneExample = (
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   const result = validateInput(inputSchema as AnyTrail['input'], 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',
@@ -125,13 +185,13 @@ const checkEventOrigins = (
 /**
  * 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: Topo): Result<void, ValidationError> => {
   const issues = [
-    ...checkFollows(topo.hikes, topo),
+    ...checkFollows(topo.trails, topo),
     ...checkExamples(topo.trails),
     ...checkEventOrigins(topo.events, topo),
   ];

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/adapters.ts","./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/fetch.ts","./src/guards.ts","./src/health.ts","./src/hike.ts","./src/index.ts","./src/job.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}
+{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/dispatch.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/guards.ts","./src/index.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}

package/dist/hike.d.ts

@@ -1,36 +0,0 @@
-/**
- * Hike — a composition that follows trails.
- */
-import type { Trail, TrailSpec } from './trail.js';
-export interface HikeSpec<I, O> extends TrailSpec<I, O> {
-    readonly follows: readonly string[];
-}
-export interface Hike<I, O> extends Omit<Trail<I, O>, 'kind'> {
-    readonly kind: 'hike';
-    readonly follows: readonly string[];
-}
-/**
- * Create a hike definition.
- *
- * A hike is a composition that declares which trails it follows.
- * Returns a frozen object with `kind: "hike"` and all spec fields.
- *
- * @example
- * ```typescript
- * // ID as first argument
- * const onboard = hike("entity.onboard", {
- *   follows: ["entity.add", "entity.relate"],
- *   input: z.object({ name: z.string() }),
- *   implementation: (input, ctx) => Result.ok(...),
- * });
- *
- * // Full spec object (programmatic)
- * const onboard = hike({ id: "entity.onboard", follows: [...], ... });
- * ```
- */
-export declare function hike<I, O>(id: string, spec: HikeSpec<I, O>): Hike<I, O>;
-export declare function hike<I, O>(spec: HikeSpec<I, O> & {
-    readonly id: string;
-}): Hike<I, O>;
-export type AnyHike = Hike<any, any>;
-//# sourceMappingURL=hike.d.ts.map

package/dist/hike.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hike.d.ts","sourceRoot":"","sources":["../src/hike.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOnD,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAMD,MAAM,WAAW,IAAI,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACzE,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EACvB,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC7C,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AA0Bd,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC"}

package/dist/hike.js

@@ -1,20 +0,0 @@
-/**
- * Hike — a composition that follows trails.
- */
-export function hike(idOrSpec, maybeSpec) {
-    const resolved = typeof idOrSpec === 'string'
-        ? { id: idOrSpec, spec: maybeSpec }
-        : { id: idOrSpec.id, spec: idOrSpec };
-    if (!resolved.spec) {
-        throw new TypeError('hike() requires a spec when an id is provided');
-    }
-    const { follows, implementation, ...rest } = resolved.spec;
-    return Object.freeze({
-        ...rest,
-        follows: Object.freeze([...follows]),
-        id: resolved.id,
-        implementation: async (input, ctx) => await implementation(input, ctx),
-        kind: 'hike',
-    });
-}
-//# sourceMappingURL=hike.js.map

package/dist/hike.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hike.js","sourceRoot":"","sources":["../src/hike.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiDH,MAAM,UAAU,IAAI,CAClB,QAA6D,EAC7D,SAA0B;IAE1B,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,+CAA+C,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;QACpC,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,MAAe;KACtB,CAAC,CAAC;AACL,CAAC"}

package/src/__tests__/hike.test.ts

@@ -1,117 +0,0 @@
-import { describe, test, expect } from 'bun:test';
-
-import { z } from 'zod';
-
-import { Result } from '../result';
-import { hike } from '../hike';
-import type { TrailContext } from '../types';
-
-const stubCtx: TrailContext = {
-  requestId: 'test-123',
-  signal: AbortSignal.timeout(5000),
-};
-
-describe('hike()', () => {
-  const inputSchema = z.object({ userId: z.string() });
-  const outputSchema = z.object({ profile: z.string() });
-
-  const fetchProfile = hike('fetch-profile', {
-    description: 'Fetch a user profile',
-    follows: ['authenticate', 'validate-session'],
-    implementation: (input) =>
-      Result.ok({ profile: `Profile for ${input.userId}` }),
-    input: inputSchema,
-    output: outputSchema,
-  });
-
-  describe('basics', () => {
-    test("returns kind 'hike'", () => {
-      expect(fetchProfile.kind).toBe('hike');
-    });
-
-    test('returns correct id', () => {
-      expect(fetchProfile.id).toBe('fetch-profile');
-    });
-
-    test('preserves follows array', () => {
-      expect(fetchProfile.follows).toEqual([
-        'authenticate',
-        'validate-session',
-      ]);
-    });
-
-    test('follows array is frozen', () => {
-      expect(Object.isFrozen(fetchProfile.follows)).toBe(true);
-    });
-  });
-
-  describe('trail compatibility', () => {
-    test('extends Trail — has input schema', () => {
-      const parsed = fetchProfile.input.safeParse({ userId: 'u-1' });
-      expect(parsed.success).toBe(true);
-    });
-
-    test('extends Trail — has output schema', () => {
-      expect(fetchProfile.output).toBeDefined();
-    });
-
-    test('extends Trail — implementation is callable', async () => {
-      const result = await fetchProfile.implementation(
-        { userId: 'u-1' },
-        stubCtx
-      );
-      expect(result.isOk()).toBe(true);
-      expect(result.unwrap()).toEqual({ profile: 'Profile for u-1' });
-    });
-
-    test('preserves description', () => {
-      expect(fetchProfile.description).toBe('Fetch a user profile');
-    });
-
-    test('result object is frozen', () => {
-      expect(Object.isFrozen(fetchProfile)).toBe(true);
-    });
-  });
-
-  test('markers are preserved', () => {
-    const withMarkers = hike('tagged-hike', {
-      follows: ['setup'],
-      implementation: () => Result.ok(),
-      input: z.object({}),
-      markers: { domain: 'auth' },
-    });
-    expect(withMarkers.markers).toEqual({ domain: 'auth' });
-  });
-
-  describe('single-object overload', () => {
-    test('accepts spec with id property', () => {
-      const r = hike({
-        follows: ['entity.add', 'entity.relate'],
-        id: 'entity.onboard',
-        implementation: () => Result.ok(),
-        input: z.object({}),
-      });
-      expect(r.id).toBe('entity.onboard');
-      expect(r.kind).toBe('hike');
-      expect(r.follows).toEqual(['entity.add', 'entity.relate']);
-    });
-
-    test('sync implementations are normalized to an awaitable runtime function', async () => {
-      const r = hike({
-        follows: ['entity.add'],
-        id: 'entity.check',
-        implementation: (input: { userId: string }) =>
-          Result.ok({ profile: input.userId }),
-        input: inputSchema,
-        output: outputSchema,
-      });
-
-      const promise = r.implementation({ userId: 'u-2' }, stubCtx);
-      expect(promise).toBeInstanceOf(Promise);
-
-      const result = await promise;
-      expect(result.isOk()).toBe(true);
-      expect(result.unwrap()).toEqual({ profile: 'u-2' });
-    });
-  });
-});

package/src/__tests__/job.test.ts

@@ -1,98 +0,0 @@
-import { describe, test, expect } from 'bun:test';
-
-import { z } from 'zod';
-
-import { jobOutputSchema } from '../job';
-
-describe('jobOutputSchema', () => {
-  test('parses a valid completed job output', () => {
-    const input = {
-      completedAt: '2026-03-25T00:01:00Z',
-      current: 10,
-      jobId: 'job-123',
-      percentage: 100,
-      result: { rows: 42 },
-      startedAt: '2026-03-25T00:00:00Z',
-      status: 'completed',
-      total: 10,
-    };
-
-    const parsed = jobOutputSchema.parse(input);
-
-    expect(parsed.jobId).toBe('job-123');
-    expect(parsed.status).toBe('completed');
-    expect(parsed.current).toBe(10);
-    expect(parsed.total).toBe(10);
-  });
-
-  test('parses a minimal pending job output', () => {
-    const input = {
-      current: 0,
-      jobId: 'job-456',
-      status: 'pending',
-      total: 100,
-    };
-
-    const parsed = jobOutputSchema.parse(input);
-
-    expect(parsed.jobId).toBe('job-456');
-    expect(parsed.status).toBe('pending');
-    expect(parsed.result).toBeUndefined();
-    expect(parsed.error).toBeUndefined();
-  });
-
-  test('parses a failed job with error', () => {
-    const input = {
-      current: 3,
-      error: 'connection reset',
-      jobId: 'job-789',
-      status: 'failed',
-      total: 10,
-    };
-
-    const parsed = jobOutputSchema.parse(input);
-
-    expect(parsed.status).toBe('failed');
-    expect(parsed.error).toBe('connection reset');
-  });
-
-  test('rejects when jobId is missing', () => {
-    const input = {
-      current: 1,
-      status: 'running',
-      total: 5,
-    };
-
-    expect(() => jobOutputSchema.parse(input)).toThrow();
-  });
-
-  test('rejects an invalid status value', () => {
-    const input = {
-      current: 0,
-      jobId: 'job-bad',
-      status: 'unknown',
-      total: 0,
-    };
-
-    expect(() => jobOutputSchema.parse(input)).toThrow();
-  });
-
-  test('composes statusFields and progressFields correctly', () => {
-    const { shape } = jobOutputSchema;
-
-    // Status field from statusFields()
-    expect(shape.status).toBeInstanceOf(z.ZodEnum);
-
-    // Progress fields from progressFields()
-    expect(shape.current).toBeInstanceOf(z.ZodNumber);
-    expect(shape.total).toBeInstanceOf(z.ZodNumber);
-    expect(shape.percentage).toBeDefined();
-
-    // Job-specific fields
-    expect(shape.jobId).toBeInstanceOf(z.ZodString);
-    expect(shape.error).toBeDefined();
-    expect(shape.result).toBeDefined();
-    expect(shape.startedAt).toBeDefined();
-    expect(shape.completedAt).toBeDefined();
-  });
-});