@ghostry/fabricator 0.0.1

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

@@ -0,0 +1,56 @@
+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 type { Schema } from "./Schema";
+import type { Definition, Fabricated, Override, 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<any>;
+}> = {
+    [Kind]: "object";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    [Children]: Fields;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    schema: Schema<$Schema[typeof Meta]["definition"], AdaptationsOf<$Schema>>;
+    /**
+     * `overrides`, if given, skips generation for exactly the fields it names —
+     * using this Fabricator's already-derived randomness for everything else,
+     * never drawing fresh (see `Fabricator()` below). `config.validate` defaults
+     * to `true`, delegated to `schema.override(overrides)`'s existing recursive
+     * checks (result unused); `{ validate: false }` skips that — used internally
+     * when recursing into an already-validated nested override, also available
+     * to a caller who already knows their overrides are valid.
+     */
+    fabricate: (overrides?: Override<$Schema[typeof Meta]["definition"]>, config?: {
+        validate?: boolean;
+    }) => Fabricated<$Schema[typeof Meta]["definition"]>;
+};
+export declare function isObjectFabricator(candidate: BaseFabricator<unknown>): candidate is Fabricator;
+export type Fields = Record<string, BaseFabricator<unknown>>;
+/**
+ * Turn an `object` Schema into a live Fabricator, given every field already
+ * built by `Constructor.ts` — which owns recursion into nested Schemas, so
+ * `object` never calls `construct()` and there's no import cycle with
+ * `Constructor.ts`. Schema-baked `.override()`-marked fields (`[Fixed]` in
+ * `Types.ts`) are already resolved into literal-valued `fields` entries
+ * before they reach here. `fabricate`'s `overrides` (below) is a separate
+ * per-call mechanism; the two compose.
+ *
+ * `schema` is echoed as `.schema` unchanged — callers wanting a
+ * `toSchema`-normalized Fabricator (no `extend`/`refine`/`override`) pass
+ * that; `Constructor.ts`'s `make` passes `object.rehydrate(...)` so a
+ * top-level built Fabricator's `.schema` still composes.
+ *
+ * A compute-kind field (from `.refine()`) needs the rest of the object
+ * already fabricated (`object/compute/Fabricator.ts`), which isn't available
+ * until every ordinary field has resolved. Two phases: ordinary fields
+ * first, then compute fields against the accumulated result, in definition
+ * order (a compute field can see an earlier compute field's value, not a
+ * later one) — unless covered by `overrides`, in which case it resolves in
+ * phase 1 like any other overridden field.
+ */
+export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, fields: Fields): Fabricator<Schema<$Definition>>;

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

@@ -0,0 +1,23 @@
+import type { Adaptations } from "../../Adapter/Types";
+import { Adaptation, Meta } from "../../Types";
+import { Schema } from "./Schema";
+import type { Definition, Meta as ThisMeta } from "./Types";
+/**
+ * Rebuild a full `object` Schema — with `extend`/`refine` restored — from
+ * anything already reduced to this kind's `[Meta]` (a bare Schema, or a
+ * built Fabricator normalized via `toSchema`). `toSchema` alone only keeps
+ * `[Kind]`/`[Meta]`, enough to fabricate from but not to derive a subtype —
+ * this is what lets a built Fabricator's `.schema` still compose via
+ * `extend`/`refine` (`Constructor.ts`'s `make`). Reattaches `produce` via
+ * `.as(...)` when present, so a `toSchema`-stripped, `.as(...)`-produced
+ * schema doesn't lose its custom producer — and carries `[Adaptation]` for
+ * the same reason: without it, `.override(...)` on a nested adapted
+ * `object` field (which round-trips through here) and a built Fabricator's
+ * `.schema` would both silently come back unadapted.
+ */
+export declare function rehydrate<$Definition extends Definition, $Adaptations extends Adaptations = {}>(schema: {
+    [Meta]: ThisMeta<$Definition>;
+    readonly [Adaptation]?: $Adaptations;
+}): Schema<$Definition, $Adaptations>;
+export default _default;
+declare function _default<const $Definition extends Definition>(definition: $Definition): Schema<$Definition>;

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

