@ontrails/core 1.0.0-beta.1 → 1.0.0-beta.11

package/src/validation.ts

@@ -94,6 +94,34 @@ export const validateOutput = <T>(
 // Zod → JSON Schema (public API)
 // ---------------------------------------------------------------------------
 
+/**
+ * Sentinel indicating a dynamic default that should be omitted from schema
+ * exports. Zod v4 wraps all defaults in getters; dynamic ones (functions)
+ * produce new values on each access. We detect this by reading the getter
+ * twice and comparing with `Object.is`. If values differ, the default is
+ * dynamic and we cache this sentinel to skip it in future calls.
+ */
+const DYNAMIC_DEFAULT = Symbol('DYNAMIC_DEFAULT');
+const defaultValueCache = new WeakMap<object, unknown>();
+
+/** Read a Zod v4 default getter twice and decide if it's stable.
+ *  Uses Object.is for primitives and JSON.stringify for objects/arrays. */
+const resolveDefault = (def: Record<string, unknown>): unknown => {
+  try {
+    const a = def['defaultValue'];
+    const b = def['defaultValue'];
+    if (Object.is(a, b)) {
+      return a;
+    }
+    // Object/array defaults produce new references each call but may
+    // still be structurally identical (e.g. `() => ({ key: 'val' })`).
+    return JSON.stringify(a) === JSON.stringify(b) ? a : DYNAMIC_DEFAULT;
+  } catch {
+    // BigInt, circular refs, or other non-serializable defaults
+    return DYNAMIC_DEFAULT;
+  }
+};
+
 /**
  * Convert common Zod types to a JSON Schema object.
  *
@@ -142,9 +170,13 @@ export const zodToJsonSchema: JsonSchemaConverter = (
     default: (value) => {
       const inner = value._zod.def['innerType'] as unknown as z.ZodType;
       const innerSchema = zodToJsonSchema(inner);
-      const rawDefault = value._zod.def['defaultValue'];
-      innerSchema['default'] =
-        typeof rawDefault === 'function' ? rawDefault() : rawDefault;
+      if (!defaultValueCache.has(value._zod.def)) {
+        defaultValueCache.set(value._zod.def, resolveDefault(value._zod.def));
+      }
+      const cached = defaultValueCache.get(value._zod.def);
+      if (cached !== DYNAMIC_DEFAULT) {
+        innerSchema['default'] = cached;
+      }
       return innerSchema;
     },
     enum: (value) => {

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/service.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();
-  });
-});

package/src/adapters.ts

@@ -1,68 +0,0 @@
-import type { Result } from './result.js';
-
-// ---------------------------------------------------------------------------
-// Shared option types
-// ---------------------------------------------------------------------------
-
-/** Options for search queries */
-export interface SearchOptions {
-  readonly limit?: number | undefined;
-  readonly offset?: number | undefined;
-  readonly filters?: Readonly<Record<string, unknown>> | undefined;
-}
-
-/** A single search hit */
-export interface SearchResult {
-  readonly id: string;
-  readonly score: number;
-  readonly document: Readonly<Record<string, unknown>>;
-}
-
-/** Options for storage writes */
-export interface StorageOptions {
-  /** Time-to-live in milliseconds */
-  readonly ttl?: number | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Adapter port interfaces
-// ---------------------------------------------------------------------------
-
-/** Full-text / vector index adapter */
-export interface IndexAdapter {
-  index(
-    id: string,
-    document: Readonly<Record<string, unknown>>
-  ): Promise<Result<void, Error>>;
-
-  search(
-    query: string,
-    options?: SearchOptions
-  ): Promise<Result<readonly SearchResult[], Error>>;
-
-  remove(id: string): Promise<Result<void, Error>>;
-}
-
-/** Key-value storage adapter */
-export interface StorageAdapter {
-  get(key: string): Promise<Result<unknown, Error>>;
-  set(
-    key: string,
-    value: unknown,
-    options?: StorageOptions
-  ): Promise<Result<void, Error>>;
-  delete(key: string): Promise<Result<void, Error>>;
-  has(key: string): Promise<Result<boolean, Error>>;
-}
-
-/** Cache adapter with typed get/set and bulk clear */
-export interface CacheAdapter {
-  get<T>(key: string): Promise<Result<T | undefined, Error>>;
-  set<T>(
-    key: string,
-    value: T,
-    options?: StorageOptions
-  ): Promise<Result<void, Error>>;
-  delete(key: string): Promise<Result<void, Error>>;
-  clear(): Promise<Result<void, Error>>;
-}

package/src/health.ts

@@ -1,23 +0,0 @@
-// ---------------------------------------------------------------------------
-// Health check types
-// ---------------------------------------------------------------------------
-
-/** Aggregate health status */
-export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
-
-/** Individual component check result */
-export interface HealthCheck {
-  readonly status: HealthStatus;
-  readonly message?: string | undefined;
-  /** Latency in milliseconds */
-  readonly latency?: number | undefined;
-}
-
-/** Full health report returned by a health endpoint */
-export interface HealthResult {
-  readonly status: HealthStatus;
-  readonly checks: Readonly<Record<string, HealthCheck>>;
-  readonly version?: string | undefined;
-  /** Uptime in seconds */
-  readonly uptime?: number | undefined;
-}

package/src/hike.ts

@@ -1,77 +0,0 @@
-/**
- * Hike — a composition that follows trails.
- */
-
-import type { Trail, TrailSpec } from './trail.js';
-import type { TrailContext } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Spec (input to the factory)
-// ---------------------------------------------------------------------------
-
-export interface HikeSpec<I, O> extends TrailSpec<I, O> {
-  readonly follows: readonly string[];
-}
-
-// ---------------------------------------------------------------------------
-// Shape (output of the factory)
-// ---------------------------------------------------------------------------
-
-export interface Hike<I, O> extends Omit<Trail<I, O>, 'kind'> {
-  readonly kind: 'hike';
-  readonly follows: readonly string[];
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * 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 function hike<I, O>(id: string, spec: HikeSpec<I, O>): Hike<I, O>;
-export function hike<I, O>(
-  spec: HikeSpec<I, O> & { readonly id: string }
-): Hike<I, O>;
-export function hike<I, O>(
-  idOrSpec: string | (HikeSpec<I, O> & { readonly id: string }),
-  maybeSpec?: HikeSpec<I, O>
-): Hike<I, O> {
-  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: I, ctx: TrailContext) =>
-      await implementation(input, ctx),
-    kind: 'hike' as const,
-  });
-}
-
-// oxlint-disable-next-line no-explicit-any -- existential type; see AnyTrail
-export type AnyHike = Hike<any, any>;

package/src/job.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-
-import { progressFields } from './patterns/progress.js';
-import { statusFields } from './patterns/status.js';
-
-/**
- * Proof: job-style output schema composes from existing pattern helpers.
- * No dedicated `kind: "job"` needed — regular trails with status+progress output work.
- */
-export const jobOutputSchema = z.object({
-  ...progressFields().shape,
-  ...statusFields().shape,
-  completedAt: z.string().optional(),
-  error: z.string().optional(),
-  jobId: z.string(),
-  result: z.unknown().optional(),
-  startedAt: z.string().optional(),
-});
-
-export type JobOutput = z.infer<typeof jobOutputSchema>;