@ontrails/core 1.0.0-beta.14 → 1.0.0-beta.16

package/src/types.ts

@@ -1,4 +1,66 @@
+import type { TrailsError } from './errors.js';
+import type { BasePermit } from './permits.js';
 import type { Result } from './result.js';
+import type { Signal } from './signal.js';
+import type { AnyTrail } from './trail.js';
+import type { CrossInput, TrailOutput } from './type-utils.js';
+import type { ActivationProvenance } from './activation-provenance.js';
+
+// ---------------------------------------------------------------------------
+// Detour
+// ---------------------------------------------------------------------------
+
+/** A recovery path that activates when a trail's blaze fails with a matching error. */
+export interface Detour<Input, Output, TErr extends TrailsError = TrailsError> {
+  /* oxlint-disable-next-line no-explicit-any -- standard pattern for matching abstract+concrete class constructors */
+  readonly on: abstract new (...args: any[]) => TErr;
+  readonly maxAttempts?: number | undefined;
+  readonly recover: (
+    attempt: DetourAttempt<Input, TErr>,
+    ctx: TrailContext
+  ) => Promise<Result<Output, TrailsError>>;
+}
+
+/** Context passed to a detour's recover function on each attempt. */
+export interface DetourAttempt<Input, TErr extends TrailsError = TrailsError> {
+  /** 1-indexed attempt number */
+  readonly attempt: number;
+  /** The matched error */
+  readonly error: TErr;
+  /** Original trail input */
+  readonly input: Input;
+}
+
+type CrossBatchCall<TTarget extends AnyTrail | string = AnyTrail | string> =
+  TTarget extends AnyTrail
+    ? readonly [trail: TTarget, input: CrossInput<TTarget>]
+    : readonly [id: string, input: unknown];
+
+type CrossBatchResult<TTarget extends AnyTrail | string> =
+  TTarget extends AnyTrail
+    ? Result<TrailOutput<TTarget>, Error>
+    : Result<unknown, Error>;
+
+type CrossBatchResults<TCalls extends readonly CrossBatchCall[]> = {
+  readonly [K in keyof TCalls]: TCalls[K] extends readonly [
+    infer TTarget,
+    unknown,
+  ]
+    ? TTarget extends AnyTrail | string
+      ? CrossBatchResult<TTarget>
+      : never
+    : never;
+};
+
+/** Runtime options for batch `ctx.cross([...])` calls. */
+export interface CrossBatchOptions {
+  /**
+   * Maximum number of branches to execute concurrently.
+   *
+   * Omit for unbounded concurrency. `1` is equivalent to sequential execution.
+   */
+  readonly concurrency?: number | undefined;
+}
 
 /**
  * Trail implementation — sync or async.
@@ -11,17 +73,67 @@ export type Implementation<I, O> = (
   ctx: TrailContext
 ) => Result<O, Error> | Promise<Result<O, Error>>;
 
-/** Invoke another trail by id — used for trail composition */
-export type CrossFn = <O>(
-  id: string,
-  input: unknown
-) => Promise<Result<O, Error>>;
+/**
+ * Invoke another trail — used for trail composition.
+ *
+ * Two call shapes:
+ *
+ * - **By trail object** (typed): `ctx.cross(showGist, { id })` — the compiler
+ *   infers `I` and `O` from the trail's schemas, so the result is fully typed.
+ * - **By string id** (untyped escape hatch): `ctx.cross('gist.show', { id })`
+ *   — returns `Result<O, Error>` where `O` defaults to `unknown`.
+ * - **By batch**: `ctx.cross([[showGist, { id }], ['audit.log', payload]])`
+ *   — executes every crossing concurrently and resolves once all results are
+ *   available. Result ordering always matches the input tuple ordering. Pass
+ *   `{ concurrency: N }` as the second argument to limit how many branches
+ *   run at once.
+ */
+export interface CrossFn {
+  <const TCalls extends readonly CrossBatchCall[]>(
+    calls: TCalls,
+    options?: CrossBatchOptions
+  ): Promise<CrossBatchResults<TCalls>>;
+  <T extends AnyTrail>(
+    trail: T,
+    input: CrossInput<T>
+  ): Promise<Result<TrailOutput<T>, Error>>;
+  <O = unknown>(id: string, input: unknown): Promise<Result<O, Error>>;
+}
+
+/**
+ * Emit a signal — used for signal-driven activation.
+ *
+ * Fan-out to consumer trails (those with the signal in their `on:` array) is
+ * the framework's responsibility. Producers call with a `Signal<T>` value and
+ * get best-effort `Promise<void>` semantics: payload validation, missing topo
+ * entries, guard suppression, and consumer failures are observable through
+ * diagnostics/logging but do not become producer-facing `Result` plumbing.
+ * Consumers fan out in parallel, each with its own derived context. Runtime
+ * cycle suppression is still signal-id-based against the current fire stack:
+ * it prevents re-entrant loops but can over-suppress legitimate diamond
+ * re-fires, with a debug breadcrumb and a warn emitted when suppression
+ * happens.
+ */
+export type FireFn = <T>(signal: Signal<T>, payload: T) => Promise<void>;
 
