@ghostry/fabricator 0.0.1

package/dist/types/Primitive/string/Constants.d.ts

@@ -0,0 +1,58 @@
+import type { CodepointRange } from "./Types";
+/**
+ * Unicode code point ranges for spanning the codespace — a fuzzing aid
+ * for exercising input far outside ordinary text. Use a preset or build
+ * an arbitrary inclusive range with `range(from, to)`.
+ *
+ * Lives here rather than `Types.ts` so that file stays type-only. A
+ * value export alongside `export type Fabricated = string` makes the
+ * module a value module, and `export * as string` in
+ * `Primitive/namespace.ts` then resolves `string` to the namespace —
+ * a cycle that drops `[Kind]`/`[Meta]` off `Core`.
+ */
+export declare const unicode: {
+    /**
+     * All Unicode scalar values: the codespace minus the surrogate block
+     * (U+D800–U+DFFF). Always well-formed UTF-16, so it round-trips cleanly
+     * through encoders, URLs, and datastores.
+     *
+     * This is the default composition for strings.
+     */
+    scalars: {
+        from: number;
+        to: number;
+    }[];
+    /**
+     * The entire Unicode codespace, U+0000–U+10FFFF, including the surrogate
+     * block — so it can yield lone surrogates and thus ill-formed UTF-16.
+     * Opt in for lone surrogates and other ill-formed UTF-16 when fuzzing.
+     */
+    codespace: {
+        from: number;
+        to: number;
+    };
+    /** The Basic Multilingual Plane, U+0000–U+FFFF. */
+    bmp: {
+        from: number;
+        to: number;
+    };
+    /** Printable ASCII, U+0020–U+007E. */
+    ascii: {
+        from: number;
+        to: number;
+    };
+    /** An arbitrary inclusive code point range. */
+    range: (from: number, to: number) => CodepointRange;
+};
+/**
+ * The built-in character classes as code point ranges, each an alias for
+ * the code point ranges it spans. For use in the `[weight, source]` form
+ * of `composition` (e.g. mixing a class with a Unicode range).
+ */
+export declare const classes: {
+    lowercase: ReadonlyArray<CodepointRange>;
+    uppercase: ReadonlyArray<CodepointRange>;
+    digit: ReadonlyArray<CodepointRange>;
+    symbol: ReadonlyArray<CodepointRange>;
+    space: ReadonlyArray<CodepointRange>;
+};

package/dist/types/Primitive/string/Fabricator.d.ts

@@ -0,0 +1,24 @@
+import type { AdaptationsOf } from "../../Adapter/Types";
+import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
+import type { Trace } from "../../Random/Types";
+import { Kind, Meta, type Adaptation } from "../../Types";
+import { Schema } from "./Schema";
+import type { Fabricated, Meta as ThisMeta } from "./Types";
+export type Fabrication<_ extends Fabricator> = Fabricated;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = NaiveFabricator<Fabricated> & {
+    [Kind]: "string";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    schema: Schema<$Schema[typeof Meta], AdaptationsOf<$Schema>>;
+};
+/**
+ * Turn a `string` Schema into a live Fabricator — the one place this kind's
+ * character-generation logic actually runs. `Constructor.ts` calls this once per
+ * `construct()`, never from inside the returned `fabricate`.
+ */
+export declare function Fabricator(context: FabricatorContext<Schema>): Fabricator;

package/dist/types/Primitive/string/Registry.d.ts

@@ -0,0 +1,44 @@
+import type { Produce } from "../../Random/Types";
+import { Kind } from "../../Types";
+import { Schema } from "./Schema";
+import type { Fabricated, InputWhereby, JsonSchema } from "./Types";
+declare const _default: {
+    /**
+     * The builder carries the primitive's `[Kind]` so it can be named directly
+     * as a `compute` source — which derives its schema by kind — without
+     * first satisfying a `whereby`.
+     */
+    [Kind]: "string";
+    /**
+     * Derive a custom string type: a `string` Schema whose production is
+     * `produce`, optionally tagged with a `format` hint that schema exporters
+     * (e.g. `toTypeBox`) read.
+     */
+    as: (produce: Produce<Fabricated>, hints?: JsonSchema) => Schema<{
+        produce: Produce<string>;
+        hints: JsonSchema | undefined;
+    }, {}>;
+    /**
+     * A string whose length falls uniformly within `[length.min, length.max]`;
+     * `length.min` defaults to inclusive 0. Exclusive ends use a Bound object.
+     * Pass `composition` to control which characters appear and in what
+     * proportion; without one, characters span all Unicode scalar values (the
+     * codespace minus surrogates, so always well-formed UTF-16).
+     *
+     * `length` counts UTF-16 code units, so the result's `.length` equals the
+     * chosen length exactly. When the composition cannot fill the final code
+     * units — e.g. only astral, two-unit characters remain for a one-unit gap —
+     * the gap is topped up with a well-formed BMP character outside the
+     * requested `composition`, inserted at a random character boundary.
+     */
+    whereby: (whereby: InputWhereby) => Schema<{
+        whereby: {
+            length: {
+                min: import("../..").Bound<number>;
+                max: import("../..").Bound<number>;
+            };
+            composition?: import("./Types").Composition;
+        };
+    }, {}>;
+};
+export default _default;

