@aeye/core 0.5.3 → 0.6.0

package/dist/schema/cycle-breaker.js

@@ -0,0 +1,157 @@
+import z from 'zod';
+import { buildAnyValueSchema } from './any-value';
+/**
+ * Build the inline placeholder used in place of a cyclic `$ref` for
+ * descriptors with `supportsRecursion: false`. Inspects the recursive zod
+ * `schema` and emits a JSON-Schema node whose top-level shape matches it
+ * (number → `{type: 'number'}`, array → `{type: 'array', items: ...}`, union
+ * → `{anyOf: [...]}`, etc.) so the LLM still knows what JSON value to send
+ * at the cycle position. One level of structural fidelity, then bottoms out
+ * at the descriptor's flat "any" encoding.
+ */
+export function buildCycleBreakerSchema(schema, refId, descriptor) {
+    const placeholder = genericize(schema, descriptor, 1);
+    // The description is MODEL-FACING, so it must not point at a `$defs` entry
+    // this dialect never emits — under `allowDefsRef: false` there is no `$defs`
+    // section at all, and telling the model to look at one is a lie about the
+    // document it was handed. Name the recursion instead.
+    const description = descriptor.allowDefsRef
+        ? `Would recursively reference #/$defs/${refId}`
+        : `Recursive reference to '${refId}' — repeat this shape here`;
+    return { ...placeholder, description };
+}
+/**
+ * Reduce a zod schema to a JSON-Schema node carrying its top-level shape
+ * class (string / number / array / object / union / …) without nested
+ * constraints. Used by the cycle-breaker so the placeholder at a recursive
+ * position matches the JSON value the LLM is supposed to emit.
+ *
+ * `depth` controls how far structural fidelity flows into the *recursive*
+ * containers (arrays of arrays, unions of unions). Closed-form schemas
+ * (primitives, objects, tuples) ignore depth — they have no further
+ * substructure to walk and are always safe to emit verbatim.
+ * - `depth >= 1`: arrays carry their `items`, unions carry their branches,
+ *   each recursing at `depth - 1`.
+ * - `depth === 0`: arrays collapse to bare `{type: 'array'}`, unions
+ *   collapse to the descriptor's flat any encoding. Stops the walk before
+ *   it can re-traverse the cycle that triggered the call.
+ *
+ * Depth is hardcoded to 1 by `buildCycleBreakerSchema`. That's enough for
+ * "a list of objects should be a list of records" and prevents infinite
+ * recursion on `Array<Array<Self>>` / `Union<Union<Self>>` shapes.
+ */
+function genericize(schema, descriptor, depth) {
+    // Unwrap transparent wrappers — recurse at the same depth because the
+    // wrapper itself doesn't add a structural level.
+    if (schema instanceof z.ZodLazy) {
+        return genericize(schema.def.getter(), descriptor, depth);
+    }
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+        return genericize(schema.unwrap(), descriptor, depth);
+    }
+    if (schema instanceof z.ZodDefault) {
+        return genericize(schema.def.innerType, descriptor, depth);
+    }
+    if (schema instanceof z.ZodCodec) {
+        return genericize(schema.def.in, descriptor, depth);
+    }
+    if (schema instanceof z.ZodPipe) {
+        return genericize(schema.def.in, descriptor, depth);
+    }
+    // Primitive leaves and string-flavored types — no substructure, depth
+    // irrelevant. The LLM gets a precise type signal.
+    if (schema instanceof z.ZodString)
+        return { type: 'string' };
+    if (schema instanceof z.ZodNumber)
+        return { type: 'number' };
+    if (schema instanceof z.ZodBigInt)
+        return { type: 'number' };
+    if (schema instanceof z.ZodBoolean)
+        return { type: 'boolean' };
+    if (schema instanceof z.ZodNull)
+        return { type: 'null' };
+    if (schema instanceof z.ZodUndefined)
+        return { type: 'null' };
+    if (schema instanceof z.ZodDate ||
+        schema instanceof z.ZodISODateTime ||
+        schema instanceof z.ZodISODate ||
+        schema instanceof z.ZodISOTime ||
+        schema instanceof z.ZodISODuration ||
+        schema instanceof z.ZodEmail ||
+        schema instanceof z.ZodIPv4 ||
+        schema instanceof z.ZodIPv6 ||
+        schema instanceof z.ZodUUID ||
+        schema instanceof z.ZodTemplateLiteral) {
+        return { type: 'string' };
+    }
+    if (schema instanceof z.ZodLiteral) {
+        // ZodLiteral can carry one or more values; pick the first that maps to
+        // a JSON primitive type, else fall back to flat any.
+        const v = Array.from(schema.values).find((x) => x === null || typeof x === 'string' || typeof x === 'number' || typeof x === 'boolean');
+        if (v === null)
+            return { type: 'null' };
+        if (typeof v === 'string')
+            return { type: 'string' };
+        if (typeof v === 'number')
+            return { type: 'number' };
+        if (typeof v === 'boolean')
+            return { type: 'boolean' };
+        return buildAnyValueSchema(descriptor);
+    }
+    if (schema instanceof z.ZodEnum) {
+        const numericValues = Object.values(schema.def.entries).filter((v) => typeof v === 'number');
+        const values = Object.entries(schema.def.entries)
+            .filter(([k]) => numericValues.indexOf(+k) === -1)
+            .map(([, v]) => v);
+        if (values.every((v) => typeof v === 'string'))
+            return { type: 'string' };
+        if (values.every((v) => typeof v === 'number'))
+            return { type: 'number' };
+        return buildAnyValueSchema(descriptor);
+    }
+    // Closed-form containers — no nested schema to walk, safe at any depth.
+    if (schema instanceof z.ZodObject ||
+        schema instanceof z.ZodRecord ||
+        schema instanceof z.ZodIntersection) {
+        return { type: 'object', additionalProperties: true };
+    }
+    if (schema instanceof z.ZodTuple) {
+        // Heterogeneous positional shape — drop items, keep array hint.
+        return { type: 'array' };
+    }
+    // Recursive containers — depth gates further structural fidelity.
+    if (schema instanceof z.ZodArray) {
+        if (depth <= 0)
+            return { type: 'array' };
+        return { type: 'array', items: genericize(schema.element, descriptor, depth - 1) };
+    }
+    if (schema instanceof z.ZodUnion || schema instanceof z.ZodDiscriminatedUnion) {
+        if (depth <= 0)
+            return buildAnyValueSchema(descriptor);
+        const options = schema.options;
+        const branches = options.map((opt) => genericize(opt, descriptor, depth - 1));
+        const unique = uniqueByJSON(branches);
+        return unique.length === 1 ? unique[0] : { anyOf: unique };
+    }
+    // ZodAny / ZodUnknown / ZodTransform / anything we don't recognize —
+    // emit the descriptor's any encoding. Safer than guessing.
+    return buildAnyValueSchema(descriptor);
+}
+/**
+ * Dedupe an array of JSONSchema nodes by structural (JSON-stringified)
+ * equality. Order-preserving: the first occurrence wins. Used by
+ * `genericize` to collapse `union<T, T>` placeholders into a single branch.
+ */
+function uniqueByJSON(nodes) {
+    const seen = new Set();
+    const out = [];
+    for (const node of nodes) {
+        const key = JSON.stringify(node);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(node);
+    }
+    return out;
+}
+//# sourceMappingURL=cycle-breaker.js.map

