functype 1.0.1 → 1.2.0

package/dist/{index-BYF5RMBp.d.ts → index-DAKubqXO.d.ts}

@@ -1,5 +1,5 @@
-import { t as Brand } from "./Brand-BJIRbUKB.js";
-import { c as Pipe, l as Foldable, o as Serializable, r as Typeable, t as Tuple, u as Type } from "./Tuple-De-FhPDq.js";
+import { t as Brand } from "./Brand-bfnGXuum.js";
+import { d as Type, l as Pipe, o as Serializable, r as Typeable, t as Tuple, u as Foldable } from "./Tuple-8yRldBty.js";
 
 //#region src/error/ParseError.d.ts
 declare const ParseError: (message?: string) => Error & {
@@ -200,6 +200,13 @@ declare const LazyList: (<A extends Type>(iterable: Iterable<A>) => LazyList<A>)
    * Create a LazyList from multiple values
    */
   from: <A extends Type>(...values: A[]) => LazyList<A>;
+  /**
+   * Reconstruct a LazyList from a JSON envelope emitted by `serialize().toJSON()`
+   * or instance `toJSON()`. Verifies `@functype === "LazyList"` when the marker
+   * is present (canonical from 1.2.0). The materialized array becomes the new
+   * LazyList's backing — laziness can't survive JSON serialization.
+   */
+  fromJSON: <A extends Type>(json: string) => LazyList<A>;
   /**
    * Create an infinite LazyList by repeatedly applying a function
    * @example
@@ -244,6 +251,190 @@ declare const LazyList: (<A extends Type>(iterable: Iterable<A>) => LazyList<A>)
   cycle: <A extends Type>(iterable: Iterable<A>) => LazyList<A>;
 };
 //#endregion
+//#region src/serialization/error-envelope.d.ts
+/**
+ * Canonical projection of `Error` to JSON, shared by every Serializable type
+ * that carries an `Error` in its failure branch (`Try.Failure`, `Task.Err`,
+ * `Lazy` with a thrown thunk).
+ *
+ * Round-trip guarantees:
+ *  - `err.name` survives (preserves discriminator: `e.name === "TypeError"` works)
+ *  - `err.message` survives
+ *  - `err.stack` survives if present at serialize time
+ *  - `err.cause` survives recursively (arbitrary nesting depth)
+ *
+ * What does NOT survive:
+ *  - `instanceof TypeError` and other subclass identity checks (JSON cannot
+ *    reconstruct user-defined classes without arbitrary code execution).
+ *  - Custom Error-subclass fields (e.g. `HttpError.status`). The generic
+ *    projection doesn't know about them; a future registry mechanism may
+ *    address this.
+ *
+ * Use `e.name` for discriminator checks across the serialization boundary,
+ * not `e instanceof SomeError`.
+ */
+type SerializedError = {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly cause?: SerializedError | string;
+};
+/**
+ * Project an arbitrary thrown value to the canonical SerializedError shape.
+ * Accepts both `Error` instances and non-Error throwables (strings, plain
+ * objects, etc.). Non-Error throwables get `name: "NonErrorThrowable"` and
+ * the best textual representation we can produce.
+ */
+declare const serializeError: (err: unknown) => SerializedError;
+/**
+ * Reconstruct an Error from a SerializedError. The reconstructed Error has
+ * the same `name`, `message`, `stack`, and `cause` chain as the original,
+ * but its prototype is always `Error.prototype` — subclass identity does
+ * not round-trip.
+ *
+ * A `string` is accepted as a shorthand for `{name: "Error", message: <string>}`,
+ * matching what `serializeCause` emits when a `cause` was a bare string.
+ */
+declare const deserializeError: (s: SerializedError | string) => Error;
+//#endregion
+//#region src/serialization/SerializationCompanion.d.ts
+/**
+ * Serialization result containing methods for different formats
+ */
+interface SerializationResult {
+  /** Serializes to JSON string */
+  toJSON: () => string;
+  /** Serializes to YAML string */
+  toYAML: () => string;
+  /** Serializes to base64-encoded binary string */
+  toBinary: () => string;
+}
+/**
+ * The namespaced marker stamped on every functype envelope. Defends against
+ * `_tag` collisions with Effect/fp-ts (which use identical strings like
+ * `"Some"`, `"Left"`, `"Success"`). A value WITHOUT this marker is treated
+ * as "not ours" by `Serialization.deserialize`.
+ *
+ * See `docs/proposals/universal-deserialize-changes.md` Change 0 for the
+ * full rationale.
+ */
+declare const FUNCTYPE_MARKER: "@functype";
+/**
+ * Shape of every functype JSON envelope. The marker identifies the type,
+ * `_tag` (when present) discriminates variants within that type, and the
+ * remaining payload fields are type-specific (`value` for canonical cases,
+ * `error` for failure branches, etc.).
+ */
+type FunctypeEnvelope = {
+  readonly [FUNCTYPE_MARKER]: string;
+  readonly _tag?: string;
+  readonly [key: string]: unknown;
+};
+/**
+ * Build the canonical `{@functype, _tag, value}` envelope OBJECT used by both
+ * the instance `toJSON()` (which returns it directly so native JSON.stringify
+ * can recurse) and the `serialize().toJSON()` method (which stringifies it).
+ *
+ * `_tag` is always emitted — variant-less types pass the same string for
+ * marker and tag (default behavior when tag is omitted). Keeping `_tag`
+ * across the board preserves back-compat for readers that did
+ * `if (parsed._tag === "List")` against 1.1.0 envelopes.
+ *
+ * @param marker - The `@functype` type marker, e.g. `"Either"`, `"Option"`.
+ * @param tag - The variant discriminator, e.g. `"Right"`, `"Some"`. Defaults
+ *              to `marker` for types without variants (List, Map, etc.).
+ * @param value - The payload.
+ */
+declare const envelope: (marker: string, tag: string | undefined, value: unknown) => FunctypeEnvelope;
+/**
+ * Build a non-canonical envelope where the payload doesn't fit the standard
+ * `{value}` shape — e.g. `Try.Failure` carries `{error: SerializedError}`,
+ * `Lazy`-with-thrown-thunk carries the same.
+ *
+ * @param marker - The `@functype` type marker.
+ * @param tag - The variant discriminator (may be the same as marker for
+ *              variant-less types).
+ * @param fields - Additional payload fields merged into the envelope.
+ */
+declare const taggedEnvelope: (marker: string, tag: string, fields: Record<string, unknown>) => FunctypeEnvelope;
+/**
+ * Creates a serializer for the canonical envelope shape, with the `@functype`
+ * marker stamped at the top level (Change 0 of the 1.2.0 universal-deserialize
+ * work). Two forms:
+ *
+ *   createSerializer(marker, value)          // variant-less types (List, Map, …)
+ *   createSerializer(marker, tag, value)     // variants (Either, Option, …)
+ *
+ * Variant-less envelopes are `{"@functype": marker, value}`. Variant envelopes
+ * are `{"@functype": marker, _tag: tag, value}`.
+ */
+declare function createSerializer(marker: string, value: unknown): SerializationResult;
+declare function createSerializer(marker: string, tag: string, value: unknown): SerializationResult;
+/**
+ * Creates a serializer for non-canonical envelopes whose payload doesn't
+ * fit the `{value}` shape — e.g. failure branches that carry a structured
+ * `SerializedError`. The envelope still carries the `@functype` marker
+ * and `_tag` discriminator.
+ *
+ * @param marker - The `@functype` type marker.
+ * @param tag - The variant discriminator.
+ * @param fields - The payload fields (merged after marker + tag).
+ */
+declare const createTaggedSerializer: (marker: string, tag: string, fields: Record<string, unknown>) => SerializationResult;
+/**
+ * @deprecated Use `createTaggedSerializer` instead. Retained for backwards
+ *             compatibility with any external callers; will be removed in a
+ *             future major. The single internal caller (`Try.Failure`) has
+ *             been migrated to `createTaggedSerializer`.
+ *
+ * Creates a serializer for complex objects with custom serialization logic.
+ * Note: this variant does NOT stamp the `@functype` marker — callers must
+ * include it in `data` themselves if they want envelope dispatch to work.
+ */
+declare const createCustomSerializer: (data: Record<string, unknown>) => SerializationResult;
+/**
+ * Generic deserializer from JSON. The `reconstructor` receives the full
+ * parsed envelope including any `@functype` marker; per-type companions
+ * verify the marker matches their expected value.
+ */
+declare const fromJSON: <T>(json: string, reconstructor: (parsed: {
+  _tag?: string;
+  [key: string]: unknown;
+}) => T) => T;
+/**
+ * Generic deserializer from YAML (simple format)
+ * @param yaml - The YAML string to parse
+ * @param reconstructor - Function to reconstruct the type from parsed data
+ * @returns Reconstructed instance
+ */
+declare const fromYAML: <T>(yaml: string, reconstructor: (parsed: {
+  _tag?: string;
+  [key: string]: unknown;
+}) => T) => T;
+/**
+ * Generic deserializer from binary (base64-encoded JSON)
+ * @param binary - The base64-encoded binary string
+ * @param reconstructor - Function to reconstruct the type from parsed data
+ * @returns Reconstructed instance
+ */
+declare const fromBinary: <T>(binary: string, reconstructor: (parsed: {
+  _tag?: string;
+  [key: string]: unknown;
+}) => T) => T;
+/**
+ * Creates companion serialization methods for a type
+ * @param reconstructor - Function to reconstruct the type from parsed data
+ * @returns Companion methods object with fromJSON, fromYAML, and fromBinary
+ */
+declare const createSerializationCompanion: <T>(reconstructor: (parsed: {
+  _tag?: string;
+  [key: string]: unknown;
+}) => T) => {
+  fromJSON: (json: string) => T;
+  fromYAML: (yaml: string) => T;
+  fromBinary: (binary: string) => T;
+};
+//#endregion
 //#region src/typeclass/ContainerOps.d.ts
 /**
  * Universal operations that work on any container (single-value or collection).
@@ -570,6 +761,21 @@ interface Try<out T> extends FunctypeSum<T, TypeNames>, Extractable<T>, Pipe<T>,
     _tag: TypeNames;
     value: T | Error;
   };
+  /**
+   * Custom JSON serialization. Success emits `{"@functype":"Try","_tag":"Success","value":T}`.
+   * Failure emits `{"@functype":"Try","_tag":"Failure","error":SerializedError}` where
+   * SerializedError captures `name`, `message`, `stack`, and the full `cause` chain —
+   * `e.name` survives round-trip but `instanceof SomeError` does not.
+   */
+  toJSON(): {
+    "@functype": "Try";
+    _tag: "Success";
+    value: T;
+  } | {
+    "@functype": "Try";
+    _tag: "Failure";
+    error: SerializedError;
+  };
 }
 declare const Try: (<T>(f: () => T) => Try<T>) & {
   /**
@@ -1422,6 +1628,21 @@ interface TaskOutcome<out T> extends FunctypeBase<T, "Ok" | "Err">, Extractable<
     Ok: (value: T) => U;
     Err: (error: Throwable) => U;
   }) => U;
+  /**
+   * Custom JSON serialization. Ok emits `{"@functype":"Task","_tag":"Ok","value":T}`.
+   * Err emits `{"@functype":"Task","_tag":"Err","error":SerializedError}` capturing the
+   * Throwable's name, message, stack, and cause chain. See error-envelope.ts —
+   * `instanceof` does NOT survive round-trip but `error.name` does.
+   */
+  toJSON(): {
+    "@functype": "Task";
+    _tag: "Ok";
+    value: T;
+  } | {
+    "@functype": "Task";
+    _tag: "Err";
+    error: SerializedError;
+  };
 }
 interface Ok<out T> extends TaskOutcome<T> {
   readonly _tag: "Ok";
@@ -1527,6 +1748,15 @@ declare const Task$1: (<T = unknown>(params?: TaskParams) => {
    * Preferred for new code
    */
   err: <T>(error: unknown, data?: unknown, params?: TaskParams) => Err<T>;
+  /**
+   * Reconstruct a TaskOutcome from a JSON envelope emitted by `serialize().toJSON()`
+   * or instance `toJSON()`. Verifies `@functype === "Task"` and dispatches on `_tag`.
+   *
+   * Err reconstruction goes through `deserializeError` so `name`/`message`/`stack`/`cause`
+   * survive; the resulting Throwable carries the deserialized Error as its underlying
+   * error (subclass identity does NOT round-trip — see error-envelope.ts).
+   */
+  fromJSON: <T>(json: string) => TaskOutcome<T>;
   /**
    * Create TaskOutcome from Either
    * @param either - Either to convert
@@ -1618,6 +1848,131 @@ declare const Task$1: (<T = unknown>(params?: TaskParams) => {
 };
 type Task$1 = ReturnType<typeof Task$1>;
 //#endregion
+//#region src/decoder/DecoderError.d.ts
+/**
+ * Recursive decoder error.
+ *
+ * `Leaf` represents a single decode failure at some `path` in the input.
+ * `Composite` aggregates child failures (one per failed field of an object,
+ * one per failed element of a list, etc.) and mirrors the structural shape
+ * of the input — making it possible to render `user.name: expected string`
+ * alongside `user.age: expected number` from a single response.
+ *
+ * Accumulation lives in the data, not in the wrapper. Combinators in
+ * `DecoderCompanion` (object/list/map) produce `Composite` when more than
+ * one child decoder fails, unwrapping single-child composites back to a
+ * `Leaf` for cleaner error messages. The plain `Either<DecoderError, A>`
+ * return type of `Decoder<A>` keeps composition with the rest of the
+ * library uniform.
+ *
+ * Named `DecoderError` (not `DecodeError`) to avoid collision with the
+ * existing `HttpError.DecodeError` variant — these are at different layers:
+ * the HTTP variant is the outer wrapper, this is the structural inner cause.
+ */
+type DecoderError = DecoderErrorLeaf | DecoderErrorComposite;
+type DecoderErrorLeaf = {
+  readonly _tag: "Leaf";
+  readonly path: ReadonlyArray<string>;
+  readonly message: string;
+  readonly cause?: unknown;
+};
+type DecoderErrorComposite = {
+  readonly _tag: "Composite";
+  readonly path: ReadonlyArray<string>;
+  readonly children: List<DecoderError>;
+};
+declare const DecoderError: {
+  readonly _tag: "DecoderError";
+} & {
+  leaf: (path: ReadonlyArray<string>, message: string, cause?: unknown) => DecoderErrorLeaf;
+  composite: (path: ReadonlyArray<string>, children: List<DecoderError>) => DecoderErrorComposite;
+  isLeaf: (e: DecoderError) => e is DecoderErrorLeaf;
+  isComposite: (e: DecoderError) => e is DecoderErrorComposite;
+  match: <T>(e: DecoderError, patterns: {
+    readonly Leaf: (e: DecoderErrorLeaf) => T;
+    readonly Composite: (e: DecoderErrorComposite) => T;
+  }) => T;
+  prepend: (segment: string, e: DecoderError) => DecoderError;
+  flatten: (e: DecoderError) => List<{
+    readonly path: ReadonlyArray<string>;
+    readonly message: string;
+  }>;
+  format: (e: DecoderError) => string;
+};
+//#endregion
+//#region src/decoder/Decoder.d.ts
+/**
+ * A `Decoder<A>` converts an `unknown` value into either a typed `A` or a
+ * structural `DecoderError`. The shape `(raw) => Either<DecoderError, A>` is
+ * the canonical FP decoder contract (cf. circe `Decoder`, fp-ts `Decoder`,
+ * Effect-TS `Schema.decodeUnknownEither`, Elm `Json.Decode.Decoder`).
+ *
+ * Any function matching this signature IS a decoder — there is no plugin
+ * registration. Zod / TypeBox / Valibot / AJV / hand-rolled adapters are
+ * ~15 lines each. The bundled combinators in `DecoderCompanion` cover the
+ * functype-aware cases (Option, Either, List, etc.) that a generic schema
+ * library cannot express.
+ */
+type Decoder$1<A> = (raw: unknown) => Either<DecoderError, A>;
+//#endregion
+//#region src/decoder/index.d.ts
+/**
+ * A `Decoder<A>` converts an `unknown` value into either a typed `A` or a
+ * structural `DecoderError`. The shape `(raw) => Either<DecoderError, A>` is
+ * the canonical FP decoder contract (cf. circe `Decoder`, fp-ts `Decoder`,
+ * Effect-TS `Schema.decodeUnknownEither`, Elm `Json.Decode.Decoder`).
+ *
+ * Any function matching this signature IS a decoder — there is no plugin
+ * registration. Zod / TypeBox / Valibot / AJV / hand-rolled adapters are
+ * ~15 lines each. The bundled combinators in the `Decoder` value namespace
+ * cover the functype-aware cases (Option, Either, List, etc.) that a
+ * generic schema library cannot express.
+ */
+type Decoder<A> = (raw: unknown) => Either<DecoderError, A>;
+/**
+ * Decoder namespace: combinators for converting `unknown` into typed values.
+ *
+ * - `Decoder.string` / `.number` / `.boolean` / `.unknown` / `.nullable(inner)` — leaf primitives
+ * - `Decoder.option(inner)` — null-bias Option (null → None, else inner → Some)
+ * - `Decoder.either.envelope({ok, err})` / `.discriminated({...}, l, r)` — Either variants
+ * - `Decoder.list(inner)` / `.array(inner)` / `.map(inner)` / `.object(shape)` — composites; accumulate child failures
+ * - `Decoder.tagged.option/either/try/list/map/obj(inner?)` — round-trip the `{_tag, value}` shape
+ *   used by functype's built-in `.toJSON()` (for functype-to-functype services)
+ */
+declare const Decoder: {
+  readonly _tag: "Decoder";
+} & {
+  tagged: {
+    option: <A>(inner: Decoder$1<A>) => Decoder$1<Option<A>>;
+    either: <L, R>(left: Decoder$1<L>, right: Decoder$1<R>) => Decoder$1<Either<L, R>>;
+    try: <A>(inner: Decoder$1<A>) => Decoder$1<Try<A>>;
+    list: <A>(inner: Decoder$1<A>) => Decoder$1<List<A>>;
+    map: <V>(inner: Decoder$1<V>) => Decoder$1<Map$1<string, V>>;
+    obj: <T extends Record<string, unknown>>(shape: { [K in keyof T]: Decoder$1<T[K]> }) => Decoder$1<T>;
+  };
+  string: Decoder$1<string>;
+  number: Decoder$1<number>;
+  boolean: Decoder$1<boolean>;
+  unknown: Decoder$1<unknown>;
+  nullable: <A>(inner: Decoder$1<A>) => Decoder$1<A | null>;
+  option: <A>(inner: Decoder$1<A>) => Decoder$1<Option<A>>;
+  either: {
+    envelope: <L, R>(shape: {
+      ok: Decoder$1<R>;
+      err: Decoder$1<L>;
+    }) => Decoder$1<Either<L, R>>;
+    discriminated: <L, R>(config: {
+      tag: string;
+      leftTag: string;
+      rightTag: string;
+    }, left: Decoder$1<L>, right: Decoder$1<R>) => Decoder$1<Either<L, R>>;
+  };
+  list: <A>(inner: Decoder$1<A>) => Decoder$1<List<A>>;
+  array: <A>(inner: Decoder$1<A>) => Decoder$1<A[]>;
+  map: <V>(inner: Decoder$1<V>) => Decoder$1<Map$1<string, V>>;
+  object: <T extends Record<string, unknown>>(shape: { [K in keyof T]: Decoder$1<T[K]> }) => Decoder$1<T>;
+};
+//#endregion
 //#region src/error/ErrorFormatter.d.ts
 /**
  * Type definition for task information that may be attached to errors
@@ -3316,6 +3671,14 @@ type HttpStatusError = {
   readonly statusText: string;
   readonly body: string;
 };
+/**
+ * Raised when a successful HTTP response could not be decoded into the
+ * caller's expected shape — JSON parse failure, a `decode: Decoder<T>` that
+ * returned `Left(DecoderError)`, a throwing `decodeUnsafe` / `validate`, etc.
+ * In practice `cause` is a `DecoderError` (when produced by the `decode`
+ * path) or an `Error` (otherwise) — but the field is typed `unknown` for
+ * back-compat with the 1.0.x runtime.
+ */
 type DecodeError = {
   readonly _tag: "DecodeError";
   readonly url: string;
@@ -3323,6 +3686,13 @@ type DecodeError = {
   readonly body: string;
   readonly cause: unknown;
 };
+/**
+ * More descriptive alias for `DecodeError` — clarifies that this is the
+ * HTTP-level wrapper for response decoding failures, distinct from the
+ * structural `DecoderError` tree it usually carries in `cause`. Both names
+ * refer to the same `_tag: "DecodeError"` variant.
+ */
+type ResponseDecodeError = DecodeError;
 type HttpError = NetworkError | HttpStatusError | DecodeError;
 declare const HttpError: {
   readonly _tag: "HttpError";
@@ -3349,14 +3719,47 @@ interface HttpRequestOptions<T = unknown> {
   readonly body?: unknown;
   readonly signal?: AbortSignal;
   readonly parseAs?: ParseMode;
+  /**
+   * Either-returning response decoder. Returns `Left(DecoderError)` on
+   * failure; the framework maps that to `HttpError.DecodeError(cause: DecoderError)`.
+   * The recursive `DecoderError` tree preserves structural failure info
+   * (paths, child errors) for diagnosis and rendering.
+   *
+   * For adapters whose primary API throws (e.g. Zod's `.parse`), use an
+   * adapter package (e.g. `functype-zod`'s `Decoder.fromZod(schema)`) or
+   * wrap the throwing function in a tiny custom decoder. The deprecated
+   * `validate` field is also still accepted for back-compat.
+   */
+  readonly decode?: Decoder$1<T>;
+  /**
+   * @deprecated Use `decode` (Either-returning). For throw-pattern adapters
+   *   like Zod's `.parse`, prefer an adapter package (`functype-zod`'s
+   *   `Decoder.fromZod`). `validate` is kept for back-compat with the 1.0.x
+   *   API and will be removed in a future major release. Throwing maps to
+   *   `HttpError.DecodeError(cause: Error)`.
+   */
   readonly validate?: (data: unknown) => T;
+  /**
+   * Whether to flatten functype ADTs in the request body to their primitive
+   * projections (Option → nullable, Either → right-value-or-throw-on-Left,
+   * List → array, Try → success-value-or-throw, Map → record) before serializing.
+   * Default `true` — matches the wire shape external JSON APIs expect.
+   *
+   * Set to `false` to emit each ADT's canonical `{_tag, value}` form via
+   * `toValue()` for functype-to-functype services where both ends round-trip
+   * the tagged shape via `Decoder.tagged.*`.
+   */
+  readonly flatten?: boolean;
 }
 interface HttpMethodOptions<T = unknown> {
   readonly headers?: Record<string, string>;
   readonly body?: unknown;
   readonly signal?: AbortSignal;
   readonly parseAs?: ParseMode;
+  readonly decode?: Decoder$1<T>;
+  /** @deprecated Use `decode` (Either-returning) or an adapter package for throw-pattern validators. */
   readonly validate?: (data: unknown) => T;
+  readonly flatten?: boolean;
 }
 interface HttpResponse<T> {
   readonly data: T;
@@ -3368,8 +3771,10 @@ interface HttpResponse<T> {
  * The assembled, pre-wire view of a request that `HttpClientConfig.beforeRequest`
  * receives and may return a transformed copy of. URL is resolved against
  * `baseUrl`; headers reflect the `defaultHeaders` + per-call merge. The
- * response-side `validate` function is intentionally not exposed here — it
- * isn't part of the wire request and applies to the response.
+ * response-side decoders (`decode` / `validate`) are intentionally not
+ * exposed here — they aren't part of the wire request and apply to the
+ * response. The `flatten` flag IS exposed because it affects how `body`
+ * is serialized.
  */
 interface HttpRequestView {
   readonly url: string;
@@ -3378,6 +3783,7 @@ interface HttpRequestView {
   readonly body?: unknown;
   readonly signal?: AbortSignal;
   readonly parseAs?: ParseMode;
+  readonly flatten?: boolean;
 }
 //#endregion
 //#region src/fetch/HttpClient.d.ts
@@ -3432,8 +3838,8 @@ type HttpMethods = {
   readonly put: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
   readonly patch: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
   readonly delete: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
-  readonly head: (url: string, options?: HttpMethodOptions) => IO<never, HttpError, HttpResponse<void>>;
-  readonly options: (url: string, options?: HttpMethodOptions) => IO<never, HttpError, HttpResponse<void>>;
+  readonly head: (url: string, options?: HttpMethodOptions<void>) => IO<never, HttpError, HttpResponse<void>>;
+  readonly options: (url: string, options?: HttpMethodOptions<void>) => IO<never, HttpError, HttpResponse<void>>;
 };
 declare const Http: {
   readonly _tag: "Http";
@@ -3444,8 +3850,8 @@ declare const Http: {
   put: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
   patch: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
   delete: <T = unknown>(url: string, options?: HttpMethodOptions<T>) => IO<never, HttpError, HttpResponse<T>>;
-  head: (url: string, options?: HttpMethodOptions) => IO<never, HttpError, HttpResponse<void>>;
-  options: (url: string, options?: HttpMethodOptions) => IO<never, HttpError, HttpResponse<void>>;
+  head: (url: string, options?: HttpMethodOptions<void>) => IO<never, HttpError, HttpResponse<void>>;
+  options: (url: string, options?: HttpMethodOptions<void>) => IO<never, HttpError, HttpResponse<void>>;
   client: (config: HttpClientConfig) => HttpMethods;
 };
 //#endregion
@@ -3750,13 +4156,39 @@ interface Lazy<out T extends Type> extends FunctypeBase<T, "Lazy">, Extractable<
    */
   toString(): string;
   /**
-   * Converts the Lazy to a value object
-   * @returns Object representation of the Lazy with evaluation state
+   * Converts the Lazy to a value object.
+   *
+   * **Forces the thunk** as a side effect — Lazy serialization (and projection
+   * to a plain value object) cannot represent an unevaluated thunk in JSON;
+   * forcing is the only way to produce a complete projection. If the thunk
+   * threw, the failure is captured in the `error` field (real Error, with
+   * full prototype intact for in-memory inspection — `toJSON` projects to
+   * `SerializedError` for the wire).
+   *
+   * Changed in 1.2.0 — pre-1.2.0 Lazy emitted `{_tag, evaluated, value?}`
+   * without forcing. See `docs/proposals/serializable-audit-q1-q2.md`.
    */
   toValue(): {
     _tag: "Lazy";
-    evaluated: boolean;
-    value?: T;
+    value: T;
+  } | {
+    _tag: "Lazy";
+    error: Error;
+  };
+  /**
+   * Custom JSON serialization. Forces the thunk (see `toValue` for the
+   * side-effect contract). Emits `{"@functype":"Lazy","_tag":"Lazy","value":T}`
+   * on success, or `{"@functype":"Lazy","_tag":"Lazy","error":SerializedError}`
+   * if the thunk threw — see error-envelope.ts for round-trip semantics.
+   */
+  toJSON(): {
+    "@functype": "Lazy";
+    _tag: "Lazy";
+    value: T;
+  } | {
+    "@functype": "Lazy";
+    _tag: "Lazy";
+    error: SerializedError;
   };
 }
 /**
@@ -3842,6 +4274,24 @@ declare const Lazy: (<T extends Type>(thunk: () => T) => Lazy<T>) & {
    * @returns A new Lazy instance that throws the error
    */
   fail: <T extends Type>(error: unknown) => Lazy<T>;
+  /**
+   * Creates an already-evaluated Lazy. Used by `fromJSON` to reconstruct a
+   * Lazy whose thunk was forced at serialize time — there is no original
+   * thunk to defer because a closure cannot be JSON-serialized.
+   *
+   * Functionally equivalent to `Lazy.fromValue` but reads with intent at
+   * the call site.
+   */
+  evaluated: <T extends Type>(value: T) => Lazy<T>;
+  /**
+   * Reconstruct a Lazy from a JSON envelope emitted by `serialize().toJSON()`
+   * or instance `toJSON()`. Verifies `@functype === "Lazy"`. Success envelopes
+   * become already-evaluated Lazies via `Lazy.evaluated`; failure envelopes
+   * become Lazies whose forcing rethrows the deserialized Error (see
+   * error-envelope.ts — `instanceof SomeError` does NOT survive but `name`
+   * does).
+   */
+  fromJSON: <T extends Type>(json: string) => Lazy<T>;
 };
 //#endregion
 //#region src/traversable/Traversable.d.ts
@@ -4246,75 +4696,43 @@ declare const Ref: (<A extends Type>(initial: A) => Ref<A>) & {
    */
   of: <A extends Type>(initial: A) => Ref<A>;
 };
-//#endregion
-//#region src/serialization/SerializationCompanion.d.ts
-/**
- * Serialization result containing methods for different formats
- */
-interface SerializationResult {
-  /** Serializes to JSON string */
-  toJSON: () => string;
-  /** Serializes to YAML string */
-  toYAML: () => string;
-  /** Serializes to base64-encoded binary string */
-  toBinary: () => string;
+declare namespace Serialization_d_exports {
+  export { deserialize, isFunctypeValue, serialize };
 }
 /**
- * Creates a serializer for a simple tagged value
- * @param tag - The type tag (e.g., "Some", "List", "Success")
- * @param value - The value to serialize
- * @returns Serialization methods
- */
-declare const createSerializer: (tag: string, value: unknown) => SerializationResult;
-/**
- * Creates a serializer for complex objects with custom serialization logic
- * @param data - The data object to serialize (should include _tag)
- * @returns Serialization methods
+ * Reconstruct any value from a JSON string. Walks the parsed structure and
+ * rebuilds functype envelopes via the dispatch table. Returns a `Try` so
+ * malformed JSON or unknown markers are expressible values rather than
+ * thrown — matches the functype convention for expected-failure paths.
+ *
+ * @example
+ *   const result = Serialization.deserialize('{"@functype":"Either","_tag":"Right","value":5}')
+ *   result.fold(e => console.error(e), v => console.log(v))  // → Right(5)
+ *
+ *   // Plain (non-functype) values pass through:
+ *   Serialization.deserialize('{"name":"alice","age":30}')  // → Success({name, age})
  */
-declare const createCustomSerializer: (data: Record<string, unknown>) => SerializationResult;
+declare const deserialize: (json: string) => Try<unknown>;
 /**
- * Generic deserializer from JSON
- * @param json - The JSON string to parse
- * @param reconstructor - Function to reconstruct the type from parsed data
- * @returns Reconstructed instance
- */
-declare const fromJSON: <T>(json: string, reconstructor: (parsed: {
-  _tag: string;
-  [key: string]: unknown;
-}) => T) => T;
-/**
- * Generic deserializer from YAML (simple format)
- * @param yaml - The YAML string to parse
- * @param reconstructor - Function to reconstruct the type from parsed data
- * @returns Reconstructed instance
- */
-declare const fromYAML: <T>(yaml: string, reconstructor: (parsed: {
-  _tag: string;
-  [key: string]: unknown;
-}) => T) => T;
-/**
- * Generic deserializer from binary (base64-encoded JSON)
- * @param binary - The base64-encoded binary string
- * @param reconstructor - Function to reconstruct the type from parsed data
- * @returns Reconstructed instance
+ * Serialize any value to a JSON string. Thin convenience over `JSON.stringify`
+ * — functype instances self-stringify via their instance `toJSON()` method,
+ * which emits the `@functype`-marked envelope. Nested functype values
+ * embedded in plain objects/arrays serialize correctly via the standard
+ * JSON.stringify protocol with no walker needed.
+ *
+ * `undefined` is converted to `null` (matching the convention DBOS and
+ * SuperJSON use; `JSON.stringify(undefined)` returns the string `undefined`
+ * which is not valid JSON).
  */
-declare const fromBinary: <T>(binary: string, reconstructor: (parsed: {
-  _tag: string;
-  [key: string]: unknown;
-}) => T) => T;
+declare const serialize: (value: unknown) => string;
 /**
- * Creates companion serialization methods for a type
- * @param reconstructor - Function to reconstruct the type from parsed data
- * @returns Companion methods object with fromJSON, fromYAML, and fromBinary
+ * Runtime guard: is this a live functype Serializable? Checks for the
+ * `serialize()` method plus the `_tag` field that every Serializable instance
+ * carries. Use this when wrapping `serialize`/`deserialize` in a host
+ * serializer that needs to distinguish functype values from foreign data
+ * (e.g. `isApplicable` in a DBOS recipe).
  */
-declare const createSerializationCompanion: <T>(reconstructor: (parsed: {
-  _tag: string;
-  [key: string]: unknown;
-}) => T) => {
-  fromJSON: (json: string) => T;
-  fromYAML: (yaml: string) => T;
-  fromBinary: (binary: string) => T;
-};
+declare const isFunctypeValue: (v: unknown) => v is Serializable<unknown>;
 //#endregion
 //#region src/set/Set.d.ts
 /**
@@ -4665,6 +5083,16 @@ interface Option<out T extends Type> extends Functype<T, "Some" | "None">, Promi
     _tag: "Some" | "None";
     value: T;
   };
+  /**
+   * Custom JSON serialization producing the canonical `@functype`-marked
+   * envelope so native `JSON.stringify` recursion (e.g. inside a plain
+   * object) emits a round-trip-able shape.
+   */
+  toJSON(): {
+    "@functype": "Option";
+    _tag: "Some" | "None";
+    value: T | null;
+  };
   /**
    * Pattern matches over the Option, applying a handler function based on the variant
    * @param patterns - Object with handler functions for Some and None variants
@@ -5029,9 +5457,14 @@ interface EitherBase<out L extends Type, out R extends Type> extends FunctypeSum
     value: L | R;
   };
   /**
-   * Custom JSON serialization that excludes getter properties
+   * Custom JSON serialization that excludes getter properties.
+   * Emits the canonical functype envelope with `@functype: "Either"` so
+   * native `JSON.stringify` recursion (e.g. inside a plain object body)
+   * produces a marker-bearing envelope that survives a round-trip through
+   * `Serialization.deserialize`.
    */
   toJSON(): {
+    "@functype": "Either";
     _tag: "Left" | "Right";
     value: L | R;
   };
@@ -5336,4 +5769,4 @@ interface FailureErrorType extends Error {
 }
 declare const FailureError: (cause: Error, message?: string) => FailureErrorType;
 //#endregion
-export { Map$1 as $, reduceRightWiden as $n, TypedError as $t, Collection as A, UntypedMatch as An, RIO as At, SerializationResult as B, IntegerNumber as Bn, Context as Bt, isRight as C, createCancellationTokenSource as Cn, HttpStatusError as Ct, Functype as D, ThrowableType as Dn, TestContext as Dt, FunctypeSum as E, Throwable as En, TestClockTag as Et, Some as F, Companion as Fn, LayerError as Ft, fromJSON as G, PositiveNumber as Gn, FieldValidation as Gt, createSerializationCompanion as H, NonNegativeNumber as Hn, HasService as Ht, Stack as I, BoundedNumber as In, LayerInput as It, Obj as J, ValidatedBrand as Jn, ValidationRule as Jt, fromYAML as K, UUID as Kn, FormValidation as Kt, Valuable as L, BoundedString as Ln, LayerOutput as Lt, None as M, CompanionMethods as Mn, TimeoutError as Mt, Option as N, InstanceType as Nn, UIO as Nt, FunctypeBase as O, Base as On, IO as Ot, OptionConstructor as P, isCompanion as Pn, Layer as Pt, ESMapType as Q, Widen as Qn, ErrorStatus as Qt, ValuableParams as R, EmailAddress as Rn, Exit as Rt, isLeft as S, TaskSuccess as Sn, HttpMethod as St, tryCatchAsync as T, NAME as Tn, TestClock as Tt, createSerializer as U, PatternString as Un, Tag as Ut, createCustomSerializer as V, NonEmptyString as Vn, ContextServices as Vt, fromBinary as W, PositiveInteger as Wn, TagService as Wt, MatchableUtils as X, Try as Xn, ErrorCode as Xt, Matchable as Y, ValidatedBrandCompanion as Yn, Validator as Yt, ESMap as Z, TypeNames as Zn, ErrorMessage as Zt, Right as _, TaskFailure as _n, HttpRequestView as _t, EmptyListError as a, createErrorSerializer as an, Monad as ar, HKT as at, TypeCheckLeft as b, TaskParams as bn, DecodeError as bt, LeftError as c, safeStringify as cn, LazyList as cr, OptionKind as ct, isDoCapable as d, CancellationTokenSource as dn, DoResult as dr, FoldableUtils as dt, TypedErrorContext as en, reduceWiden as er, KVTraversable as et, unwrap as f, Err as fn, Doable as fr, Http as ft, LeftOf as g, Task$1 as gn, HttpRequestOptions as gt, Left as h, TaggedThrowable as hn, HttpMethodOptions as ht, DoGenerator as i, TaskErrorInfo as in, Functor as ir, EitherKind as it, List as j, Cond as jn, Task as jt, FunctypeCollection as k, Match as kn, InterruptedError as kt, LeftErrorType as l, Async as ln, Extractable as lr, TryKind as lt, EitherBase as m, Sync as mn, HttpClientConfig as mt, Do as n, ErrorFormatterOptions as nn, Applicative as nr, Lazy as nt, FailureError as o, formatError as on, CollectionOps as or, Kind as ot, Either as p, Ok as pn, ParseError as pr, HttpClient as pt, Ref as q, UrlString as qn, Validation as qt, DoAsync as r, ErrorWithTaskInfo as rn, AsyncMonad as rr, Identity as rt, FailureErrorType as s, formatStackTrace as sn, ContainerOps as sr, ListKind as st, $ as t, ErrorChainElement as tn, Promisable as tr, Traversable as tt, NoneError as u, CancellationToken as un, isExtractable as ur, UniversalContainer as ut, RightOf as v, TaskMetadata as vn, HttpResponse as vt, tryCatch as w, isTaggedThrowable as wn, NetworkError as wt, TypeCheckRight as x, TaskResult as xn, HttpError as xt, TestEither as y, TaskOutcome as yn, ParseMode as yt, Set as z, ISO8601Date as zn, ExitTag as zt };
+export { HKT as $, reduceWiden as $n, TaskErrorInfo as $t, Collection as A, Cond as An, LayerError as At, Serialization_d_exports as B, NonEmptyString as Bn, FieldValidation as Bt, isRight as C, isTaggedThrowable as Cn, Extractable as Cr, IO as Ct, Functype as D, Base as Dn, ParseError as Dr, TimeoutError as Dt, FunctypeSum as E, ThrowableType as En, Doable as Er, Task as Et, Some as F, BoundedNumber as Fn, Context as Ft, ESMap as G, UUID as Gn, ErrorCode as Gt, Obj as H, PatternString as Hn, Validation as Ht, Stack as I, BoundedString as In, ContextServices as It, KVTraversable as J, ValidatedBrandCompanion as Jn, TypedError as Jt, ESMapType as K, UrlString as Kn, ErrorMessage as Kt, Valuable as L, EmailAddress as Ln, HasService as Lt, None as M, InstanceType as Mn, LayerOutput as Mt, Option as N, isCompanion as Nn, Exit as Nt, FunctypeBase as O, Match as On, UIO as Ot, OptionConstructor as P, Companion as Pn, ExitTag as Pt, EitherKind as Q, reduceRightWiden as Qn, ErrorWithTaskInfo as Qt, ValuableParams as R, ISO8601Date as Rn, Tag as Rt, isLeft as S, createCancellationTokenSource as Sn, LazyList as Sr, TestContext as St, tryCatchAsync as T, Throwable as Tn, DoResult as Tr, RIO as Tt, Matchable as U, PositiveInteger as Un, ValidationRule as Ut, Ref as V, NonNegativeNumber as Vn, FormValidation as Vt, MatchableUtils as W, PositiveNumber as Wn, Validator as Wt, Lazy as X, TypeNames as Xn, ErrorChainElement as Xt, Traversable as Y, Try as Yn, TypedErrorContext as Yt, Identity as Z, Widen as Zn, ErrorFormatterOptions as Zt, Right as _, TaskMetadata as _n, fromYAML as _r, HttpStatusError as _t, EmptyListError as a, DecoderError as an, CollectionOps as ar, FoldableUtils as at, TypeCheckLeft as b, TaskResult as bn, deserializeError as br, TestClock as bt, LeftError as c, Async as cn, FunctypeEnvelope as cr, HttpClientConfig as ct, isDoCapable as d, Err as dn, createSerializationCompanion as dr, HttpRequestView as dt, createErrorSerializer as en, Promisable as er, Kind as et, unwrap as f, Ok as fn, createSerializer as fr, HttpResponse as ft, LeftOf as g, TaskFailure as gn, fromJSON as gr, HttpMethod as gt, Left as h, Task$1 as hn, fromBinary as hr, HttpError as ht, DoGenerator as i, Decoder as in, Monad as ir, UniversalContainer as it, List as j, CompanionMethods as jn, LayerInput as jt, FunctypeCollection as k, UntypedMatch as kn, Layer as kt, LeftErrorType as l, CancellationToken as ln, SerializationResult as lr, HttpMethodOptions as lt, EitherBase as m, TaggedThrowable as mn, envelope as mr, DecodeError as mt, Do as n, formatStackTrace as nn, AsyncMonad as nr, OptionKind as nt, FailureError as o, DecoderErrorComposite as on, ContainerOps as or, Http as ot, Either as p, Sync as pn, createTaggedSerializer as pr, ParseMode as pt, Map$1 as q, ValidatedBrand as qn, ErrorStatus as qt, DoAsync as r, safeStringify as rn, Functor as rr, TryKind as rt, FailureErrorType as s, DecoderErrorLeaf as sn, FUNCTYPE_MARKER as sr, HttpClient as st, $ as t, formatError as tn, Applicative as tr, ListKind as tt, NoneError as u, CancellationTokenSource as un, createCustomSerializer as ur, HttpRequestOptions as ut, RightOf as v, TaskOutcome as vn, taggedEnvelope as vr, NetworkError as vt, tryCatch as w, NAME as wn, isExtractable as wr, InterruptedError as wt, TypeCheckRight as x, TaskSuccess as xn, serializeError as xr, TestClockTag as xt, TestEither as y, TaskParams as yn, SerializedError as yr, ResponseDecodeError as yt, Set as z, IntegerNumber as zn, TagService as zt };