package/dist/types/Primitive/string/Schema.d.ts

@@ -0,0 +1,65 @@
+import { type AdaptationEntry } from "../../Adapter/Core";
+import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { Core, Fabricated, JsonSchema, Meta as ThisMeta } from "./Types";
+/**
+ * Buildable `string` recipe: length/composition (`whereby` — required, unlike
+ * `number`/`date`; no natural bound to fuzz a length to), or opaque
+ * production via `as`.
+ *
+ * `$Meta` is generic (defaulting to the full `Meta` union) so builder return
+ * types stay narrow — see `number/Schema.ts`. `$Adaptations` is generic for
+ * the same reason, threaded through every builder method so an adaptation
+ * survives chaining (see `adapt`).
+ */
+export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends Adaptations = {}> extends Core<$Meta, $Adaptations> {
+    /**
+     * Layer an opaque production on this schema's existing `[Meta]` — carrying
+     * `whereby` forward, not discarding it, so a later `.as(...)` (or future
+     * validation of `produce`) still has it to check against.
+     */
+    as: (produce: Produce<Fabricated>, hints?: JsonSchema) => Schema<$Meta, $Adaptations>;
+    /**
+     * Override what this schema maps to in one external schema library, for a
+     * contract no native kind expresses — a `string` that is really an email, a
+     * `date` that must cross the wire as an ISO string. Canonical `adapt`; every
+     * other kind's method is the same and points here.
+     *
+     * `adapter` is the adapter itself, imported from its package
+     * (`schema.adapt(typebox, ...)`), not a name. The key this adaptation is
+     * filed under comes from it, so naming the wrong adapter is an import error
+     * rather than an entry nothing looks up. Several libraries = several chained
+     * calls; each replaces only its own adapter's entry.
+     *
+     * Additive to fabrication: only an adapter reads `[Adaptation]`, so the
+     * schema still produces exactly what it did. `Static<ToTypeBox<...>>` and
+     * `fabricate()` can therefore disagree — telling an external library
+     * something the fabricator doesn't honor is the point; keeping them
+     * compatible is the caller's business.
+     *
+     * Every other builder method carries the map forward, so `.adapt(...)`
+     * composes in any order with `.as(...)`/`.whereby(...)`/`.extend(...)`.
+     *
+     * `produce` receives an {@link Adapting} — `{ schema, meta }` for the schema
+     * being adapted. An adaptation deriving from this kind's config destructures
+     * `meta`; one building on what it replaces destructures `schema`. See that
+     * type; they describe one object, `meta` being that `schema`'s `[Meta]`.
+     *
+     * That schema carries whichever same-adapter adaptation it replaced
+     * (`Adapter/Core.ts`'s `layer`) — so `toTypeBox(schema)` inside one resolves
+     * to the previous layer, or this kind's ordinary mapping, and
+     * `Type.Intersect([toTypeBox(schema), extra])` reads as it looks. `[Kind]`,
+     * `[Meta]`, and `[Adaptation]` are always on it; builder methods are not,
+     * when the schema was normalized into an enclosing `object`/`array` field
+     * (`toSchema`).
+     *
+     * `$Returnable` is inferred from `produce`'s return position, not a
+     * constraint on the argument, so the adaptation keeps its precise type for
+     * the adapter to read off `[Adaptation]`. Bounding it by
+     * `ReturnType<$Adapter["convert"]>` rejects a producer returning something
+     * that adapter could never emit, at the call site rather than silently at
+     * conversion.
+     */
+    adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Meta, $Adaptations>>) => $Returnable) => Schema<$Meta, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
+}
+export declare function Schema<$Meta extends ThisMeta, $Adaptations extends Adaptations = {}>(schema: Core<$Meta, $Adaptations>): Schema<$Meta, $Adaptations>;