@@ -0,0 +1,41 @@
+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 { ShallowMerge } from "../../Utility/ShallowMerge";
+import type { Computer } from "./compute/Schema";
+import type { Core, Definition, Extender, Fabricated, Override, Refinement } from "./Types";
+export type Refiner<$Definition extends Definition, $Refinement extends Refinement<$Definition>> = (params: {
+    base: Schema<$Definition>;
+    compute: Computer<$Definition>;
+}) => $Refinement;
+export interface Schema<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> extends Core<$Definition, $Adaptations> {
+    extend: <const $Extension extends Definition>(extender: Extender<$Definition, $Extension>) => Schema<ShallowMerge<$Definition, $Extension>, $Adaptations>;
+    refine: <const $Refinement extends Refinement<$Definition>>(refiner: Refiner<$Definition, $Refinement>) => Schema<ShallowMerge<$Definition, $Refinement>, $Adaptations>;
+    override: (override: Override<$Definition>) => Schema<$Definition, $Adaptations>;
+    /**
+     * Layer an opaque production on this schema's existing `[Meta]` — carrying
+     * `definition`/`refinements` forward, not discarding them, so
+     * `extend`/`refine`/`override` keep working (they drop the custom producer
+     * again, falling back to definition-based fabrication) and a later
+     * `.as(...)` (or future validation of `produce`) still has the definition
+     * to check against.
+     */
+    as: (produce: Produce<Fabricated<$Definition>>) => 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.
+     * Carried through `extend`/`refine`/`override`, which all reduce to a
+     * fresh `make(...)` (`Registry.ts`) over this same schema.
+     */
+    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>>>;
+}
+/**
+ * Unlike every other kind, `adapt` is *not* added here but by `Registry.ts`'s
+ * `make` alongside `extend`/`refine`/`override`: those three rebuild from
+ * `definition`/`refinements` rather than deriving from this object, so the
+ * adaptation map has to be threaded through `make` itself or chaining one
+ * of them would drop it (see `make`'s `adapt`).
+ */
+export declare function Schema<$Definition extends Definition, $Adaptations extends Adaptations = {}>(schema: Omit<Schema<$Definition, $Adaptations>, "as">): Schema<$Definition, $Adaptations>;
+export declare function isObjectSchema(candidate: AnySchema): candidate is Schema;

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