-/** Resolve a provision instance from the current trail context. */
-export type ProvisionLookup = <T = unknown>(
-  provisionOrId: { readonly id: string } | string
+/** Resolve a resource instance from the current trail context. */
+export type ResourceLookup = <T = unknown>(
+  resourceOrId: { readonly id: string } | string
 ) => T;
 
+/**
+ * Wrap the execution of `fn` in a child trace span.
+ *
+ * Creates a nested span under the current trail's root trace record, times
+ * the callback, records success or failure (including error category), and
+ * writes the completed span to the registered sink. Errors thrown by `fn`
+ * are recorded on the span and then rethrown — tracing never swallows them.
+ */
+export type TraceFn = <T>(
+  label: string,
+  fn: () => T | Promise<T>
+) => Promise<T>;
+
 /** Callback for reporting progress from long-running trails */
 export type ProgressCallback = (event: ProgressEvent) => void;
 
@@ -46,20 +158,68 @@ export interface Logger {
   child(context: Record<string, unknown>): Logger;
 }
 
-/** Context extension key for the invoking trailhead name. */
-export const TRAILHEAD_KEY = '__trails_trailhead' as const;
+export type LogLevel =
+  | 'debug'
+  | 'error'
+  | 'fatal'
+  | 'info'
+  | 'silent'
+  | 'trace'
+  | 'warn';
+
+export interface LogRecord {
+  readonly category: string;
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly metadata: Record<string, unknown>;
+  readonly timestamp: Date;
+}
+
+export interface LogSink {
+  readonly name: string;
+  readonly write: (record: LogRecord) => void;
+  readonly flush?: (() => Promise<void>) | undefined;
+}
 
-/** Minimal permit shape available on TrailContext. Permits extends this. */
-export interface BasePermit {
-  readonly id: string;
-  readonly scopes: readonly string[];
+export interface LogFormatter {
+  format(record: LogRecord): string;
 }
 
+/**
+ * Context extension key for the invoking surface name.
+ */
+export const SURFACE_KEY = '__trails_surface' as const;
+
+/**
+ * Context extension key for the layer names attached by the invoking surface.
+ */
+export const SURFACE_LAYER_NAMES_KEY = '__trails_surface_layer_names' as const;
+
+/**
+ * Context extension key carrying per-layer runtime input.
+ *
+ * Surfaces (CLI, MCP, HTTP) project each typed layer's `input` schema onto
+ * their native idioms (flags, tool params, query strings). At execute time
+ * the parsed values are partitioned per layer and stored under this key as
+ * `Record<layerName, unknown>`. Layers that need runtime input read their
+ * own slot via `ctx.extensions?.[LAYER_INPUTS_KEY]?.[layer.name]`.
+ *
+ * @see TRL-473 for the CLI projection contract.
+ */
+export const LAYER_INPUTS_KEY = '__trails_layer_inputs' as const;
+
 /** Runtime context threaded through every trail execution */
 export interface TrailContext {
+  readonly activation?: ActivationProvenance | undefined;
   readonly requestId: string;
   readonly abortSignal: AbortSignal;
   readonly cross?: CrossFn | undefined;
+  /**
+   * Emit a typed signal. Fans out to every trail with the signal in its
+   * `on:` declaration. Bound by the runner that holds the topo (typically
+   * `run()`); undefined when a context is constructed without topo access.
+   */
+  readonly fire?: FireFn | undefined;
   readonly permit?: BasePermit;
   readonly workspaceRoot?: string | undefined;
   readonly logger?: Logger | undefined;
@@ -67,7 +227,37 @@ export interface TrailContext {
   readonly cwd?: string | undefined;
   readonly env?: Record<string, string | undefined> | undefined;
   readonly extensions?: Readonly<Record<string, unknown>> | undefined;
-  readonly provision?: ProvisionLookup | undefined;
+  readonly resource?: ResourceLookup | undefined;
+  /**
+   * Whether the current invocation is a dry run.
+   *
+   * Defaults to `false`. Trails that don't read this field are unaffected.
+   * Trails that do read it decide what dry-run means for their domain — for
+   * example: preview the change without committing, validate inputs without
+   * performing side effects, or return what would happen without actually
+   * doing it.
+   *
+   * The framework only carries the flag from the surface (e.g. CLI
+   * `--dry-run`) into the context. It never short-circuits trail execution
+   * on its own based on this field.
+   *
+   * Pair this runtime signal with `TrailSpec.dryRun`, which declares whether a
+   * trail supports dry-run semantics for governance, derivation, and surface
+   * tooling.
+   *
+   * @remarks Always defined on contexts produced by `executeTrail` or
+   * `createTrailContext` (normalized to `false` when not provided).
+   */
+  readonly dryRun?: boolean | undefined;
+  /**
+   * Wrap a callback in a child trace span.
+   *
+   * Always present on contexts produced by `executeTrail` or
+   * `createTrailContext`. Optional on the interface so manually constructed
+   * contexts (tests, ad-hoc compositions) don't have to supply one — call
+   * sites tolerate `undefined` by falling back to a no-op passthrough.
+   */
+  readonly trace?: TraceFn | undefined;
 }
 
 /**
@@ -82,6 +272,7 @@ export type PermitRequirement =
   | 'public';
 
 /** Input shape used to seed a runtime TrailContext before resolution. */
-export type TrailContextInit = Omit<TrailContext, 'provision'> & {
-  readonly provision?: ProvisionLookup | undefined;
+export type TrailContextInit = Omit<TrailContext, 'resource' | 'trace'> & {
+  readonly resource?: ResourceLookup | undefined;
+  readonly trace?: TraceFn | undefined;
 };

package/src/validate-established-topo.ts

@@ -1,7 +1,7 @@
 import { ValidationError } from './errors.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
-import { validateEstablishedTopo as validateDraftFreeTopo } from './draft.js';
+import { validateDraftFreeTopo } from './draft.js';
 import type { TopoIssue } from './validate-topo.js';
 import { validateTopo } from './validate-topo.js';
 
@@ -9,7 +9,13 @@ const PROJECTION_BLOCKING_RULES = new Set([
   'cross-cycle',
   'cross-exists',
   'no-self-cross',
-  'provision-exists',
+  'activation-source-definition-unique',
+  'activation-source-edge-unique',
+  'activation-source-kind-known',
+  'activation-schedule-valid',
+  'resource-exists',
+  'signal-fire-exists',
+  'signal-on-exists',
   'signal-origin-exists',
 ]);
 

package/src/validate-topo.ts

@@ -1,18 +1,30 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks trail crossing references, example input validity, event origin
- * references, and output schema completeness. Returns a Result with all
- * issues collected into a single ValidationError.
+ * Checks trail crossing references, example input validity, signal origin
+ * references, activation source kinds, and output schema completeness. Returns
+ * a Result with all issues collected into a single ValidationError.
  */
 
+import type { ActivationSchemaIssue } from './activation-source-compatibility.js';
+import { getActivationSourceInputCompatibilityIssues } from './activation-source-compatibility.js';
+import {
+  activationSourceDeclarationSignature,
+  activationSourceKey,
+} from './activation-source-projection.js';
+import type { AnyContour } from './contour.js';
+import { getContourReferences } from './contour.js';
 import { ValidationError } from './errors.js';
+import type { ActivationEntry } from './activation-source.js';
+import { isKnownActivationSourceKind } from './activation-source.js';
 import { isDraftId } from './draft.js';
-import type { AnySignal } from './event.js';
+import type { AnySignal } from './signal.js';
+import { validateScheduleSource } from './schedule.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
 import { validateInput } from './validation.js';
+import { validateWebhookSource } from './webhook.js';
 
 // ---------------------------------------------------------------------------
 // Issue shape
@@ -22,8 +34,14 @@ export interface TopoIssue {
   readonly trailId: string;
   readonly rule: string;
   readonly message: string;
+  readonly inputPath?: readonly (string | number)[];
+  readonly schemaIssues?: readonly TopoSchemaIssue[];
+  readonly sourceId?: string;
+  readonly sourceKind?: string;
 }
 
+export type TopoSchemaIssue = ActivationSchemaIssue;
+
 // ---------------------------------------------------------------------------
 // Validators
 // ---------------------------------------------------------------------------
@@ -114,21 +132,21 @@ const checkCrosses = (
   return issues;
 };
 
-const checkProvisions = (
+const checkResources = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
 
   for (const [id, trail] of trails) {
-    for (const declaredProvision of trail.provisions) {
+    for (const declaredResource of trail.resources) {
       if (
-        !topo.hasProvision(declaredProvision.id) &&
-        !isDraftId(declaredProvision.id)
+        !topo.hasResource(declaredResource.id) &&
+        !isDraftId(declaredResource.id)
       ) {
         issues.push({
-          message: `Provision "${declaredProvision.id}" is not in the topo`,
-          rule: 'provision-exists',
+          message: `Resource "${declaredResource.id}" is not in the topo`,
+          rule: 'resource-exists',
           trailId: id,
         });
       }
@@ -203,6 +221,214 @@ const checkSignalOrigins = (
   return issues;
 };
 
+const checkSignalReferences = (
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+
+  for (const [id, trail] of trails) {
+    for (const signalId of trail.fires ?? []) {
+      if (!signals.has(signalId) && !isDraftId(signalId)) {
+        issues.push({
+          message: `Trail fires signal "${signalId}" which is not in the topo`,
+          rule: 'signal-fire-exists',
+          trailId: id,
+        });
+      }
+    }
+
+    for (const signalId of trail.on ?? []) {
+      if (!signals.has(signalId) && !isDraftId(signalId)) {
+        issues.push({
+          message: `Trail declares on signal "${signalId}" which is not in the topo`,
+          rule: 'signal-on-exists',
+          trailId: id,
+        });
+      }
+    }
+  }
+
+  return issues;
+};
+
+const checkActivationSources = (
+  trails: ReadonlyMap<string, AnyTrail>
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  const sourceDeclarations = new Map<
+    string,
+    {
+      readonly signature: string;
+      readonly trailId: string;
+    }
+  >();
+  const trailSourceEdges = new Set<string>();
+
+  for (const [id, trail] of trails) {
+    for (const activation of trail.activationSources ?? []) {
+      if (!isKnownActivationSourceKind(activation.source.kind)) {
+        issues.push({
+          message: `Trail declares on source "${activation.source.id}" with unsupported source kind "${activation.source.kind}"`,
+          rule: 'activation-source-kind-known',
+          trailId: id,
+        });
+        continue;
+      }
+
+      const sourceKey = activationSourceKey(activation.source);
+      const edgeKey = `${id}\0${sourceKey}`;
+      if (trailSourceEdges.has(edgeKey)) {
+        issues.push({
+          message: `Trail declares activation source "${activation.source.id}" (${activation.source.kind}) more than once. Keep one source-to-trail activation edge, or split distinct activation behavior into distinct source ids.`,
+          rule: 'activation-source-edge-unique',
+          sourceId: activation.source.id,
+          sourceKind: activation.source.kind,
+          trailId: id,
+        });
+      } else {
+        trailSourceEdges.add(edgeKey);
+      }
+
+      if (!isDraftId(activation.source.id)) {
+        const signature = activationSourceDeclarationSignature(
+          activation.source
+        );
+        const previous = sourceDeclarations.get(sourceKey);
+        if (previous === undefined) {
+          sourceDeclarations.set(sourceKey, { signature, trailId: id });
+        } else if (previous.signature !== signature) {
+          issues.push({
+            message: `Activation source "${activation.source.id}" (${activation.source.kind}) is declared with conflicting source options by trails "${previous.trailId}" and "${id}". Use one canonical source declaration per source id, or give distinct source configurations distinct ids.`,
+            rule: 'activation-source-definition-unique',
+            sourceId: activation.source.id,
+            sourceKind: activation.source.kind,
+            trailId: id,
+          });
+        }
+      }
+
+      const scheduleIssues = validateScheduleSource(activation.source);
+      for (const issue of scheduleIssues) {
+        issues.push({
+          inputPath: [issue.field],
+          message: `Trail declares schedule source "${activation.source.id}" with invalid ${issue.field}: ${issue.message}`,
+          rule: 'activation-schedule-valid',
+          schemaIssues: [
+            { code: issue.field, message: issue.message, path: [issue.field] },
+          ],
+          sourceId: activation.source.id,
+          sourceKind: activation.source.kind,
+          trailId: id,
+        });
+      }
+
+      const webhookIssues = validateWebhookSource(activation.source);
+      for (const issue of webhookIssues) {
+        issues.push({
+          inputPath: [issue.field],
+          message: `Trail declares webhook source "${activation.source.id}" with invalid ${issue.field}: ${issue.message}`,
+          rule: 'activation-webhook-valid',
+          schemaIssues: [
+            { code: issue.field, message: issue.message, path: [issue.field] },
+          ],
+          sourceId: activation.source.id,
+          sourceKind: activation.source.kind,
+          trailId: id,
+        });
+      }
+    }
+  }
+
+  return issues;
+};
+
+const issuePathText = (path: readonly (string | number)[]): string =>
+  path.length > 0 ? path.join('.') : '<root>';
+
+const createSourceCompatibilityIssue = (
+  trailId: string,
+  activation: ActivationEntry,
+  schemaIssues: readonly TopoSchemaIssue[]
+): TopoIssue => {
+  const [firstIssue] = schemaIssues;
+  const inputPath = firstIssue?.path ?? Object.freeze([]);
+  return {
+    inputPath,
+    message: `Activation source "${activation.source.id}" (${activation.source.kind}) does not satisfy trail input at ${issuePathText(inputPath)}: ${firstIssue?.message ?? 'source payload is incompatible with trail input'}`,
+    rule: 'activation-source-input-compatible',
+    schemaIssues,
+    sourceId: activation.source.id,
+    sourceKind: activation.source.kind,
+    trailId,
+  };
+};
+
+const checkSourcePayloadCompatibility = (
+  trail: AnyTrail,
+  activation: ActivationEntry,
+  signals: ReadonlyMap<string, AnySignal>
+): TopoIssue | undefined => {
+  if (
+    !isKnownActivationSourceKind(activation.source.kind) ||
+    isDraftId(activation.source.id)
+  ) {
+    return undefined;
+  }
+
+  const schemaIssues = getActivationSourceInputCompatibilityIssues(
+    trail.input,
+    activation.source,
+    signals
+  );
+  if (!schemaIssues) {
+    return undefined;
+  }
+
+  return schemaIssues.length > 0
+    ? createSourceCompatibilityIssue(trail.id, activation, schemaIssues)
+    : undefined;
+};
+
+const checkActivationSourceInputCompatibility = (
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+
+  for (const trail of trails.values()) {
+    for (const activation of trail.activationSources ?? []) {
+      const issue = checkSourcePayloadCompatibility(trail, activation, signals);
+      if (issue) {
+        issues.push(issue);
+      }
+    }
+  }
+
+  return issues;
+};
+
+const checkContourReferences = (
+  contours: ReadonlyMap<string, AnyContour>,
+  topo: Topo
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+
+  for (const [name, contourDef] of contours) {
+    for (const ref of getContourReferences(contourDef)) {
+      if (!topo.hasContour(ref.contour) && !isDraftId(ref.contour)) {
+        issues.push({
+          message: `Contour "${name}" references "${ref.contour}" which is not in the topo`,
+          rule: 'contour-reference-exists',
+          trailId: name,
+        });
+      }
+    }
+  }
+
+  return issues;
+};
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -210,16 +436,21 @@ const checkSignalOrigins = (
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks crossing references, example inputs, event origins, and output
- * schema presence. Returns `Result.ok()` when no issues are found, or
+ * Checks crossing references, example inputs, signal origins, activation
+ * source kinds, 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 = [
     ...checkCrosses(topo.trails, topo),
-    ...checkProvisions(topo.trails, topo),
+    ...checkResources(topo.trails, topo),
+    ...checkContourReferences(topo.contours, topo),
     ...checkExamples(topo.trails),
     ...checkSignalOrigins(topo.signals, topo),
+    ...checkSignalReferences(topo.trails, topo.signals),
+    ...checkActivationSources(topo.trails),
+    ...checkActivationSourceInputCompatibility(topo.trails, topo.signals),
   ];
 
   if (issues.length === 0) {

package/src/validation.ts

@@ -7,6 +7,7 @@
 
 import type { z } from 'zod';
 
+import { BLOB_REF_SCHEMA_META_KEY, blobRefJsonSchema } from './blob-ref.js';
 import { ValidationError } from './errors.js';
 import { Result } from './result.js';
 
@@ -31,10 +32,57 @@ type JsonSchemaConverter = (schema: z.ZodType) => JsonSchema;
 // ---------------------------------------------------------------------------
 
 const isOptionalLike = (s: ZodInternals): boolean => {
-  const defType = s._zod.def['type'] as string;
+  let current = s;
+  const seen = new Set<ZodInternals>();
+  while (
+    current._zod.def['type'] === 'readonly' &&
+    !seen.has(current) &&
+    current._zod.def['innerType'] !== undefined
+  ) {
+    seen.add(current);
+    current = current._zod.def['innerType'] as ZodInternals;
+  }
+  const defType = current._zod.def['type'] as string;
   return defType === 'optional' || defType === 'default';
 };
 
+const getSchemaMeta = (
+  schema: z.ZodType
+): Readonly<Record<string, unknown>> | undefined => {
+  const maybeMeta = (schema as unknown as { meta?: () => unknown }).meta;
+  if (typeof maybeMeta !== 'function') {
+    return undefined;
+  }
+  const meta = maybeMeta.call(schema);
+  return typeof meta === 'object' && meta !== null
+    ? (meta as Readonly<Record<string, unknown>>)
+    : undefined;
+};
+
+const getSchemaJsonSchemaOverride = (
+  schema: z.ZodType
+): JsonSchema | undefined => {
+  const meta = getSchemaMeta(schema);
+  if (meta?.[BLOB_REF_SCHEMA_META_KEY] === true) {
+    const override: JsonSchema = {
+      properties: Object.fromEntries(
+        Object.entries(blobRefJsonSchema.properties).map(([key, value]) => [
+          key,
+          { ...value },
+        ])
+      ),
+      required: [...blobRefJsonSchema.required],
+      type: blobRefJsonSchema.type,
+    };
+    const { description } = schema as unknown as ZodInternals;
+    if (description) {
+      override['description'] = description;
+    }
+    return override;
+  }
+  return undefined;
+};
+
 // ---------------------------------------------------------------------------
 // Issue formatting
 // ---------------------------------------------------------------------------
@@ -132,6 +180,11 @@ const resolveDefault = (def: Record<string, unknown>): unknown => {
 export const zodToJsonSchema: JsonSchemaConverter = (
   schema: z.ZodType
 ): JsonSchema => {
+  const jsonSchemaOverride = getSchemaJsonSchemaOverride(schema);
+  if (jsonSchemaOverride !== undefined) {
+    return jsonSchemaOverride;
+  }
+
   const s = schema as unknown as ZodInternals;
 
   const collectObjectFields = (shape: Record<string, ZodInternals>) => {
@@ -197,6 +250,10 @@ export const zodToJsonSchema: JsonSchemaConverter = (
       const inner = value._zod.def['innerType'] as unknown as z.ZodType;
       return zodToJsonSchema(inner);
     },
+    readonly: (value) => {
+      const inner = value._zod.def['innerType'] as unknown as z.ZodType;
+      return zodToJsonSchema(inner);
+    },
     string: () => ({ type: 'string' }),
     union: (value) => {
       const options = value._zod.def['options'] as unknown as z.ZodType[];