@classytic/arc 2.20.0 → 2.22.0

package/dist/utils/index.d.mts

@@ -1,9 +1,8 @@
-import { Qt as UserLike, S as QueryParserInterface, b as ParsedQuery, et as OpenApiSchemas, qt as AnyRecord, st as ResourceConfig } from "../index-_--GyzcO.mjs";
-import { n as ErrorMapper } from "../errorHandler-BtUUDPEa.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DOHkjQlD.mjs";
+import { $ as OpenApiSchemas, Qt as UserLike, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
-
 //#region src/core/validateResourceConfig.d.ts
 interface ConfigError {
   field: string;
@@ -384,6 +383,49 @@ interface Guard<T> {
  */
 declare function defineGuard<T>(config: GuardConfig<T>): Guard<T>;
 //#endregion
+//#region src/utils/filter-dialect.d.ts
+/**
+ * Filter dialects — decouple `ArcQueryParser` from any single datastore's
+ * operator vocabulary.
+ *
+ * The parser owns everything store-INDEPENDENT: URL parsing, field/operator
+ * whitelisting, depth limits, value coercion, ReDoS-safe regex sanitisation.
+ * A `FilterDialect` owns the ONLY store-specific part of the output — which
+ * token each neutral operator (`gte`, `like`, `in`, …) is emitted as, and how a
+ * case-insensitive text match is expressed. Swap the dialect (or the whole
+ * parser via `QueryParserInterface`) to target a non-Mongo store; the default
+ * stays Mongo, so existing hosts are unaffected.
+ */
+interface FilterDialect {
+  /**
+   * Neutral operator name → emitted token. An operator absent from this map is
+   * treated as unsupported (dropped), so a dialect also defines its operator set.
+   */
+  readonly operators: Readonly<Record<string, string>>;
+  /**
+   * Extra keys merged into a field-filter when a documented case-insensitive
+   * text operator (`like` / `contains`) is used. Mongo expresses this as a
+   * sibling `{ $options: 'i' }`; a dialect that encodes case-insensitivity in
+   * the operator itself returns `{}`.
+   */
+  caseInsensitiveModifier(): Record<string, unknown>;
+}
+/**
+ * Default dialect — MongoDB / MongoKit operator shape. Emits `$`-prefixed
+ * tokens and the `$options: 'i'` case-insensitive sibling. This is what
+ * `ArcQueryParser` uses when no dialect is supplied, so behaviour is identical
+ * to every prior arc version.
+ */
+declare const MONGO_DIALECT: FilterDialect;
+/**
+ * Store-neutral reference dialect — emits UN-prefixed operator tokens as a
+ * translation AST (`?price[gte]=40` → `{ price: { gte: 40 } }`, with
+ * `{ caseInsensitive: true }` for `like`/`contains`). A non-Mongo adapter can
+ * consume this directly instead of writing a full `QueryParserInterface`. Use
+ * as a starting point; adjust the token names to your store's vocabulary.
+ */
+declare const NEUTRAL_DIALECT: FilterDialect;
+//#endregion
 //#region src/utils/handleRaw.d.ts
 /**
  * Wrap a raw Fastify handler with Arc's response shape and error handling.
@@ -425,6 +467,13 @@ interface ArcQueryParserOptions {
    * Also used by MCP to enrich list tool descriptions.
    */
   allowedOperators?: string[];
+  /**
+   * Datastore dialect for the EMITTED filter shape (operator tokens +
+   * case-insensitive expression). Defaults to `MONGO_DIALECT`. Pass
+   * `NEUTRAL_DIALECT` (or a custom one) to retarget the operator vocabulary
+   * without writing a full `QueryParserInterface`.
+   */
+  dialect?: FilterDialect;
 }
 /**
  * Arc's default query parser
@@ -469,8 +518,13 @@ declare class ArcQueryParser implements QueryParserInterface {
   readonly allowedSortFields?: readonly string[];
   /** Allowed operators (used by MCP for operator descriptions) */
   readonly allowedOperators?: readonly string[];
-  /** Supported filter operators */
-  private readonly operators;
+  /**
+   * Datastore dialect — owns the store-specific operator tokens + the
+   * case-insensitive modifier. Defaults to Mongo (backward-compatible).
+   */
+  private readonly dialect;
+  /** Supported filter operators (neutral name → emitted token), from the dialect. */
+  private get operators();
   constructor(options?: ArcQueryParserOptions);
   /**
    * Parse URL query parameters into structured query options
@@ -545,9 +599,8 @@ declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryPar
 interface JsonSchema {
   /**
    * Optional because JSON Schema allows top-level combinator-only schemas
-   * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-   * `listResponse()`, which emits a `oneOf` of the four canonical list
-   * shapes with no top-level `type`.
+   * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — hosts
+   * may pass such schemas anywhere a `JsonSchema` is accepted.
    */
   type?: string | string[];
   properties?: Record<string, JsonSchema | AnyRecord>;
@@ -569,18 +622,25 @@ interface JsonSchema {
  */
 declare const paginationSchema: JsonSchema;
 /**
- * List response schema — full union of every wire shape `toCanonicalList`
- * can emit. Hosts who know their endpoint only ever produces one variant
- * can pin to a narrower helper:
+ * List response schema — accepts every wire shape `toCanonicalList` can
+ * emit. Hosts who know their endpoint only ever produces one variant can
+ * pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
  *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
  *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
  *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
  *   - `bareListResponse(item)` — `{ data }`
  *
- * The default `listResponse(item)` is the union (`oneOf`) of all four so
- * Fastify validation accepts any canonical kit shape — pre-2.13 this only
- * modelled offset and rejected keyset/aggregate/bare lists at the
- * response-schema gate.
+ * SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+ * pre-2.22 union was semantically identical on the wire — every variant is
+ * `additionalProperties: true` and the property definitions never conflict
+ * (`next` only exists on keyset, the offset counters only on offset/
+ * aggregate; fast-json-stringify skips undefined optionals) — but
+ * fast-json-stringify implements top-level `oneOf` by running full AJV
+ * validation PER RESPONSE to pick the branch, on the hottest route of
+ * every arc app. The merge keeps the exact bytes (pinned by
+ * `tests/utils/list-response-serialization.test.ts`) and drops the
+ * per-response branch validation. Only `data` is required — the one field
+ * all four variants share.
  */
 declare function listResponse(itemSchema: JsonSchema): JsonSchema;
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
@@ -607,12 +667,10 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          additionalProperties: boolean;
           /**
            * Optional because JSON Schema allows top-level combinator-only schemas
-           * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-           * `listResponse()`, which emits a `oneOf` of the four canonical list
-           * shapes with no top-level `type`.
+           * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — hosts
+           * may pass such schemas anywhere a `JsonSchema` is accepted.
            */
           type?: string | string[];
           properties?: Record<string, JsonSchema | AnyRecord>;
@@ -623,6 +681,7 @@ declare const responses: {
           oneOf?: JsonSchema[];
           anyOf?: JsonSchema[];
           allOf?: JsonSchema[];
+          additionalProperties: boolean;
         };
       };
     };
@@ -632,54 +691,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -689,54 +748,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -746,54 +805,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -803,54 +862,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -860,54 +919,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -917,54 +976,54 @@ declare const responses: {
     content: {
       "application/json": {
         schema: {
-          readonly type: "object";
+          readonly type: 'object';
           readonly properties: {
             readonly code: {
-              readonly type: "string";
+              readonly type: 'string';
               readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
             };
             readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
+              readonly type: 'string';
+              readonly description: 'Human-readable, safe-for-client message.';
             };
             readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
+              readonly type: 'integer';
+              readonly description: 'Suggested HTTP status code (hosts may override).';
             };
             readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+              readonly type: 'array';
+              readonly description: 'Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).';
               readonly items: {
-                readonly type: "object";
+                readonly type: 'object';
                 readonly properties: {
                   readonly path: {
-                    readonly type: "string";
+                    readonly type: 'string';
                     readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
                   };
                   readonly code: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly message: {
-                    readonly type: "string";
+                    readonly type: 'string';
                   };
                   readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+                    readonly type: 'object';
+                    readonly description: 'Non-PII per-detail diagnostics (safe to log + return).';
                   };
                 };
-                readonly required: readonly ["code", "message"];
+                readonly required: readonly ['code', 'message'];
               };
             };
             readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
+              readonly type: 'string';
+              readonly description: 'Request id for support lookups.';
             };
             readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
+              readonly type: 'object';
+              readonly description: 'Non-PII diagnostics (safe to log + return).';
             };
           };