@@ -0,0 +1,85 @@
+import type { Adaptations } from "../../Adapter/Types";
+import type { Produce } from "../../Random/Types";
+import type { AnySchema, ValueOf } from "../../Schema/Types";
+import { Kind, Meta, type Adaptation, type Omitted, type Produces } from "../../Types";
+import { type Pretty } from "../../Utility/Types";
+import type { Schema as ComputeSchema } from "./compute/Schema";
+export type Definition<$Schema = AnySchema> = {
+    [_ in string]: $Schema;
+};
+/**
+ * Constraint for a refinement's values. The source schema differs per
+ * property, so it must be `any` (not `AnySchema`) to stay assignable across
+ * every property's own `$Source`. Constraint only: precise types still flow
+ * via `$Refinement`.
+ */
+export type Refinement<$Definition extends Definition> = Definition<ComputeSchema<Fabricated<$Definition>, any>>;
+export type Extender<$Definition extends Definition, $Extension extends Definition> = (params: {
+    base: $Definition;
+}) => $Extension;
+export type Refinements = ReadonlyArray<Definition>;
+/**
+ * Every `object.omittable`- or `object.optional`-kind field's key, so
+ * `Fabricated` can mark exactly those `?:` instead of required — matching
+ * runtime, where a field whose roll lands on omission never has its key
+ * appear (`object/omittable/Fabricator.ts`, `object/optional/Fabricator.ts`).
+ * `object.optional`'s `ValueOf` already carries `| undefined` (its
+ * `Fabricated`), so combined with the `?:` here a field lands on
+ * `{ a?: T | undefined }` — omitted, present-as-`undefined`, or
+ * present-with-a-value.
+ */
+type OmittableKeys<$Definition extends Definition> = {
+    [$K in keyof $Definition]: $Definition[$K] extends {
+        [Kind]: "object.omittable" | "object.optional";
+    } ? $K : never;
+}[keyof $Definition];
+export type Fabricated<$Definition extends Definition, $Bindings extends unknown[] = []> = Pretty<{
+    [$K in Exclude<keyof $Definition, OmittableKeys<$Definition>>]: ValueOf<$Definition[$K], $Bindings>;
+} & {
+    [$K in OmittableKeys<$Definition>]?: ValueOf<$Definition[$K], $Bindings>;
+}>;
+/**
+ * The shape `.override()` accepts: every field optional, so a present key
+ * skips generation for that field. A nested `object`-kind field recurses
+ * into its own `Override` (deep-merge); an `object.omittable` or
+ * `object.optional` field additionally accepts `Omitted`, to force that
+ * field off rather than only forcing a value on (`object.optional` already
+ * accepts `undefined` via `ValueOf`); every other field — including
+ * `object.compute` — is a full-replacement leaf, typed as whatever it
+ * fabricates to (`ValueOf`).
+ *
+ * Checked via a bare structural `[Kind]`/`[Meta]` shape, never `Schema`/
+ * `Fabricator` — either carries `refine`'s contravariant use of
+ * `$Definition`, and referencing it here would leak that contravariance
+ * into every recursive `Override` instantiation.
+ */
+export type Override<$Definition extends Definition> = Pretty<{
+    [$K in keyof $Definition]?: $Definition[$K] extends {
+        [Kind]: "object";
+        [Meta]: {
+            definition: infer $Nested extends Definition;
+        };
+    } ? Override<$Nested> : $Definition[$K] extends {
+        [Kind]: "object.omittable" | "object.optional";
+    } ? ValueOf<$Definition[$K]> | typeof Omitted : ValueOf<$Definition[$K]>;
+}>;
+/**
+ * `definition`/`refinements` stay required regardless of `produce` — an
+ * opaque `as` production layers on top rather than replacing them, so
+ * `extend`/`refine`/`override` and `ToTypeBox`'s structural derivation keep
+ * working, and a prior definition survives `as` for future validation of
+ * `produce`.
+ */
+export type Meta<$Definition extends Definition = Definition> = {
+    definition: $Definition;
+    refinements: Refinements;
+    produce?: Produce<Fabricated<$Definition>>;
+};
+export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
+    [Kind]: "object";
+    [Meta]: Meta<$Definition>;
+    bindings?: unknown[];
+    readonly [Produces]?: Fabricated<$Definition, NonNullable<this["bindings"]>>;
+    readonly [Adaptation]?: $Adaptations;
+}
+export {};

package/dist/types/Primitive/object/compute/Fabricator.d.ts

@@ -0,0 +1,31 @@
+import type { Adaptations } from "../../../Adapter/Types";
+import type { Fabricator as BaseFabricator, FabricatorContext } from "../../../Fabricator/Types";
+import type { Trace } from "../../../Random/Types";
+import { Kind, Meta, type Adaptation } from "../../../Types";
+import type { Schema } from "./Schema";
+import type { Resolved, Source } from "./Types";
+export type Fabrication<$Fabricator extends Fabricator<any, Source>> = $Fabricator extends Fabricator<any, infer $Source> ? Resolved<$Source> : never;
+export type Fabricator<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> = {
+    [Kind]: "object.compute";
+    [Meta]: {
+        source: $Source;
+        resolve: (params: {
+            fabricated: $Fabricated;
+        }) => Resolved<$Source>;
+    };
+    readonly trace: Trace;
+    readonly [Adaptation]?: $Adaptations;
+    fabricate: (params?: {
+        fabricated: $Fabricated;
+    }) => Resolved<$Source>;
+};
+export declare function isObjectComputeFabricator(candidate: BaseFabricator<unknown>): candidate is Fabricator<unknown, Source>;
+/**
+ * Turn an `object.compute` Schema into a live Fabricator. Unlike every other
+ * kind, there's nothing of `source` to build here — a computed field's
+ * value comes entirely from `resolve`, given the rest of the object. The
+ * node still records `trace` so it can be rebuilt from a parent field's
+ * captured trace; `.fabricate()` without the parent object throws
+ * `DetachedComputeError`.
+ */
+export declare function Fabricator<$Fabricated, $Source extends Source>(context: FabricatorContext<Schema<$Fabricated, $Source>>): Fabricator<$Fabricated, $Source>;

