@hypequery/datasets 0.23.1 → 0.25.0

package/dist/utils/time-measure-values-sql.js

@@ -1,54 +1,51 @@
-import { GRAIN_FUNCTIONS } from '../constants.js';
-import { quoteSQLIdentifier } from '../sql-utils.js';
-import { addTimeSql as add, subtractTimeSql as subtract } from './time-arithmetic-sql.js';
-import { isCountAggregation, windowAggregateSql } from './window-aggregation-sql.js';
+import { isCountAggregation } from './count-aggregations.js';
 import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
 /** One row is emitted into each bounded window it contributes to. */
-function contributionSql(window, grain) {
-    const bucket = `${GRAIN_FUNCTIONS[grain]}(_hq_time)`;
+function contributionSql(dialect, window, grain) {
+    const bucket = dialect.truncateTime('_hq_time', grain);
     if (!window)
         return bucket;
     if (window.cumulative)
-        return `greatest(${bucket}, _hq_first)`;
+        return dialect.greatest(bucket, '_hq_first');
     let count;
     if (window.trailing) {
-        const end = add(bucket, window.trailing.amount, window.trailing.unit);
-        count = `dateDiff('${grain}', ${bucket}, ${end})`;
+        const end = dialect.addTime(bucket, window.trailing.amount, window.trailing.unit);
+        count = dialect.timeDiff(grain, bucket, end);
     }
     else if (window.toDate) {
-        const calendarStart = `${GRAIN_FUNCTIONS[window.toDate]}(_hq_time)`;
-        const end = add(calendarStart, 1, window.toDate);
-        count = `dateDiff('${grain}', ${bucket}, ${end})`;
+        const calendarStart = dialect.truncateTime('_hq_time', window.toDate);
+        const end = dialect.addTime(calendarStart, 1, window.toDate);
+        count = dialect.timeDiff(grain, bucket, end);
     }
     else {
         throw new Error('Window measure has no supported mode.');
     }
-    const fanoutGuard = `throwIf(${count} > 1000, 'A window row contributes to more than 1000 buckets.')`;
-    const calendarGuard = calendarBucketGuardSql(bucket, `${count} + ${fanoutGuard}`, grain);
-    const bucketIndices = `arrayJoin(range(toUInt64(${count} + ${fanoutGuard} + ${calendarGuard})))`;
-    return add(bucket, bucketIndices, grain);
+    const fanoutGuard = dialect.guard(`${count} > 1000`, 'A window row contributes to more than 1000 buckets.');
+    const calendarGuard = calendarBucketGuardSql(dialect, bucket, `${count} + ${fanoutGuard}`, grain);
+    const bucketIndices = dialect.seriesIndex(`${count} + ${fanoutGuard} + ${calendarGuard}`);
+    return dialect.addTime(bucket, bucketIndices, grain);
 }
-export function windowScanStartSql(window, grain) {
+export function windowScanStartSql(dialect, window, grain) {
     if (window.trailing)
-        return subtract(add('_hq_first', 1, grain), window.trailing.amount, window.trailing.unit);
+        return dialect.subtractTime(dialect.addTime('_hq_first', 1, grain), window.trailing.amount, window.trailing.unit);
     if (window.toDate)
-        return `${GRAIN_FUNCTIONS[window.toDate]}(_hq_first)`;
+        return dialect.truncateTime('_hq_first', window.toDate);
     throw new Error('Cumulative windows have unbounded history.');
 }
 /** Base measures respect partial endpoints; windows use entire contributing buckets. */
-export function windowMeasureRowsSql(window, axis) {
+export function windowMeasureRowsSql(dialect, window, axis) {
     const range = window ? '' : ` WHERE _hq_time ${axis.lowerInclusive ? '>=' : '>'} _hq_lower AND _hq_time ${axis.upperInclusive ? '<=' : '<'} _hq_upper`;
-    return `SELECT *, ${contributionSql(window, axis.grain)} AS _hq_period FROM _hq_scanned${range}`;
+    return `SELECT *, ${contributionSql(dialect, window, axis.grain)} AS _hq_period FROM _hq_scanned${range}`;
 }
 /** Fill dimension combinations, aggregate populations, and join measure values onto the series. */
-export function buildTimeMeasureValuesSql(dims, inputs, axis) {
+export function buildTimeMeasureValuesSql(dialect, dims, inputs, axis) {
     const ctes = [];
     const keys = dims.map(dimension => dimension.alias);
     const combinations = keys.length
         ? ` CROSS JOIN (SELECT DISTINCT ${keys.join(', ')} FROM _hq_scanned) AS _hq_combinations`
         : '';
     ctes.push(`_hq_skeleton AS (SELECT * FROM _hq_series${combinations})`);
-    const projections = ['s._hq_period AS period', ...dims.map(dimension => `s.${dimension.alias} AS ${quoteSQLIdentifier(dimension.name)}`)];
+    const projections = ['s._hq_period AS period', ...dims.map(dimension => `s.${dimension.alias} AS ${dialect.quoteIdentifier(dimension.name)}`)];
     const joins = [];
     let index = 0;
     for (const input of inputs) {
@@ -58,28 +55,28 @@ export function buildTimeMeasureValuesSql(dims, inputs, axis) {
         const aggregate = `_hq_agg${index}`;
         ctes.push(...rowCtes, `${fan} AS (${rowsSql})`);
         // toNullable makes unmatched LEFT JOIN values NULL regardless of join_use_nulls.
-        const expression = windowAggregateSql(base.definition, base.value, base.arg);
+        const expression = dialect.windowAggregate(base.definition, base.value, base.arg);
         const groupColumns = `_hq_period${keys.length ? `, ${keys.join(', ')}` : ''}`;
         const outputRange = restrictToAxis ? ' WHERE _hq_period BETWEEN _hq_first AND _hq_last' : '';
         const trailingRange = window?.trailing
-            ? ` AND _hq_time >= ${subtract(add('_hq_period', 1, axis.grain), window.trailing.amount, window.trailing.unit)}`
+            ? ` AND _hq_time >= ${dialect.subtractTime(dialect.addTime('_hq_period', 1, axis.grain), window.trailing.amount, window.trailing.unit)}`
             : '';
-        const aggregationSql = `SELECT ${groupColumns}, toNullable(${expression}) AS ${output}`
+        const aggregationSql = `SELECT ${groupColumns}, ${dialect.toNullable(expression)} AS ${output}`
             + ` FROM ${fan}${outputRange}${trailingRange} GROUP BY ${groupColumns}`;
         ctes.push(`${aggregate} AS (${aggregationSql})`);
         const alias = `m${index}`;
-        const condition = [`s._hq_period = ${alias}._hq_period`, ...keys.map(key => `isNotDistinctFrom(s.${key}, ${alias}.${key})`)];
+        const condition = [`s._hq_period = ${alias}._hq_period`, ...keys.map(key => dialect.isNotDistinctFrom(`s.${key}`, `${alias}.${key}`))];
         joins.push(`LEFT JOIN ${aggregate} AS ${alias} ON ${condition.join(' AND ')}`);
         let value = `${alias}.${output}`;
         if (window?.cumulative) {
             const operation = base.definition.aggregation === 'count' ? 'sum' : base.definition.aggregation;
             const partition = keys.length ? `PARTITION BY ${keys.map(key => `s.${key}`).join(', ')} ` : '';
             const frame = `${partition}ORDER BY s._hq_period ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`;
-            value = `${operation}OrNull(${value}) OVER (${frame})`;
+            value = `${dialect.reaggregate(operation, value)} OVER (${frame})`;
         }
         if (isCountAggregation(base.definition))
             value = `coalesce(${value}, 0)`;
-        projections.push(`${value} AS ${quoteSQLIdentifier(name)}`);
+        projections.push(`${value} AS ${dialect.quoteIdentifier(name)}`);
         index++;
     }
     ctes.push(`_hq_values AS (SELECT ${projections.join(', ')} FROM _hq_skeleton AS s ${joins.join(' ')})`);

package/dist/utils/timestamp-instants.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedTimeBound } from './time-axis-bounds.js';
+/**
+ * Parse an RFC 3339 instant: ISO 8601 text carrying `Z` or a numeric offset,
+ * the form `Date.prototype.toISOString` produces. Offset-free text is a local
+ * reading rather than an instant and yields undefined, as does anything that
+ * is not a timestamp.
+ */
+export declare function parseTimestampInstant(value: unknown): ParsedTimeBound | undefined;
+/**
+ * The wall clock an instant shows in `timezone`, spelled
+ * `YYYY-MM-DD hh:mm:ss[.fraction]`: the form ClickHouse reads as local time in
+ * the zone of the DateTime64 it is compared against. Offsets are whole
+ * minutes, so the authored sub-second digits survive unchanged; a zero
+ * fraction is dropped.
+ */
+export declare function instantWallClock(instant: ParsedTimeBound, timezone: string): string;
+//# sourceMappingURL=timestamp-instants.d.ts.map

package/dist/utils/timestamp-instants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-instants.d.ts","sourceRoot":"","sources":["../../src/utils/timestamp-instants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAGjF;AAUD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASnF"}

package/dist/utils/timestamp-instants.js

@@ -0,0 +1,34 @@
+import { parseTimeBound } from './time-axis-bounds.js';
+/**
+ * Parse an RFC 3339 instant: ISO 8601 text carrying `Z` or a numeric offset,
+ * the form `Date.prototype.toISOString` produces. Offset-free text is a local
+ * reading rather than an instant and yields undefined, as does anything that
+ * is not a timestamp.
+ */
+export function parseTimestampInstant(value) {
+    const instant = parseTimeBound(value);
+    return instant?.hasOffset ? instant : undefined;
+}
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const CLOCK_PARTS = {
+    hourCycle: 'h23',
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit',
+};
+/**
+ * The wall clock an instant shows in `timezone`, spelled
+ * `YYYY-MM-DD hh:mm:ss[.fraction]`: the form ClickHouse reads as local time in
+ * the zone of the DateTime64 it is compared against. Offsets are whole
+ * minutes, so the authored sub-second digits survive unchanged; a zero
+ * fraction is dropped.
+ */
+export function instantWallClock(instant, timezone) {
+    const parts = new Intl.DateTimeFormat('en-US', { ...CLOCK_PARTS, timeZone: timezone })
+        .formatToParts(new Date(instant.milliseconds));
+    const part = (type) => parts.find(entry => entry.type === type)?.value ?? '';
+    const date = `${part('year').padStart(4, '0')}-${part('month')}-${part('day')}`;
+    const clock = `${part('hour')}:${part('minute')}:${part('second')}`;
+    const remainder = ((instant.nanoseconds % NANOSECONDS_PER_SECOND) + NANOSECONDS_PER_SECOND) % NANOSECONDS_PER_SECOND;
+    const fraction = remainder === 0n ? '' : `.${remainder.toString().padStart(9, '0').replace(/0+$/, '')}`;
+    return `${date} ${clock}${fraction}`;
+}

package/dist/utils/timestamp-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * True for the timestamp text a filter may bind: a real calendar date, or a
+ * date and time with seconds, optionally with a fraction and `Z`/offset.
+ *
+ * ClickHouse reads an invalid `DateTime64` parameter as some other instant
+ * instead of refusing it (`2026-13-45` becomes 1900-01-01, `2026-02-30`
+ * rolls into March, digits are read as Unix seconds), and refuses a time
+ * without seconds, so anything else is rejected before planning. This is
+ * the same rule as the Python planner's.
+ */
+export declare function isTimestampText(value: unknown): value is string;
+//# sourceMappingURL=timestamp-text.d.ts.map

package/dist/utils/timestamp-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-text.d.ts","sourceRoot":"","sources":["../../src/utils/timestamp-text.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK/D"}

package/dist/utils/timestamp-text.js

@@ -0,0 +1,18 @@
+import { parseTimeBound } from './time-axis-bounds.js';
+/**
+ * True for the timestamp text a filter may bind: a real calendar date, or a
+ * date and time with seconds, optionally with a fraction and `Z`/offset.
+ *
+ * ClickHouse reads an invalid `DateTime64` parameter as some other instant
+ * instead of refusing it (`2026-13-45` becomes 1900-01-01, `2026-02-30`
+ * rolls into March, digits are read as Unix seconds), and refuses a time
+ * without seconds, so anything else is rejected before planning. This is
+ * the same rule as the Python planner's.
+ */
+export function isTimestampText(value) {
+    const parsed = parseTimeBound(value);
+    if (!parsed)
+        return false;
+    const time = parsed.text.slice(10);
+    return time === '' || /^[T ]\d{2}:\d{2}:\d{2}/.test(time);
+}

package/dist/utils/zod-json-schema.d.ts

@@ -0,0 +1,8 @@
+import { type AnyZodSchema } from './zod-schema-version.js';
+/**
+ * Draft-07 JSON Schema for a Zod 3 or Zod 4 schema, describing what a caller
+ * may send. `zod-to-json-schema` only reads Zod 3 (it returns an empty schema
+ * for Zod 4), and Zod 4 ships its own generator.
+ */
+export declare function zodToDraft7JsonSchema(schema: AnyZodSchema): Record<string, unknown>;
+//# sourceMappingURL=zod-json-schema.d.ts.map

package/dist/utils/zod-json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-json-schema.d.ts","sourceRoot":"","sources":["../../src/utils/zod-json-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASnF"}

package/dist/utils/zod-json-schema.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { isZod4Schema } from './zod-schema-version.js';
+/**
+ * Draft-07 JSON Schema for a Zod 3 or Zod 4 schema, describing what a caller
+ * may send. `zod-to-json-schema` only reads Zod 3 (it returns an empty schema
+ * for Zod 4), and Zod 4 ships its own generator.
+ */
+export function zodToDraft7JsonSchema(schema) {
+    if (isZod4Schema(schema)) {
+        return z.toJSONSchema(schema, {
+            target: 'draft-7',
+            io: 'input',
+            unrepresentable: 'any',
+        });
+    }
+    return zodToJsonSchema(schema, { target: 'jsonSchema7', $refStrategy: 'none' });
+}

package/dist/utils/zod-schema-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Any Zod schema, from either major version or another installed copy of Zod.
+ *
+ * Structural on purpose: a caller's schema built with their own `zod@3` is not
+ * assignable to this package's `zod@4` types, but both carry their definition
+ * on `_def` (v3) or `_zod` (v4).
+ */
+export type AnyZodSchema = {
+    readonly _def: unknown;
+} | {
+    readonly _zod: unknown;
+};
+/** Zod 4 (classic or mini) keeps its internals on `_zod`; Zod 3 has none. */
+export declare function isZod4Schema(schema: unknown): schema is {
+    readonly _zod: {
+        readonly def: Record<string, any>;
+    };
+};
+//# sourceMappingURL=zod-schema-version.d.ts.map

package/dist/utils/zod-schema-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-schema-version.d.ts","sourceRoot":"","sources":["../../src/utils/zod-schema-version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnF,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAA;CAAE,CAIhH"}

package/dist/utils/zod-schema-version.js

@@ -0,0 +1,6 @@
+/** Zod 4 (classic or mini) keeps its internals on `_zod`; Zod 3 has none. */
+export function isZod4Schema(schema) {
+    return typeof schema === 'object'
+        && schema !== null
+        && typeof schema._zod === 'object';
+}

package/dist/utils/zod-v3-protocol-schema.d.ts

@@ -0,0 +1,10 @@
+import { type ProtocolSchemaDraft } from './protocol-schema-conversion.js';
+/** A Zod 3 schema, read through its `_def`. Callers may hold any 3.x copy of Zod. */
+type ZodV3Schema = {
+    readonly _def: Record<string, any>;
+    readonly description?: string;
+};
+/** Converts the portable subset of a Zod 3 schema into an RFC 0004 draft. */
+export declare function convertZodV3Schema(schema: ZodV3Schema, path: string): ProtocolSchemaDraft;
+export {};
+//# sourceMappingURL=zod-v3-protocol-schema.d.ts.map

package/dist/utils/zod-v3-protocol-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-v3-protocol-schema.d.ts","sourceRoot":"","sources":["../../src/utils/zod-v3-protocol-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AAEzC,qFAAqF;AACrF,KAAK,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA8DzF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAyGzF"}

package/dist/utils/zod-v3-protocol-schema.js

@@ -0,0 +1,164 @@
+import { ProtocolSchemaAdapterError, annotate, canonicalValue, nativeEnumValues, withDefault, } from './protocol-schema-conversion.js';
+function typeName(schema) {
+    return String(schema?._def?.typeName ?? 'Unknown');
+}
+function convertString(schema, path) {
+    const result = { kind: 'string' };
+    for (const check of schema._def.checks) {
+        switch (check.kind) {
+            case 'min':
+                result.minLength = check.value;
+                break;
+            case 'max':
+                result.maxLength = check.value;
+                break;
+            case 'length':
+                result.minLength = check.value;
+                result.maxLength = check.value;
+                break;
+            default:
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod string check "${String(check.kind)}"`, path);
+        }
+    }
+    return annotate(schema.description, result);
+}
+function convertNumber(schema, path) {
+    const result = { kind: 'number' };
+    for (const check of schema._def.checks) {
+        switch (check.kind) {
+            case 'int':
+                result.kind = 'integer';
+                break;
+            case 'min':
+                result[check.inclusive === false ? 'exclusiveMinimum' : 'minimum'] = check.value;
+                break;
+            case 'max':
+                result[check.inclusive === false ? 'exclusiveMaximum' : 'maximum'] = check.value;
+                break;
+            case 'finite':
+                break;
+            default:
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.kind)}"`, path);
+        }
+    }
+    return annotate(schema.description, result);
+}
+function isOptionalProperty(schema) {
+    const name = typeName(schema);
+    return name === 'ZodOptional' || name === 'ZodDefault';
+}
+function isUnconstrainedRecordKey(schema) {
+    if (schema === undefined || typeName(schema) !== 'ZodString')
+        return false;
+    const definition = schema._def;
+    return Array.isArray(definition.checks)
+        && definition.checks.length === 0
+        && definition.coerce !== true;
+}
+/** Converts the portable subset of a Zod 3 schema into an RFC 0004 draft. */
+export function convertZodV3Schema(schema, path) {
+    const definition = schema._def;
+    const done = (result) => annotate(schema.description, result);
+    switch (typeName(schema)) {
+        case 'ZodAny':
+        case 'ZodUnknown':
+            return done({ kind: 'any' });
+        case 'ZodNever':
+        case 'ZodVoid':
+        case 'ZodUndefined':
+            return done({ kind: 'void' });
+        case 'ZodNull':
+            return done({ kind: 'null' });
+        case 'ZodBoolean':
+            return done({ kind: 'boolean' });
+        case 'ZodString':
+            return convertString(schema, path);
+        case 'ZodNumber':
+            return convertNumber(schema, path);
+        case 'ZodLiteral':
+            return done({ kind: 'literal', value: canonicalValue(definition.value, `${path}.value`) });
+        case 'ZodEnum':
+            return done({ kind: 'enum', values: [...definition.values] });
+        case 'ZodNativeEnum':
+            return done({ kind: 'enum', values: nativeEnumValues(definition.values) });
+        case 'ZodArray': {
+            const result = {
+                kind: 'array',
+                items: convertZodV3Schema(definition.type, `${path}.items`),
+            };
+            if (definition.minLength?.value !== undefined)
+                result.minItems = definition.minLength.value;
+            if (definition.maxLength?.value !== undefined)
+                result.maxItems = definition.maxLength.value;
+            if (definition.exactLength?.value !== undefined) {
+                result.minItems = definition.exactLength.value;
+                result.maxItems = definition.exactLength.value;
+            }
+            return done(result);
+        }
+        case 'ZodObject': {
+            if (typeName(definition.catchall) !== 'ZodNever') {
+                throw new ProtocolSchemaAdapterError('Unsupported Zod object catchall', path);
+            }
+            const shape = definition.shape();
+            return done({
+                kind: 'object',
+                properties: Object.fromEntries(Object.entries(shape).map(([name, property]) => [
+                    name,
+                    convertZodV3Schema(property, `${path}.properties.${name}`),
+                ])),
+                required: Object.entries(shape)
+                    .filter(([, property]) => !isOptionalProperty(property))
+                    .map(([name]) => name),
+                unknownProperties: definition.unknownKeys === 'passthrough'
+                    ? 'preserve'
+                    : definition.unknownKeys === 'strict'
+                        ? 'reject'
+                        : 'strip',
+            });
+        }
+        case 'ZodRecord':
+            if (!isUnconstrainedRecordKey(definition.keyType)) {
+                throw new ProtocolSchemaAdapterError('Unsupported constrained Zod record key', path);
+            }
+            return done({ kind: 'record', values: convertZodV3Schema(definition.valueType, `${path}.values`) });
+        case 'ZodUnion':
+            return done({
+                kind: 'union',
+                variants: definition.options.map((option, index) => convertZodV3Schema(option, `${path}.variants[${index}]`)),
+            });
+        case 'ZodDiscriminatedUnion':
+            // RFC 0004 has no separate discriminator index. Converting every option
+            // drops only Zod's lookup metadata; each object's literal discriminator
+            // property remains part of its protocol variant.
+            return done({
+                kind: 'union',
+                variants: [...definition.options.values()].map((option, index) => convertZodV3Schema(option, `${path}.variants[${index}]`)),
+            });
+        case 'ZodNullable':
+            return done({
+                kind: 'union',
+                variants: [convertZodV3Schema(definition.innerType, `${path}.variants[0]`), { kind: 'null' }],
+            });
+        case 'ZodOptional':
+            return done(convertZodV3Schema(definition.innerType, path));
+        case 'ZodDefault':
+            return done(withDefault(convertZodV3Schema(definition.innerType, path), definition.defaultValue(), path));
+        case 'ZodBranded':
+            return done(convertZodV3Schema(definition.type, path));
+        case 'ZodReadonly':
+            return done(convertZodV3Schema(definition.innerType, path));
+        case 'ZodEffects': {
+            const effectType = String(definition.effect?.type ?? 'unknown');
+            if (effectType !== 'refinement') {
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod effect "${effectType}"`, path);
+            }
+            // A refinement preserves the wrapped schema's input and output shape.
+            // The rule itself remains enforced by Zod, but cannot be advertised by
+            // ProtocolSchema (for example, a cross-field selection requirement).
+            return done(convertZodV3Schema(definition.schema, path));
+        }
+        default:
+            throw new ProtocolSchemaAdapterError(`Unsupported Zod type "${typeName(schema)}"`, path);
+    }
+}

package/dist/utils/zod-v4-protocol-schema.d.ts

@@ -0,0 +1,12 @@
+import { type ProtocolSchemaDraft } from './protocol-schema-conversion.js';
+/** A Zod 4 schema, read through `_zod.def`. Classic schemas also expose `description`. */
+type ZodV4Schema = {
+    readonly _zod: {
+        readonly def: Record<string, any>;
+    };
+    readonly description?: string;
+};
+/** Converts the portable subset of a Zod 4 schema into an RFC 0004 draft. */
+export declare function convertZodV4Schema(schema: ZodV4Schema, path: string): ProtocolSchemaDraft;
+export {};
+//# sourceMappingURL=zod-v4-protocol-schema.d.ts.map

package/dist/utils/zod-v4-protocol-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-v4-protocol-schema.d.ts","sourceRoot":"","sources":["../../src/utils/zod-v4-protocol-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AAEzC,0FAA0F;AAC1F,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAwHF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CA4EzF"}

package/dist/utils/zod-v4-protocol-schema.js

@@ -0,0 +1,171 @@
+import { ProtocolSchemaAdapterError, annotate, canonicalValue, nativeEnumValues, withDefault, } from './protocol-schema-conversion.js';
+const INTEGER_FORMATS = new Set(['safeint', 'int32', 'uint32']);
+function typeOf(schema) {
+    return String(schema?._zod?.def?.type ?? 'unknown');
+}
+function checksOf(schema) {
+    return (schema._zod.def.checks ?? []).map(check => check._zod.def);
+}
+/** Zod 4 stores `.refine()` as a `custom` check on the schema it refines. */
+function isRefinement(check) {
+    return check.check === 'custom';
+}
+function applyLengthChecks(schema, result, keys, label, path) {
+    for (const check of checksOf(schema)) {
+        switch (check.check) {
+            case 'min_length':
+                result[keys.min] = check.minimum;
+                break;
+            case 'max_length':
+                result[keys.max] = check.maximum;
+                break;
+            case 'length_equals':
+                result[keys.min] = check.length;
+                result[keys.max] = check.length;
+                break;
+            default:
+                if (isRefinement(check))
+                    break;
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod ${label} check "${String(check.format ?? check.check)}"`, path);
+        }
+    }
+    return result;
+}
+function convertNumber(schema, path) {
+    const result = { kind: 'number' };
+    for (const check of checksOf(schema)) {
+        switch (check.check) {
+            case 'number_format':
+                if (!INTEGER_FORMATS.has(check.format)) {
+                    throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.format)}"`, path);
+                }
+                result.kind = 'integer';
+                break;
+            case 'greater_than':
+                result[check.inclusive ? 'minimum' : 'exclusiveMinimum'] = check.value;
+                break;
+            case 'less_than':
+                result[check.inclusive ? 'maximum' : 'exclusiveMaximum'] = check.value;
+                break;
+            default:
+                if (isRefinement(check))
+                    break;
+                throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.check)}"`, path);
+        }
+    }
+    return result;
+}
+function isOptionalProperty(schema) {
+    const type = typeOf(schema);
+    return type === 'optional' || type === 'default';
+}
+function isUnconstrainedRecordKey(schema) {
+    return schema !== undefined
+        && typeOf(schema) === 'string'
+        && checksOf(schema).length === 0
+        && schema._zod.def.coerce !== true;
+}
+function unknownProperties(catchall, path) {
+    if (catchall === undefined)
+        return 'strip';
+    switch (typeOf(catchall)) {
+        case 'never':
+            return 'reject';
+        case 'unknown':
+            return 'preserve';
+        default:
+            throw new ProtocolSchemaAdapterError('Unsupported Zod object catchall', path);
+    }
+}
+function literal(values, path) {
+    if (values.length === 1) {
+        return { kind: 'literal', value: canonicalValue(values[0], `${path}.value`) };
+    }
+    return {
+        kind: 'union',
+        variants: values.map((value, index) => ({
+            kind: 'literal',
+            value: canonicalValue(value, `${path}.variants[${index}].value`),
+        })),
+    };
+}
+/**
+ * Zod 4 has no effects wrapper: a transform is a pipe into a `transform`, and
+ * a preprocessor is a pipe out of one. Neither preserves the advertised shape.
+ */
+function pipeEffect(definition) {
+    if (typeOf(definition.out) === 'transform')
+        return 'transform';
+    if (typeOf(definition.in) === 'transform')
+        return 'preprocess';
+    return 'pipe';
+}
+/** Converts the portable subset of a Zod 4 schema into an RFC 0004 draft. */
+export function convertZodV4Schema(schema, path) {
+    const definition = schema._zod.def;
+    const done = (result) => annotate(schema.description, result);
+    switch (typeOf(schema)) {
+        case 'any':
+        case 'unknown':
+            return done({ kind: 'any' });
+        case 'never':
+        case 'void':
+        case 'undefined':
+            return done({ kind: 'void' });
+        case 'null':
+            return done({ kind: 'null' });
+        case 'boolean':
+            return done({ kind: 'boolean' });
+        case 'string':
+            return done(applyLengthChecks(schema, { kind: 'string' }, { min: 'minLength', max: 'maxLength' }, 'string', path));
+        case 'number':
+            return done(convertNumber(schema, path));
+        case 'literal':
+            return done(literal(definition.values, path));
+        case 'enum':
+            return done({ kind: 'enum', values: nativeEnumValues(definition.entries) });
+        case 'array':
+            return done(applyLengthChecks(schema, { kind: 'array', items: convertZodV4Schema(definition.element, `${path}.items`) }, { min: 'minItems', max: 'maxItems' }, 'array', path));
+        case 'object': {
+            const policy = unknownProperties(definition.catchall, path);
+            const shape = definition.shape;
+            return done({
+                kind: 'object',
+                properties: Object.fromEntries(Object.entries(shape).map(([name, property]) => [
+                    name,
+                    convertZodV4Schema(property, `${path}.properties.${name}`),
+                ])),
+                required: Object.entries(shape)
+                    .filter(([, property]) => !isOptionalProperty(property))
+                    .map(([name]) => name),
+                unknownProperties: policy,
+            });
+        }
+        case 'record':
+            if (!isUnconstrainedRecordKey(definition.keyType)) {
+                throw new ProtocolSchemaAdapterError('Unsupported constrained Zod record key', path);
+            }
+            return done({ kind: 'record', values: convertZodV4Schema(definition.valueType, `${path}.values`) });
+        case 'union':
+            // A discriminated union is a union with a `discriminator`. RFC 0004 has
+            // no discriminator index; each variant keeps its literal property.
+            return done({
+                kind: 'union',
+                variants: definition.options.map((option, index) => convertZodV4Schema(option, `${path}.variants[${index}]`)),
+            });
+        case 'nullable':
+            return done({
+                kind: 'union',
+                variants: [convertZodV4Schema(definition.innerType, `${path}.variants[0]`), { kind: 'null' }],
+            });
+        case 'optional':
+        case 'readonly':
+            return done(convertZodV4Schema(definition.innerType, path));
+        case 'default':
+            return done(withDefault(convertZodV4Schema(definition.innerType, path), definition.defaultValue, path));
+        case 'pipe':
+            throw new ProtocolSchemaAdapterError(`Unsupported Zod effect "${pipeEffect(definition)}"`, path);
+        default:
+            throw new ProtocolSchemaAdapterError(`Unsupported Zod type "${typeOf(schema)}"`, path);
+    }
+}

package/dist/validation.d.ts

@@ -17,6 +17,13 @@ export interface ValidationResult {
  * @returns true if the value matches the field type
  */
 export declare function matchesFieldType(fieldType: FieldType, value: unknown): boolean;
+/** True when a list holds both instants (`Z` or an offset) and offset-free timestamps. */
+export declare function mixesInstantsAndLocalTimes(values: readonly unknown[]): boolean;
+/**
+ * An `in` list is one predicate, so every member is read in the same zone:
+ * an instant and a local time cannot share one without changing a meaning.
+ */
+export declare function mixedInstantListError(field: string): string;
 /**
  * Validates a filter value against the expected field type.
  *