package/dist/schema/cycle-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-breaker.js","sourceRoot":"","sources":["../../src/schema/cycle-breaker.ts"],"names":[],"mappings":"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"}

package/dist/schema/decode.d.ts

@@ -0,0 +1,31 @@
+import z from 'zod';
+import type { FormatDescriptor } from './descriptor';
+/**
+ * Produce a NON-FAILING variant of `schema` that keeps every transform
+ * (`preprocess`, `codec`, `pipe`, `transform`) but drops validation. Parsing
+ * a wire value through the result runs the decode preprocesses installed by
+ * `strictify` (array-of-pairs → record, numeric-key object → tuple, null →
+ * undefined) and yields the conceptual value, without ever rejecting.
+ *
+ * Recursion (`z.lazy` self-reference) is handled with a per-call memo map: an
+ * in-flight node is recorded as a thunk and re-encounters resolve to
+ * `z.lazy(thunk)`, so a self-referential schema relaxes in finite time and
+ * never infinite-loops.
+ */
+export declare function relaxValidation(schema: z.ZodType): z.ZodType;
+/**
+ * DECODE a model's wire `value` back to the conceptual shape a custom parser
+ * expects — symmetric with how `strictify` ENCODEs the request for the wire.
+ *
+ * Runs the descriptor's decode transforms (via `relaxValidation(strictify(...))`)
+ * without imposing validation, so array-of-pairs records, numeric-key tuples,
+ * and null-for-optional fields are normalized before a provider-agnostic
+ * custom parser sees them. Best-effort: NEVER throws — if the relaxed decoder
+ * can't parse the value it is returned unchanged.
+ *
+ * @param schema - the PRE-strictify conceptual schema (strictify runs internally)
+ * @param value - the model's raw wire value (already `JSON.parse`d)
+ * @param descriptor - the wire dialect the request was encoded with
+ */
+export declare function decodeWire(schema: z.ZodType, value: unknown, descriptor: FormatDescriptor): unknown;
+//# sourceMappingURL=decode.d.ts.map