package/dist/types/Primitive/object/compute/Registry.d.ts

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

package/dist/types/Primitive/object/compute/Schema.d.ts

@@ -0,0 +1,21 @@
+import { type AdaptationEntry } from "../../../Adapter/Core";
+import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../../Adapter/Types";
+import type { AnySchema } from "../../../Schema/Types";
+import type * as object from "../Types";
+import type { Core, Resolved, Source } from "./Types";
+export type Computer<$Definition extends object.Definition> = <const $Source extends Source>(source: $Source) => {
+    as: (resolve: (params: {
+        fabricated: object.Fabricated<$Definition>;
+    }) => NoInfer<Resolved<$Source>>) => Schema<object.Fabricated<$Definition>, $Source>;
+};
+export interface Schema<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> extends Core<$Fabricated, $Source, $Adaptations> {
+    /**
+     * Override what this schema maps to in one or more external schema
+     * libraries — see `string/Schema.ts`'s `adapt` for the full contract.
+     * Adapting the computed field itself, rather than the `source` it derives
+     * its shape from, is the way to say the two differ.
+     */
+    adapt: <const $Adapter extends Adapter, $Returnable extends ReturnType<$Adapter["convert"]>>(adapter: $Adapter, produce: (adapting: Adapting<Schema<$Fabricated, $Source, $Adaptations>>) => $Returnable) => Schema<$Fabricated, $Source, WithAdaptations<$Adaptations, AdaptationEntry<$Adapter, $Returnable>>>;
+}
+export declare function Schema<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}>(schema: Core<$Fabricated, $Source, $Adaptations>): Schema<$Fabricated, $Source, $Adaptations>;
+export declare function isObjectComputeSchema(candidate: AnySchema): candidate is Schema<unknown, Source>;

package/dist/types/Primitive/object/compute/Types.d.ts

@@ -0,0 +1,56 @@
+import type { Adaptations } from "../../../Adapter/Types";
+import type { AnySchema, ValueOf } from "../../../Schema/Types";
+import { Kind, type Adaptation, type Meta, type Produces } from "../../../Types";
+/**
+ * A builder that can mint a Schema via `as` — e.g. `T.string`, `T.bigint`.
+ * `compute` accepts one alongside a plain Schema so a caller needn't
+ * satisfy a `whereby` just to name a computed field's type: the resolver
+ * supplies the value, so the field's length/range is irrelevant.
+ */
+export type Builder<$Schema extends AnySchema = AnySchema> = {
+    [Kind]: $Schema[typeof Kind];
+    as: (produce: () => any) => $Schema;
+};
+/**
+ * A `compute` source: the Schema whose value and shape a computed field
+ * adopts, or a builder that denotes one.
+ */
+export type Source = AnySchema | Builder;
+/**
+ * The Schema a source denotes: a plain Schema is itself; a builder is
+ * the Schema its `as` mints.
+ */
+export type Denoted<$Source> = $Source extends AnySchema ? $Source : $Source extends Builder<infer $Schema> ? $Schema : never;
+/**
+ * The value a source resolves to: what the Schema it denotes fabricates to.
+ */
+export type Resolved<$Source, $Bindings extends unknown[] = []> = ValueOf<Denoted<$Source>, $Bindings>;
+/**
+ * Source and resolver are stored raw — the source whether a Schema or a
+ * builder (both carry a `[Kind]`, which is all schema derivation needs),
+ * and the resolver as plain data from the moment
+ * `compute(source).as(resolve)` is called: `compute` never builds anything,
+ * so unlike a Fabricator's closure there's nothing lossy about storing it.
+ * `source` is only used for its shape/type (`Adapter/TypeBox` reflects a
+ * computed field as its source's shape, unless the field itself is
+ * adapted) — the resolver draws entirely from `fabricated`, never from
+ * `source`, which may not even have a buildable recipe (a bare
+ * `T.string`/`T.bigint`).
+ *
+ * Unlike every other kind's `Meta`, this one is generic over the *enclosing
+ * object's* fabricated type as well as the source — that is what the
+ * resolver is handed.
+ */
+export type Meta<$Fabricated, $Source extends Source> = {
+    source: $Source;
+    resolve: (params: {
+        fabricated: $Fabricated;
+    }) => Resolved<$Source>;
+};
+export interface Core<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> {
+    [Kind]: "object.compute";
+    [Meta]: Meta<$Fabricated, $Source>;
+    bindings?: unknown[];
+    readonly [Produces]?: Resolved<$Source, NonNullable<this["bindings"]>>;
+    readonly [Adaptation]?: $Adaptations;
+}