package/dist/types/Primitive/string/Types.d.ts

@@ -0,0 +1,77 @@
+import type { Adaptations } from "../../Adapter/Types";
+import type { Bound, InputBound } from "../../Bound";
+import type { Produce } from "../../Random/Types";
+import type { Adaptation, Kind, Meta, Produces } from "../../Types";
+import type { classes } from "./Constants";
+/** An inclusive range of Unicode code points. */
+export type CodepointRange = {
+    from: number;
+    to: number;
+};
+/**
+ * The single mechanism every character is drawn from: one or more code
+ * point ranges. A literal string is accepted as shorthand for the ranges
+ * of its individual characters, so custom pools, the built-in classes, and
+ * the Unicode codespace are all the same thing under the hood.
+ */
+export type CharacterSource = string | CodepointRange | ReadonlyArray<CodepointRange>;
+export type CharacterClass = keyof typeof classes;
+/**
+ * How a string's characters should be composed: a weighting over the
+ * built-in classes by name, or explicit `[weight, source]` pairs over
+ * arbitrary character sources. Each character independently picks a source
+ * by weight, then a code point uniformly across that source's ranges — so
+ * the weights describe expected composition, not per-character uniformity.
+ */
+export type Composition = Partial<Record<CharacterClass, number>> | ReadonlyArray<[number, CharacterSource]>;
+export type InputWhereby = {
+    length: {
+        max: InputBound<number>;
+        min?: InputBound<number> | undefined;
+    };
+    composition?: Composition;
+};
+export type Whereby = {
+    length: {
+        min: Bound<number>;
+        max: Bound<number>;
+    };
+    composition?: Composition;
+};
+export type Fabricated = string;
+/**
+ * JSON-Schema keywords that constrain a string value — carried as neutral,
+ * schema-library-agnostic hints (see the builder's `as`). Adapters forward
+ * them to their target: `toTypeBox` to `Type.String(...)`, a future `toZod`
+ * to `z.string()` refinements, etc.
+ *
+ * Length lives on `whereby` as Bound pairs, which adapters forward as
+ * `minLength`/`maxLength`; `hints` never duplicates it — these are the
+ * orthogonal, non-length constraints.
+ */
+export type JsonSchema = {
+    format?: string;
+    pattern?: string;
+};
+/**
+ * A length/composition, drawn via `whereby` — no natural bound to fuzz to,
+ * so unlike `number`/`date` there's no bare form — optionally overridden
+ * by an opaque `as` production, carried alongside `whereby` rather than
+ * replacing it (when `whereby` was already set) so a prior
+ * length/composition survives `as` for future validation.
+ */
+export type Meta = {
+    whereby: Whereby;
+    hints?: JsonSchema | undefined;
+    produce?: never;
+} | {
+    whereby?: Whereby;
+    hints?: JsonSchema | undefined;
+    produce: Produce<Fabricated>;
+};
+export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {}> = {
+    [Kind]: "string";
+    [Meta]: $Meta;
+    readonly [Produces]?: Fabricated;
+    readonly [Adaptation]?: $Adaptations;
+};

package/dist/types/Primitive/string/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./Constants";
+export * from "./Fabricator";
+export * from "./Registry";
+export { default } from "./Registry";
+export * from "./Schema";
+export * from "./Types";

package/dist/types/Primitive/symbol/Fabricator.d.ts

@@ -0,0 +1,24 @@
+import type { AdaptationsOf } from "../../Adapter/Types";
+import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
+import type { Trace } from "../../Random/Types";
+import { Kind, Meta, type Adaptation } from "../../Types";
+import { Schema } from "./Schema";
+import type { Fabricated, Meta as ThisMeta } from "./Types";
+export type Fabrication<_ extends Fabricator> = Fabricated;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = NaiveFabricator<Fabricated> & {
+    [Kind]: "symbol";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    schema: Schema<$Schema[typeof Meta], AdaptationsOf<$Schema>>;
+};
+/**
+ * A bare symbol draws no randomness at all — `Symbol(meta.key)` is
+ * deterministic — so only the `.as(...)`-overridden path ever obtains a
+ * stream. The bare path still records `trace`, like every other node.
+ */
+export declare function Fabricator(context: FabricatorContext<Schema>): Fabricator;

package/dist/types/Primitive/symbol/Registry.d.ts

@@ -0,0 +1,16 @@
+import type { Adaptations } from "../../Adapter/Types";
+import { Adaptation, Kind, Meta, Produces } from "../../Types";
+import { Schema } from "./Schema";
+import type { Fabricated } from "./Types";
+declare const _default: {
+    [Kind]: "symbol";
+    [Meta]: {};
+    [Produces]?: Fabricated;
+    [Adaptation]?: Adaptations;
+    as: (produce: import("../../Random/Types").Produce<Fabricated>) => Schema<{}, Adaptations>;
+    adapt: <const $Adapter extends import("../..").Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: import("../..").Adapting<Schema<{}, Adaptations>>) => $Returnable) => Schema<{}, import("../../Adapter/Types").WithAdaptations<Adaptations, import("../../Adapter/Core").AdaptationEntry<$Adapter, $Returnable>>>;
+    keyed: (key: string) => Schema<{
+        key: string;
+    }, {}>;
+};
+export default _default;

package/dist/types/Primitive/symbol/Schema.d.ts

@@ -0,0 +1,24 @@
+import { type AdaptationEntry } from "../../Adapter/Core";
+import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
+/**
+ * `$Meta` is generic (defaulting to the full `Meta` union) so builder
+ * return types stay narrow — see `number/Schema.ts`. `$Adaptations` is
+ * threaded through every builder method for the same reason — see
+ * `string/Schema.ts`'s `adapt`.
+ */
+export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends Adaptations = {}> extends Core<$Meta, $Adaptations> {
+    /**
+     * Layer an opaque production on this schema's existing `[Meta]` — carrying
+     * `key` forward, not discarding it, so a later `.as(...)` (or future
+     * validation of `produce`) still has it to check against.
+     */
+    as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
+    /**
+     * Override what this schema maps to in one or more external schema
+     * libraries — see `string/Schema.ts`'s `adapt` for the full contract.
+     */
+    adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Meta, $Adaptations>>) => $Returnable) => Schema<$Meta, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
+}
+export declare function Schema<$Meta extends ThisMeta, $Adaptations extends Adaptations = {}>(schema: Core<$Meta, $Adaptations>): Schema<$Meta, $Adaptations>;

package/dist/types/Primitive/symbol/Types.d.ts

@@ -0,0 +1,19 @@
+import type { Adaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { Adaptation, Kind, Meta, Produces } from "../../Types";
+export type Fabricated = symbol;
+/**
+ * A symbol keyed via `keyed`, or unkeyed if `key` is absent, optionally
+ * overridden by an opaque `as` production — carried alongside `key` rather
+ * than replacing it, so a prior keying survives `as` for future validation.
+ */
+export type Meta = {
+    key?: string;
+    produce?: Produce<Fabricated>;
+};
+export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {}> = {
+    [Kind]: "symbol";
+    [Meta]: $Meta;
+    readonly [Produces]?: Fabricated;
+    readonly [Adaptation]?: $Adaptations;
+};

package/dist/types/Primitive/symbol/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Types";
+export * from "./Schema";
+export * from "./Fabricator";
+export * from "./Registry";
+export { default } from "./Registry";

package/dist/types/Primitive/tuple/Fabricator.d.ts

@@ -0,0 +1,37 @@
+import type { AdaptationsOf } from "../../Adapter/Types";
+import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
+import type { Trace } from "../../Random/Types";
+import { Children, Kind, Meta, type Adaptation } from "../../Types";
+import { Schema } from "./Schema";
+import type { Fabricated, Items, Meta as ThisMeta } from "./Types";
+export type Fabrication<$Fabricator extends Fabricator> = $Fabricator extends Fabricator<infer $Schema extends {
+    [Meta]: ThisMeta;
+}> ? Fabricated<$Schema[typeof Meta]["items"]> : never;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = NaiveFabricator<Fabricated<$Schema[typeof Meta]["items"]>> & {
+    [Kind]: "tuple";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    [Children]: ReadonlyArray<NaiveFabricator<any>>;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    schema: Schema<$Schema[typeof Meta]["items"], AdaptationsOf<$Schema>>;
+};
+/**
+ * `elements` are each slot's *already-dispatched* Fabricator, one per
+ * `[Meta].items` entry, built by `Constructor.ts`'s `make` before this call —
+ * mirrors `choice.Fabricator`'s `weightings`, one per option, rather than
+ * `array.Fabricator`'s single shared `element`. The `array`/`tuple`
+ * distinction: each slot gets its own private stream, so
+ * `T.tuple([T.number, T.number])` behaves like a two-field `object` of
+ * numbers, not a length-2 `array` of numbers (every element drawn
+ * sequentially off one shared stream).
+ *
+ * `toStreamFromTrace` is only consulted on the `.as(...)`-overridden path: an
+ * ordinary tuple draws no randomness of its own — every draw belongs to a
+ * slot, exactly like `object`. `trace` is still recorded so a nested
+ * tuple can be replayed from its own schema.
+ */
+export declare function Fabricator<$Items extends Items>(context: FabricatorContext<Schema<$Items>>, elements: ReadonlyArray<NaiveFabricator<any>>): Fabricator<Schema<$Items>>;

package/dist/types/Primitive/tuple/Registry.d.ts

@@ -0,0 +1,3 @@
+import { Schema } from "./Schema";
+import type { Items } from "./Types";
+export default function <const $Items extends Items>(items: $Items): Schema<$Items>;

package/dist/types/Primitive/tuple/Schema.d.ts

@@ -0,0 +1,24 @@
+import { type AdaptationEntry } from "../../Adapter/Core";
+import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { Core, Fabricated, Items } from "./Types";
+/**
+ * Buildable `tuple` recipe: a fixed-length list of slot schemas, each
+ * fabricated independently — see `Fabricator.ts` for why that independence
+ * (one Fabricator per slot, not one reused across slots like `array`'s
+ * single element) is the defining difference from `array`.
+ */
+export interface Schema<$Items extends Items = Items, $Adaptations extends Adaptations = {}> extends Core<$Items, $Adaptations> {
+    /**
+     * Layer an opaque production on this schema's existing `[Meta]` — carrying
+     * `items` forward, not discarding it, so a later `.as(...)` (or future
+     * validation of `produce`) still has it to check against.
+     */
+    as: (produce: Produce<Fabricated<$Items>>) => Schema<$Items, $Adaptations>;
+    /**
+     * Override what this schema maps to in one or more external schema
+     * libraries — see `string/Schema.ts`'s `adapt` for the full contract.
+     */
+    adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Items, $Adaptations>>) => $Returnable) => Schema<$Items, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
+}
+export declare function Schema<$Items extends Items, $Adaptations extends Adaptations = {}>(schema: Core<$Items, $Adaptations>): Schema<$Items, $Adaptations>;

package/dist/types/Primitive/tuple/Types.d.ts

@@ -0,0 +1,53 @@
+import type { Adaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { AnySchema, ValueOf } from "../../Schema/Types";
+import type { Adaptation, Kind, Meta, Produces } from "../../Types";
+/** The schema occupying a single tuple slot. */
+export type Item = AnySchema;
+/**
+ * A *tuple* of schemas, one per slot — not a flattened `ReadonlyArray`, for
+ * the same reason `choice.Items` isn't (see its doc): a widened array
+ * remembers only the union of every slot's type and loses arity and which
+ * slot held what. The real tuple is what lets `Fabricated` resolve to
+ * positional `[A, B]` rather than `(A | B)[]`, and `Adapter/TypeBox` produce
+ * a `TTuple` of the right length.
+ */
+export type Items = ReadonlyArray<Item>;
+/**
+ * Head/tail recursion, not a homomorphic `{ [$K in keyof $Items]: ... }`
+ * mapped type — the same trap `Adapter/TypeBox`'s `ChoiceOptions`/
+ * `TupleItems` avoid: `keyof` a still-abstract `ReadonlyArray<Item>` (this
+ * type's default, and what a kind-local `Fabrication<$Fabricator>` resolves
+ * against for the *bare*, unparameterized `Fabricator`) pulls in
+ * `"length"`/method keys that don't resolve to a sensible `ValueOf`. A
+ * homomorphic version type-checks for any concrete tuple but silently
+ * produces a malformed bare type, which then fails `.schema.as`'s
+ * contravariant parameter check against any concrete instantiation
+ * (`Fabrication.types.test.ts`). Matching a fixed-length tuple pattern at
+ * every step avoids it, as `TupleItems` does for `ToTypeBox`. The fallback
+ * (a genuinely widened, arity-less array) is a plain `Array<...>`, mirroring
+ * `array.Fabricated` for the same bare case.
+ */
+export type Fabricated<$Items extends Items = Items, $Bindings extends unknown[] = []> = $Items extends readonly [] ? [] : $Items extends readonly [
+    infer $Head extends Item,
+    ...infer $Rest extends Items
+] ? [ValueOf<$Head, $Bindings>, ...Fabricated<$Rest, $Bindings>] : Array<ValueOf<$Items[number], $Bindings>>;
+/**
+ * No `whereby`: arity is fixed at `T.tuple([...])` and there is nothing left
+ * to configure. Unlike `array`'s two-variant union this needs no
+ * "config or produce" split — `produce` is a plain optional layered on top,
+ * and `items` stays required so `extend`-less kinds still have the per-slot
+ * shapes `ToTypeBox` derives from (and future validation of `produce` would
+ * check against).
+ */
+export type Meta<$Items extends Items = Items> = {
+    items: $Items;
+    produce?: Produce<Fabricated<$Items>>;
+};
+export interface Core<$Items extends Items = Items, $Adaptations extends Adaptations = {}> {
+    [Kind]: "tuple";
+    [Meta]: Meta<$Items>;
+    bindings?: unknown[];
+    readonly [Produces]?: Fabricated<$Items, NonNullable<this["bindings"]>>;
+    readonly [Adaptation]?: $Adaptations;
+}

package/dist/types/Primitive/tuple/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Types";
+export * from "./Schema";
+export * from "./Fabricator";
+export * from "./Registry";
+export { default } from "./Registry";

package/dist/types/Primitive/undefinable/Fabricator.d.ts

@@ -0,0 +1,31 @@
+import type { AdaptationsOf } from "../../Adapter/Types";
+import type { Fabricator as BaseFabricator, FabricatorContext } from "../../Fabricator/Types";
+import type { Trace } from "../../Random/Types";
+import { Children, Kind, Meta, type Adaptation } from "../../Types";
+import { Schema } from "./Schema";
+import type { Definition, Fabricated, Meta as ThisMeta } from "./Types";
+export type Fabrication<$Fabricator extends Fabricator> = $Fabricator extends Fabricator<infer $Schema> ? Fabricated<$Schema[typeof Meta]["definition"]> : never;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = {
+    [Kind]: "undefinable";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    [Children]: BaseFabricator<any>;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    schema: Schema<$Schema[typeof Meta]["definition"], AdaptationsOf<$Schema>>;
+    fabricate: () => Fabricated<$Schema[typeof Meta]["definition"]>;
+};
+/**
+ * A presence roll on this field's private stream, drawn only when the
+ * wrapped value is needed — an `undefined` roll never advances `source`'s
+ * stream, and since `source` is already dispatched into its own independent
+ * stream by `Constructor.ts` regardless of this roll, skipping its draw
+ * here can never perturb any other field's reproducibility (see
+ * `object/omittable/Fabricator.ts`, and CLAUDE.md's "Randomness"). 50/50 by
+ * default; `.weighted(...)` (`Schema.ts`) reweights either outcome relative
+ * to that same default of `1`.
+ */
+export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, source: BaseFabricator<any>): Fabricator<Schema<$Definition>>;

package/dist/types/Primitive/undefinable/Outcomes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The two outcomes an undefinable roll can land on. Also the key space
+ * `.weighted(...)` weighs — see `Types.ts`'s `Weights`.
+ *
+ * Lives here rather than `Types.ts` so that file stays type-only (see
+ * `boolean/Outcomes.ts`).
+ */
+export declare const outcomes: readonly ["undefined", "value"];
+export type Outcome = (typeof outcomes)[number];

package/dist/types/Primitive/undefinable/Registry.d.ts

@@ -0,0 +1,3 @@
+import { Schema } from "./Schema";
+import type { Definition } from "./Types";
+export default function <const $Definition extends Definition>(definition: $Definition): Schema<$Definition>;

package/dist/types/Primitive/undefinable/Schema.d.ts

@@ -0,0 +1,36 @@
+import { type AdaptationEntry } from "../../Adapter/Core";
+import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { AnySchema } from "../../Schema/Types";
+import type { Core, Definition, Fabricated, Weights } from "./Types";
+/**
+ * The buildable recipe for an `undefinable`: a single wrapped Schema, drawn
+ * (or not) each fabrication.
+ */
+export interface Schema<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> extends Core<$Definition, $Adaptations> {
+    /**
+     * Layer an opaque production on this schema's existing `[Meta]` — carrying
+     * `definition` forward, not discarding it, so a later `.as(...)` (or
+     * future validation of `produce`) still has it to check against.
+     * `produce` may return `undefined`, so custom logic composes the same way
+     * the built-in roll does.
+     */
+    as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
+    /**
+     * Reweight the built-in 50/50 roll. Keys are optional — an omitted key
+     * keeps baseline weight `1`, the same weight the 50/50 split already uses
+     * — but that baseline is still relative to whatever else is specified, so
+     * `.weighted({ undefined: 0.1 })` shifts both outcomes' shares, not just
+     * `undefined`'s (see `Types.ts`'s `Weights`). Chaining `.weighted(...)`
+     * merges into previous weights rather than replacing them, the same
+     * layering `.as(...)` uses for `produce`.
+     */
+    weighted: (weights: Weights) => Schema<$Definition, $Adaptations>;
+    /**
+     * Override what this schema maps to in one or more external schema
+     * libraries — see `string/Schema.ts`'s `adapt` for the full contract.
+     */
+    adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Definition, $Adaptations>>) => $Returnable) => Schema<$Definition, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
+}
+export declare function Schema<$Definition extends Definition, $Adaptations extends Adaptations = {}>(schema: Core<$Definition, $Adaptations>): Schema<$Definition, $Adaptations>;
+export declare function isUndefinableSchema(candidate: AnySchema): candidate is Schema;

package/dist/types/Primitive/undefinable/Types.d.ts

@@ -0,0 +1,48 @@
+import type { Adaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { AnySchema, ValueOf } from "../../Schema/Types";
+import type { Adaptation, Kind, Meta, Produces } from "../../Types";
+/** The wrapped schema — the value type produced when the roll isn't `undefined`. */
+export type Definition = AnySchema;
+export type Fabricated<$Definition extends Definition, $Bindings extends unknown[] = []> = ValueOf<$Definition, $Bindings> | undefined;
+export type { Outcome } from "./Outcomes";
+/**
+ * Relative weights for `.weighted(...)`, keyed by `Outcome`. Keys optional —
+ * an omitted key falls back to baseline `1`, the same weight the 50/50
+ * split already uses. Values are relative, exactly like `weighted()`
+ * (`Distribution/index.ts`) — they need not sum to one, and are fed to
+ * `weighted()` unchanged alongside each unspecified key's baseline `1`.
+ *
+ * Specifying one outcome's weight shifts the *other* outcome's resulting
+ * probability too, even though its weight stays at `1` — its share of the
+ * total still moves, since the total changed. `.weighted({ undefined: 0.1 })`
+ * is not "10% undefined, 90% present" — with `value` at default `1`, the
+ * split is `0.1 / 1.1 ≈ 9.1%` undefined, `≈90.9%` value. No independent
+ * "absolute probability" mode; weights are only meaningful relative to the
+ * full set in play.
+ */
+export type Weights = {
+    undefined: number;
+    value?: number | undefined;
+} | {
+    undefined?: number | undefined;
+    value: number;
+};
+/**
+ * `definition` stays required regardless of `produce` — an opaque `as`
+ * production layers on top rather than replacing it, so a prior definition
+ * survives `as` for future validation of `produce` (and so `ToTypeBox`'s
+ * structural derivation of the wrapped shape keeps working either way).
+ */
+export type Meta<$Definition extends Definition = Definition> = {
+    definition: $Definition;
+    produce?: Produce<Fabricated<$Definition>>;
+    weights?: Weights;
+};
+export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
+    [Kind]: "undefinable";
+    [Meta]: Meta<$Definition>;
+    bindings?: unknown[];
+    readonly [Produces]?: Fabricated<$Definition, NonNullable<this["bindings"]>>;
+    readonly [Adaptation]?: $Adaptations;
+}

package/dist/types/Primitive/undefinable/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./Fabricator";
+export * from "./Outcomes";
+export * from "./Registry";
+export { default } from "./Registry";
+export * from "./Schema";
+export * from "./Types";