package/dist/schema/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/schema/decode.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAuKrD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAmB5D;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAanG"}

package/dist/schema/decode.js

@@ -0,0 +1,207 @@
+import z from 'zod';
+import { strictify } from './strictify';
+// ============================================================================
+// Wire → conceptual DECODE (symmetric with strictify's conceptual → wire ENCODE)
+//
+// `strictify` installs decode preprocesses (array-of-pairs → record,
+// numeric-key object → tuple, null → undefined for optionals, …) that only
+// run when Zod VALIDATES a value. A custom `parse` hook REPLACES Zod
+// validation, so it never triggers those preprocesses — it would otherwise
+// see the raw provider wire shape.
+//
+// `relaxValidation` turns a (strictified) schema into a NON-FAILING variant
+// that KEEPS every transform but DROPS validation, so we can run it purely to
+// execute the decode preprocesses and hand a custom parser the CONCEPTUAL
+// value. `decodeWire` ties it together (strictify → relax → safeParse,
+// best-effort).
+// ============================================================================
+/**
+ * Rebuild a `ZodObject` for the relaxed decoder.
+ *
+ * - Recurses each field through `relax` (so nested transforms still run).
+ * - `forceOptional`: when true every field becomes optional (max leniency —
+ *   used everywhere EXCEPT union options). When false the field keeps its own
+ *   optionality (used for union-option objects, where a required field is the
+ *   discriminating signal that lets the union pick the right branch).
+ * - `loose`: when true (default) unknown keys pass straight through; when
+ *   false the object STRIPS unknown keys. Intersection sides use `false` so
+ *   each half only claims its own keys and the two halves merge without an
+ *   "unmergable intersection" conflict (a loose side would echo the other
+ *   half's raw key and collide with that half's transformed value).
+ */
+function relaxObjectShape(schema, relax, forceOptional, loose = true) {
+    const shape = {};
+    for (const key in schema.shape) {
+        const relaxed = relax(schema.shape[key]);
+        shape[key] = forceOptional ? relaxed.optional() : relaxed;
+    }
+    const obj = z.object(shape);
+    return loose ? obj.loose() : obj;
+}
+/**
+ * Relax one side of an intersection. Object sides are rebuilt STRIP (not
+ * loose) so the two halves merge cleanly (see `relaxObjectShape`'s `loose`
+ * note); everything else relaxes normally.
+ */
+function relaxIntersectionSide(schema, relax) {
+    if (schema instanceof z.ZodObject) {
+        return relaxObjectShape(schema, relax, /* forceOptional */ true, /* loose */ false);
+    }
+    return relax(schema);
+}
+/**
+ * Relax the options of a union (plain OR discriminated — the latter is a
+ * subclass of `ZodUnion` in Zod v4, so a single path covers both).
+ *
+ * Object options are rebuilt with their ORIGINAL requiredness preserved
+ * (`forceOptional: false`) so the union can discriminate by required-field
+ * presence and run the matching option's decode transforms. Non-object
+ * options are kept AS-IS: relaxing a leaf to `z.any()` would make it swallow
+ * every value (the first branch would always win), so the strictified option
+ * is left intact — it still discriminates by type and still carries any wire
+ * transform it needs. Validation on those non-object branches is therefore
+ * only best-effort, which is acceptable: `decodeWire` falls back to the
+ * original value if nothing matches.
+ */
+function relaxUnionOptions(options, relax) {
+    const relaxed = options.map((opt) => opt instanceof z.ZodObject ? relaxObjectShape(opt, relax, false) : opt);
+    return z.union(relaxed);
+}
+/**
+ * Per-node dispatch for `relaxValidation`. Mirrors the node coverage of
+ * `strictifySimple` plus the extra wrappers/containers a strictified schema
+ * can contain (`ZodMap`, `ZodSet`, `ZodCatch`, `ZodReadonly`, `ZodPrefault`,
+ * `ZodNonOptional`, …). Unknown/leaf nodes bottom out at `z.any()`.
+ */
+function relaxNode(schema, relax) {
+    // ---- Wrappers: unwrap, relax inner, re-wrap ----
+    if (schema instanceof z.ZodOptional)
+        return relax(schema.unwrap()).optional();
+    if (schema instanceof z.ZodNullable)
+        return relax(schema.unwrap()).nullable();
+    if (schema instanceof z.ZodDefault) {
+        return relax(schema._zod.def.innerType).default(schema._zod.def.defaultValue);
+    }
+    if (schema instanceof z.ZodPrefault) {
+        return relax(schema._zod.def.innerType).prefault(schema._zod.def.defaultValue);
+    }
+    if (schema instanceof z.ZodCatch) {
+        return relax(schema._zod.def.innerType).catch(schema._zod.def.catchValue);
+    }
+    if (schema instanceof z.ZodReadonly)
+        return relax(schema._zod.def.innerType).readonly();
+    // NonOptional adds a "must be present" validation — drop it (we're relaxing).
+    if (schema instanceof z.ZodNonOptional)
+        return relax(schema._zod.def.innerType);
+    // ---- Transforms: KEEP the transform so the decode still runs ----
+    // ZodCodec must be checked before ZodPipe (it's a ZodPipe subclass in v4).
+    if (schema instanceof z.ZodCodec) {
+        return z.codec(relax(schema._zod.def.in), relax(schema._zod.def.out), { decode: schema._zod.def.transform, encode: schema._zod.def.reverseTransform });
+    }
+    // A bare transform (the `in` of a `preprocess`, the `out` of a `.transform`)
+    // carries no validation — keep it verbatim so the transform runs.
+    if (schema instanceof z.ZodTransform)
+        return schema;
+    if (schema instanceof z.ZodPipe) {
+        return z.pipe(relax(schema._zod.def.in), relax(schema._zod.def.out));
+    }
+    // ---- Containers: recurse so nested transforms are reached ----
+    if (schema instanceof z.ZodObject)
+        return relaxObjectShape(schema, relax, /* forceOptional */ true);
+    if (schema instanceof z.ZodArray)
+        return z.array(relax(schema._zod.def.element));
+    if (schema instanceof z.ZodTuple) {
+        const items = schema._zod.def.items.map(relax);
+        const rest = schema._zod.def.rest ? relax(schema._zod.def.rest) : undefined;
+        return rest ? z.tuple(items, rest) : z.tuple(items);
+    }
+    if (schema instanceof z.ZodRecord) {
+        // Accept any string key (records arrive with string-ish keys on the wire);
+        // an exhaustive/enum key schema would reject partial records.
+        return z.record(z.string(), relax(schema._zod.def.valueType));
+    }
+    if (schema instanceof z.ZodMap) {
+        return z.map(relax(schema._zod.def.keyType), relax(schema._zod.def.valueType));
+    }
+    if (schema instanceof z.ZodSet)
+        return z.set(relax(schema._zod.def.valueType));
+    // ---- Combinators ----
+    // ZodDiscriminatedUnion is a ZodUnion subclass in v4, so this one branch
+    // covers both. Discrimination survives via required-field presence.
+    if (schema instanceof z.ZodUnion)
+        return relaxUnionOptions(schema.options, relax);
+    if (schema instanceof z.ZodIntersection) {
+        return z.intersection(relaxIntersectionSide(schema._zod.def.left, relax), relaxIntersectionSide(schema._zod.def.right, relax));
+    }
+    // ---- Recursion: defer + memoize (see `relaxValidation`) ----
+    if (schema instanceof z.ZodLazy) {
+        return z.lazy(() => relax(schema._zod.def.getter()));
+    }
+    // ---- Validating leaves + anything unrecognized → accept everything ----
+    return z.any();
+}
+/**
+ * Produce a NON-FAILING variant of `schema` that keeps every transform
+ * (`preprocess`, `codec`, `pipe`, `transform`) but drops validation. Parsing
+ * a wire value through the result runs the decode preprocesses installed by
+ * `strictify` (array-of-pairs → record, numeric-key object → tuple, null →
+ * undefined) and yields the conceptual value, without ever rejecting.
+ *
+ * Recursion (`z.lazy` self-reference) is handled with a per-call memo map: an
+ * in-flight node is recorded as a thunk and re-encounters resolve to
+ * `z.lazy(thunk)`, so a self-referential schema relaxes in finite time and
+ * never infinite-loops.
+ */
+export function relaxValidation(schema) {
+    // Per-call cycle map — same scheme as `strictifyWithDescriptor`: cache a
+    // lazy thunk for in-flight schemas so recursive references resolve to a
+    // `z.lazy(() => result)` instead of recursing forever.
+    const map = new Map();
+    const relax = (s) => {
+        const cached = map.get(s);
+        if (cached) {
+            return typeof cached === 'function' ? z.lazy(cached) : cached;
+        }
+        let result;
+        map.set(s, () => result);
+        result = relaxNode(s, relax);
+        map.set(s, result);
+        return result;
+    };
+    return relax(schema);
+}
+/**
+ * Module-scope cache for relaxed decoders. Mirrors `strictifyCache`: outer
+ * WeakMap keyed by the SOURCE schema (gc'd with it), inner Map keyed by
+ * descriptor id (small bounded set).
+ */
+const relaxDecodeCache = new WeakMap();
+/**
+ * DECODE a model's wire `value` back to the conceptual shape a custom parser
+ * expects — symmetric with how `strictify` ENCODEs the request for the wire.
+ *
+ * Runs the descriptor's decode transforms (via `relaxValidation(strictify(...))`)
+ * without imposing validation, so array-of-pairs records, numeric-key tuples,
+ * and null-for-optional fields are normalized before a provider-agnostic
+ * custom parser sees them. Best-effort: NEVER throws — if the relaxed decoder
+ * can't parse the value it is returned unchanged.
+ *
+ * @param schema - the PRE-strictify conceptual schema (strictify runs internally)
+ * @param value - the model's raw wire value (already `JSON.parse`d)
+ * @param descriptor - the wire dialect the request was encoded with
+ */
+export function decodeWire(schema, value, descriptor) {
+    let perSchema = relaxDecodeCache.get(schema);
+    if (!perSchema) {
+        perSchema = new Map();
+        relaxDecodeCache.set(schema, perSchema);
+    }
+    let decoder = perSchema.get(descriptor.id);
+    if (!decoder) {
+        decoder = relaxValidation(strictify(schema, descriptor));
+        perSchema.set(descriptor.id, decoder);
+    }
+    const result = decoder.safeParse(value);
+    return result.success ? result.data : value;
+}
+//# sourceMappingURL=decode.js.map

package/dist/schema/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/schema/decode.ts"],"names":[],"mappings":"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"}