package/dist/types/Primitive/object/compute/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/object/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./Types";
+export * from "./Schema";
+export * from "./Fabricator";
+export * from "./Registry";
+export { default } from "./Registry";
+export * as compute from "./compute";
+export * as omittable from "./omittable";
+export * as optional from "./optional";

package/dist/types/Primitive/object/omittable/Fabricator.d.ts

@@ -0,0 +1,37 @@
+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 type { Schema } from "./Schema";
+import type { Definition, Resolved, Meta as ThisMeta } from "./Types";
+export type Fabrication<$Fabricator extends Fabricator<any>> = $Fabricator extends Fabricator<infer $Schema> ? Resolved<$Schema[typeof Meta]["definition"]> : never;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = {
+    [Kind]: "object.omittable";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    [Children]: BaseFabricator<any>;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    /**
+     * `Omitted` on the empty roll (or when an `.as(...)` producer returns it)
+     * — read only by `object/Fabricator.ts`'s fabricate loop, which omits the
+     * key entirely rather than writing `undefined`. Fabricating this outside
+     * a parent `object` hands the sentinel straight back.
+     */
+    fabricate: () => Resolved<$Schema[typeof Meta]["definition"]>;
+};
+export declare function isObjectOmittableFabricator(candidate: BaseFabricator<unknown>): candidate is Fabricator;
+/**
+ * A presence roll on this field's private stream, drawn only when present
+ * is decided — an omission 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 (`Random/index.ts`'s
+ * `toStreamFromTrace`: every field's stream is private from the moment it's
+ * minted). 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/object/omittable/Outcomes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The two outcomes an omittable field's presence 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 ["omitted", "value"];
+export type Outcome = (typeof outcomes)[number];

package/dist/types/Primitive/object/omittable/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/object/omittable/Schema.d.ts

@@ -0,0 +1,32 @@
+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, Resolved, Weights } from "./Types";
+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 `Omitted`, so custom presence logic composes the
+     * same way the built-in roll does.
+     */
+    as: (produce: Produce<Resolved<$Definition>>) => Schema<$Definition, $Adaptations>;
+    /**
+     * Reweight the built-in presence 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({ omitted: 0.1 })` shifts both outcomes' shares, not just
+     * `omitted`'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 isObjectOmittableSchema(candidate: AnySchema): candidate is Schema;

package/dist/types/Primitive/object/omittable/Types.d.ts

@@ -0,0 +1,57 @@
+import type { Adaptations } from "../../../Adapter/Types";
+import type { Produce } from "../../../Random/Types";
+import type { AnySchema, ValueOf } from "../../../Schema/Types";
+import { Kind, Meta, Omitted, type Adaptation, type Produces } from "../../../Types";
+/**
+ * The wrapped field's own Schema — the value type an omittable field
+ * produces when its presence roll comes up present.
+ */
+export type Definition = AnySchema;
+export type Fabricated<$Definition extends Definition, $Bindings extends unknown[] = []> = ValueOf<$Definition, $Bindings>;
+/**
+ * What an omittable field's Fabricator returns: the wrapped value, or
+ * `Omitted` when it should not appear — whether from the built-in presence
+ * roll or, via `.as(...)`, an opaque producer.
+ */
+export type Resolved<$Definition extends Definition> = Fabricated<$Definition> | typeof Omitted;
+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({ omitted: 0.1 })`
+ * is not "10% omitted, 90% present" — with `value` at default `1`, the
+ * split is `0.1 / 1.1 ≈ 9.1%` omitted, `≈90.9%` present. No independent
+ * "absolute probability" mode; weights are only meaningful relative to the
+ * full set in play.
+ */
+export type Weights = {
+    omitted: number;
+    value?: number | undefined;
+} | {
+    omitted?: 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<Resolved<$Definition>>;
+    weights?: Weights;
+};
+export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
+    [Kind]: "object.omittable";
+    [Meta]: Meta<$Definition>;
+    bindings?: unknown[];
+    readonly [Produces]?: Fabricated<$Definition, NonNullable<this["bindings"]>>;
+    readonly [Adaptation]?: $Adaptations;
+}

package/dist/types/Primitive/object/omittable/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";

package/dist/types/Primitive/object/optional/Fabricator.d.ts

@@ -0,0 +1,45 @@
+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 type { Schema } from "./Schema";
+import type { Definition, Resolved, Meta as ThisMeta } from "./Types";
+export type Fabrication<$Fabricator extends Fabricator<any>> = $Fabricator extends Fabricator<infer $Schema> ? Resolved<$Schema[typeof Meta]["definition"]> : never;
+export type Fabricator<$Schema extends {
+    [Meta]: ThisMeta;
+} = {
+    [Meta]: ThisMeta;
+}> = {
+    [Kind]: "object.optional";
+    [Meta]: $Schema[typeof Meta];
+    readonly trace: Trace;
+    [Children]: BaseFabricator<any>;
+    readonly [Adaptation]?: AdaptationsOf<$Schema>;
+    /**
+     * `Omitted` on the omission roll (or when an `.as(...)` producer returns it)
+     * — read only by `object/Fabricator.ts`'s fabricate loop, which omits the
+     * key entirely rather than writing `undefined`. A "present as `undefined`"
+     * roll returns `undefined` directly, which the loop assigns like any
+     * ordinary value — the difference from `object.omittable`. Fabricating this
+     * outside a parent `object` hands whichever of the three results back
+     * verbatim.
+     */
+    fabricate: () => Resolved<$Schema[typeof Meta]["definition"]>;
+};
+export declare function isObjectOptionalFabricator(candidate: BaseFabricator<unknown>): candidate is Fabricator;
+/**
+ * Three-way roll: omitted, present-as-`undefined`, or the wrapped value —
+ * on this field's private stream; `source` is drawn only when "value" wins.
+ * Uniform (1/3 each) by default; not achievable by composing
+ * `object.omittable(T.undefinable(inner))`'s two independent 50/50 rolls
+ * (that is 50/25/25, not 33/33/33), hence the dedicated three-way
+ * `weighted()` here — see CLAUDE.md's "Why `T.optional` isn't
+ * `omittable(undefinable(inner))`" under "Compound / field-only kinds".
+ * `.weighted(...)` (`Schema.ts`) reweights individual outcomes relative to
+ * that same default of `1`; an unspecified outcome keeps it. Skipping
+ * `source`'s draw on the two non-"value" outcomes is safe for the same
+ * reason as `object/omittable/Fabricator.ts`: `source` already has its own
+ * independent stream, minted at build time regardless of this roll (see
+ * CLAUDE.md's "Randomness").
+ */
+export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, source: BaseFabricator<any>): Fabricator<Schema<$Definition>>;

package/dist/types/Primitive/object/optional/Outcomes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The three outcomes an optional field's 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 ["omitted", "undefined", "value"];
+export type Outcome = (typeof outcomes)[number];

package/dist/types/Primitive/object/optional/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/object/optional/Schema.d.ts

@@ -0,0 +1,32 @@
+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, Resolved, Weights } from "./Types";
+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` or `Omitted`, so custom logic composes the same way
+     * the built-in three-way roll does.
+     */
+    as: (produce: Produce<Resolved<$Definition>>) => Schema<$Definition, $Adaptations>;
+    /**
+     * Reweight the built-in three-way roll. Keys are optional — an omitted key
+     * keeps baseline weight `1`, the same weight the uniform 1/3 split already
+     * uses — but that baseline is still relative to whatever else is specified,
+     * so `.weighted({ omitted: 0.1 })` shifts every outcome's share, not just
+     * `omitted`'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 isObjectOptionalSchema(candidate: AnySchema): candidate is Schema;