-          readonly required: readonly ["code", "message"];
+          readonly required: readonly ['code', 'message'];
         };
       };
     };
@@ -1049,6 +1108,20 @@ declare function isJsonSchema(input: unknown): input is Record<string, unknown>;
  * Check if an object is a Zod schema (has `_zod` marker from Zod v4).
  */
 declare function isZodSchema(input: unknown): boolean;
+/**
+ * How `toJsonSchema` reacts when a Zod schema CANNOT be converted (zod not
+ * installed/loaded, zod v3, or `z.toJSONSchema()` threw):
+ *
+ * - `'throw'` — fail fast with an actionable error. Used by
+ *   `convertRouteSchema` (VALIDATION path): a schema that silently degrades
+ *   to `{ type: 'object' }` is validation switched off — the worst outcome
+ *   for a wire contract, worse than a boot failure.
+ * - `'warn'` (default) — log loudly, degrade to a permissive `{ type:
+ *   'object' }`. Used by doc-generation paths (OpenAPI extraction of
+ *   Better Auth endpoints etc.), where the schema is third-party and a doc
+ *   gap must not take the app down.
+ */
+type UnconvertibleMode = "warn" | "throw";
 /**
  * Convert any schema input to JSON Schema.
  *
@@ -1056,13 +1129,16 @@ declare function isZodSchema(input: unknown): boolean;
  * 1. `null`/`undefined` → `undefined`
  * 2. Already JSON Schema → pass through as-is (zero overhead)
  * 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
- * 4. Unrecognized object → return as-is (treat as opaque schema)
+ * 4. Zod v3 schema → unconvertible (actionable "upgrade to v4" error/warn)
+ * 5. Unrecognized object → return as-is (treat as opaque schema)
  *
- * @param input Schema (Zod, plain JSON Schema, or opaque object)
+ * @param input  Schema (Zod, plain JSON Schema, or opaque object)
  * @param target Output target — defaults to `draft-7` for Fastify compatibility.
  *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
+ * @param mode   Failure policy for unconvertible Zod schemas — see
+ *               {@link UnconvertibleMode}. Defaults to `'warn'`.
  */
-declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget): Record<string, unknown> | undefined;
+declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget, mode?: UnconvertibleMode): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
@@ -1399,4 +1475,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
  */
 declare function getUserId(user: UserLike | null | undefined): string | undefined;
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };