@lunora/values 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -1,11 +1,17 @@
+import { LunoraError } from '@lunora/errors';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 type ValidationPath = ReadonlyArray<number | string>;
 /**
-* Thrown by `validator.parse` (or returned inside `safeParse`) when input does
-* not match the validator's shape. `path` walks from the root to the offending
-* value, e.g. `["users", 0, "email"]`.
-*/
-declare class ValidationError extends Error {
+ * Thrown by `validator.parse` (or returned inside `safeParse`) when input does
+ * not match the validator's shape. `path` walks from the root to the offending
+ * value, e.g. `["users", 0, "email"]`.
+ *
+ * A `LunoraError` subclass: carries `code: "VALIDATION_ERROR"` and `status: 400`
+ * so the runtime/DO transport mappers surface it structurally (a request that
+ * fails validation is a 400), while keeping the `name: "ValidationError"` and the
+ * `path`/`expected`/`received` diagnostics.
+ */
+declare class ValidationError extends LunoraError {
   readonly path: ValidationPath;
   readonly expected: string;
   readonly received: string;
@@ -16,35 +22,43 @@ declare class ValidationError extends Error {
   });
 }
 /**
-* Render a short, diagnostic description of a runtime value for the `received`
-* field of a {@link ValidationError}. Primitives carry their concrete (length-
-* capped) literal so messages distinguish `string "7"` from `number 7`;
-* non-plain objects carry their constructor name (e.g. `Date`) so a class
-* instance is not flattened to a bare `"object"`.
-*/
-declare const describeValue: (value: unknown) => string;
+ * Render a short, diagnostic description of a runtime value for the `received`
+ * field of a {@link ValidationError}. Primitives carry their concrete (length-
+ * capped) literal so messages distinguish `string "7"` from `number 7`;
+ * non-plain objects carry their constructor name (e.g. `Date`) so a class
+ * instance is not flattened to a bare `"object"`.
+ *
+ * Pass `{ literal: false }` to suppress the concrete primitive literal and
+ * return only the type tag (`"string"`, `"number"`, `"bigint"`, …). This is used
+ * on `.check()` refinement failures — where the value already passed its type
+ * check — so a secret-bearing field (password, token) never surfaces its value
+ * in the `ValidationError.message`/`received` that goes to the wire and logs.
+ */
+declare const describeValue: (value: unknown, options?: {
+  literal?: boolean;
+}) => string;
 declare const formatPath: (path: ValidationPath) => string;
 /** Branded id type, e.g. `Id&lt;"users">`. */
 type Id<TableName extends string> = string & {
   readonly __table: TableName;
 };
 /**
-* A JSON Schema fragment (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally
-* a loose bag — a `.check()`/`.meta()` caller contributes keywords like
-* `minLength`/`pattern`/`minimum` that `toJsonSchema` shallow-merges onto the
-* node for the enclosing validator. Mirrors the `JsonSchema` shape exported by
-* `./to-json-schema`; kept structurally identical and local so `v.ts` never
-* imports the converter and the two files stay decoupled.
-*/
+ * A JSON Schema fragment (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally
+ * a loose bag — a `.check()`/`.meta()` caller contributes keywords like
+ * `minLength`/`pattern`/`minimum` that `toJsonSchema` shallow-merges onto the
+ * node for the enclosing validator. Mirrors the `JsonSchema` shape exported by
+ * `./to-json-schema`; kept structurally identical and local so `v.ts` never
+ * imports the converter and the two files stay decoupled.
+ */
 interface JsonSchemaFragment {
   [keyword: string]: unknown;
 }
 /**
-* Options for a {@link Validator.check} refinement. Lets a predicate carry both
-* a human-facing `message` and an introspectable JSON Schema `schema` fragment
-* (e.g. `{ minLength: 1 }`) so the constraint flows into `toJsonSchema`. The
-* legacy `.check(pred, "message")` string form remains supported.
-*/
+ * Options for a {@link Validator.check} refinement. Lets a predicate carry both
+ * a human-facing `message` and an introspectable JSON Schema `schema` fragment
+ * (e.g. `{ minLength: 1 }`) so the constraint flows into `toJsonSchema`. The
+ * legacy `.check(pred, "message")` string form remains supported.
+ */
 interface CheckOptions {
   /** Failure message thrown on the `ValidationError` (default `"value matching refinement"`). */
   message?: string;
@@ -52,10 +66,10 @@ interface CheckOptions {
   schema?: JsonSchemaFragment;
 }
 /**
-* Options for {@link Validator.meta} — pure metadata with no runtime parsing
-* effect, used to enrich the emitted JSON Schema node (description + constraint
-* keywords) without attaching a predicate.
-*/
+ * Options for {@link Validator.meta} — pure metadata with no runtime parsing
+ * effect, used to enrich the emitted JSON Schema node (description + constraint
+ * keywords) without attaching a predicate.
+ */
 interface MetaOptions {
   /** A human description merged onto this validator's JSON Schema node. */
   description?: string;
@@ -63,36 +77,36 @@ interface MetaOptions {
   schema?: JsonSchemaFragment;
 }
 /**
-* Runtime "kind" tag attached to every validator. Codegen and reflective tools
-* use this to inspect the shape without crawling the closure.
-*/
-type ValidatorKind = "any" | "array" | "bigint" | "boolean" | "bytes" | "date" | "from" | "id" | "literal" | "null" | "number" | "object" | "optional" | "record" | "storage" | "string" | "timestamp" | "union";
+ * Runtime "kind" tag attached to every validator. Codegen and reflective tools
+ * use this to inspect the shape without crawling the closure.
+ */
+type ValidatorKind = "any" | "array" | "bigint" | "boolean" | "bytes" | "date" | "from" | "geoPoint" | "id" | "literal" | "null" | "number" | "object" | "optional" | "record" | "storage" | "string" | "timestamp" | "union";
 interface Validator<T = unknown> extends StandardSchemaV1<T, T> {
   readonly __type: T;
   /**
-  * Attach a refinement predicate. The returned validator parses with the
-  * original rules first; if the result satisfies `predicate` it passes
-  * through, otherwise it throws a {@link ValidationError} carrying
-  * `message` (default: `"value matching refinement"`). Multiple `.check()`
-  * calls chain — every predicate must return true.
-  *
-  * The second argument may be a plain message string (legacy form) or a
-  * {@link CheckOptions} object that additionally carries a JSON Schema
-  * `schema` fragment (e.g. `{ minLength: 1 }`) reflected by `toJsonSchema`.
-  *
-  * Works in any context — argument validators, column validators, or
-  * standalone — so it can encode invariants like
-  * `v.number().check(n => n >= 0)` or
-  * `v.string().check(s => s.length > 0, { message: "non-empty", schema: { minLength: 1 } })`.
-  */
+   * Attach a refinement predicate. The returned validator parses with the
+   * original rules first; if the result satisfies `predicate` it passes
+   * through, otherwise it throws a {@link ValidationError} carrying
+   * `message` (default: `"value matching refinement"`). Multiple `.check()`
+   * calls chain — every predicate must return true.
+   *
+   * The second argument may be a plain message string (legacy form) or a
+   * {@link CheckOptions} object that additionally carries a JSON Schema
+   * `schema` fragment (e.g. `{ minLength: 1 }`) reflected by `toJsonSchema`.
+   *
+   * Works in any context — argument validators, column validators, or
+   * standalone — so it can encode invariants like
+   * `v.number().check(n => n >= 0)` or
+   * `v.string().check(s => s.length > 0, { message: "non-empty", schema: { minLength: 1 } })`.
+   */
   check: (predicate: (value: T) => boolean, options?: CheckOptions | string) => Validator<T>;
   readonly kind: ValidatorKind;
   /**
-  * Attach pure metadata (description + JSON Schema constraint fragment) with
-  * no effect on runtime parsing. The fragment is shallow-merged onto this
-  * validator's emitted JSON Schema node, composing with any `.check()`
-  * `schema` fragments (later wins on conflicting keys).
-  */
+   * Attach pure metadata (description + JSON Schema constraint fragment) with
+   * no effect on runtime parsing. The fragment is shallow-merged onto this
+   * validator's emitted JSON Schema node, composing with any `.check()`
+   * `schema` fragments (later wins on conflicting keys).
+   */
   meta: (options: MetaOptions) => Validator<T>;
   parse: (value: unknown) => T;
   safeParse: (value: unknown) => {
@@ -106,10 +120,10 @@ interface Validator<T = unknown> extends StandardSchemaV1<T, T> {
 /** Extract the TS type a validator describes (the **select** type). */
 type Infer<V> = V extends Validator<infer T> ? T : never;
 /**
-* Column constraints/defaults collected from the `v.*` modifier chain used
-* inside `defineTable`. Inert in argument position. Persisted on the
-* validator's internal `_meta.column` and mirrored into codegen IR.
-*/
+ * Column constraints/defaults collected from the `v.*` modifier chain used
+ * inside `defineTable`. Inert in argument position. Persisted on the
+ * validator's internal `_meta.column` and mirrored into codegen IR.
+ */
 interface ColumnMeta {
   /** `.$defaultFn(fn)` — default factory; field is optional on insert. */
   defaultFn?: () => unknown;
@@ -120,24 +134,24 @@ interface ColumnMeta {
   /** `.$onUpdateFn(fn)` — recomputed on every patch/replace. */
   onUpdateFn?: () => unknown;
   /**
-  * `.serverDefault(fn)` — a SERVER-trusted value factory. Unlike
-  * `.$defaultFn` (which only fills an absent field), this runs on every
-  * insert/update and SILENTLY OVERWRITES any client-supplied value with
-  * `fn({ auth })`, so the column is never client-controllable (e.g.
-  * `ownerId`/`tenantId` stamped from `auth.userId`). Field is optional on
-  * insert. The factory runs server-side with the resolved request auth.
-  */
+   * `.serverDefault(fn)` — a SERVER-trusted value factory. Unlike
+   * `.$defaultFn` (which only fills an absent field), this runs on every
+   * insert/update and SILENTLY OVERWRITES any client-supplied value with
+   * `fn({ auth })`, so the column is never client-controllable (e.g.
+   * `ownerId`/`tenantId` stamped from `auth.userId`). Field is optional on
+   * insert. The factory runs server-side with the resolved request auth.
+   */
   serverDefault?: (context: ServerDefaultContext) => unknown;
   /** `.unique()` — synthesizes a UNIQUE index. */
   unique?: boolean;
 }
 /**
-* Context handed to a `.serverDefault(fn)` factory at write time. Carries the
-* resolved request identity so a column can be stamped from the caller
-* (`auth.userId`) rather than trusted from the client. Structurally mirrors the
-* `auth` slice of the server's procedure context without depending on
-* `@lunora/server`.
-*/
+ * Context handed to a `.serverDefault(fn)` factory at write time. Carries the
+ * resolved request identity so a column can be stamped from the caller
+ * (`auth.userId`) rather than trusted from the client. Structurally mirrors the
+ * `auth` slice of the server's procedure context without depending on
+ * `@lunora/server`.
+ */
 interface ServerDefaultContext {
   readonly auth: {
     /** The raw identity claims, or `null` for the anonymous/no-resolver case. */
@@ -147,9 +161,9 @@ interface ServerDefaultContext {
   };
 }
 /**
-* Phantom carrier of a column's select/insert types. Never present at runtime;
-* `defineTable` reads it to derive `$inferSelect` / `$inferInsert`.
-*/
+ * Phantom carrier of a column's select/insert types. Never present at runtime;
+ * `defineTable` reads it to derive `$inferSelect` / `$inferInsert`.
+ */
 interface Column<TSelect, TInsert> {
   /** Phantom carrier — type-only, never present at runtime. */
   readonly __column: {
@@ -158,11 +172,11 @@ interface Column<TSelect, TInsert> {
   };
 }
 /**
-* A {@link Validator} carrying the chainable column-modifier API. The factories
-* (`v.string()`, …) return this so modifiers are available inside `defineTable`.
-* `TSelect` is the read type; `TInsert` is the write type (modifiers may make it
-* `| undefined`, marking the field optional on insert).
-*/
+ * A {@link Validator} carrying the chainable column-modifier API. The factories
+ * (`v.string()`, …) return this so modifiers are available inside `defineTable`.
+ * `TSelect` is the read type; `TInsert` is the write type (modifiers may make it
+ * `| undefined`, marking the field optional on insert).
+ */
 interface ColumnValidator<TSelect, TInsert> extends Column<TSelect, TInsert>, Validator<TSelect> {
   /** Default factory applied in the write layer; field becomes optional on insert. */
   $defaultFn: (function_: () => TSelect) => ColumnValidator<TSelect, TInsert | undefined>;
@@ -179,20 +193,20 @@ interface ColumnValidator<TSelect, TInsert> extends Column<TSelect, TInsert>, Va
   /** Allow SQL NULL — widens the select type to `T | null`. */
   nullable: () => ColumnValidator<null | TSelect, null | TInsert>;
   /**
-  * Stamp this column SERVER-side from the request auth on every write,
-  * overwriting any client-supplied value. The field becomes optional on
-  * insert (the server fills it). Use for owner/tenant columns that must never
-  * be client-controllable — e.g. `v.string().serverDefault(({ auth }) => auth.userId)`.
-  */
+   * Stamp this column SERVER-side from the request auth on every write,
+   * overwriting any client-supplied value. The field becomes optional on
+   * insert (the server fills it). Use for owner/tenant columns that must never
+   * be client-controllable — e.g. `v.string().serverDefault(({ auth }) => auth.userId)`.
+   */
   serverDefault: (function_: (context: ServerDefaultContext) => TSelect) => ColumnValidator<TSelect, TInsert | undefined>;
   /** Enforce a UNIQUE constraint (synthesizes a unique index). */
   unique: () => ColumnValidator<TSelect, TInsert>;
 }
 /**
-* A time-valued {@link ColumnValidator} (epoch milliseconds). Adds
-* {@link TimestampColumnValidator.defaultNow} so the field can default to the
-* insert-time clock.
-*/
+ * A time-valued {@link ColumnValidator} (epoch milliseconds). Adds
+ * {@link TimestampColumnValidator.defaultNow} so the field can default to the
+ * insert-time clock.
+ */
 interface TimestampColumnValidator extends ColumnValidator<number, number> {
   /** Default to the current epoch-ms (`Date.now()`) at insert time; field becomes optional on insert. */
   defaultNow: () => ColumnValidator<number, number | undefined>;
@@ -202,13 +216,13 @@ type InferSelect<V> = V extends Validator<infer T> ? T : never;
 /** The type a validator/column accepts on **insert** (writes). */
 type InferInsert<V> = V extends Column<unknown, infer I> ? I : V extends Validator<infer T> ? T : never;
 /** Derive the read shape of a table's column map. */
-type SelectShape<S extends Record<string, Validator>> = { [K in keyof S]: InferSelect<S[K]> };
+type SelectShape<S extends Record<string, Validator>> = { [K in keyof S]: InferSelect<S[K]>; };
 /**
-* Derive the write shape of a table's column map. Columns whose insert type
-* includes `undefined` (via `.default()` / `.$defaultFn()` / `v.optional`)
-* become optional keys.
-*/
-type InsertShape<S extends Record<string, Validator>> = { [K in keyof S as undefined extends InferInsert<S[K]> ? K : never]?: Exclude<InferInsert<S[K]>, undefined> } & { [K in keyof S as undefined extends InferInsert<S[K]> ? never : K]: InferInsert<S[K]> };
+ * Derive the write shape of a table's column map. Columns whose insert type
+ * includes `undefined` (via `.default()` / `.$defaultFn()` / `v.optional`)
+ * become optional keys.
+ */
+type InsertShape<S extends Record<string, Validator>> = { [K in keyof S as undefined extends InferInsert<S[K]> ? K : never]?: Exclude<InferInsert<S[K]>, undefined>; } & { [K in keyof S as undefined extends InferInsert<S[K]> ? never : K]: InferInsert<S[K]>; };
 declare const string: () => ColumnValidator<string, string>;
 declare const number: () => ColumnValidator<number, number>;
 /** Epoch-millisecond timestamp (`number`). Pair with `.defaultNow()` for an insert-time clock. */
@@ -221,68 +235,97 @@ declare const nullValidator: () => ColumnValidator<null, null>;
 declare const bytes: () => ColumnValidator<ArrayBuffer, ArrayBuffer>;
 declare const id: <TableName extends string>(tableName: TableName) => ColumnValidator<Id<TableName>, Id<TableName>>;
 /**
-* A reference to a stored R2 object: the column holds the object's **key** (a
-* string), the same key `@lunora/storage` puts/gets by. Functionally it parses
-* like `v.string()`, but the distinct `"storage"` kind lets codegen and the
-* studio join the data model to R2 — the file browser uses it to show which
-* record owns a file and to flag orphaned objects no row references. The
-* optional `bucket` names the typed bucket the key lives in (for app-context
-* signed URLs); omit it for the app's default bucket.
-*/
+ * A reference to a stored R2 object: the column holds the object's **key** (a
+ * string), the same key `@lunora/storage` puts/gets by. Functionally it parses
+ * like `v.string()`, but the distinct `"storage"` kind lets codegen and the
+ * studio join the data model to R2 — the file browser uses it to show which
+ * record owns a file and to flag orphaned objects no row references. The
+ * optional `bucket` names the typed bucket the key lives in (for app-context
+ * signed URLs); omit it for the app's default bucket.
+ */
 declare const storage: (bucket?: string) => ColumnValidator<string, string>;
+/**
+ * A geographic point — latitude/longitude in decimal degrees (WGS84). The value
+ * a `v.geoPoint()` column reads/writes. Stored as a JSON object alongside the
+ * row; a `.geoIndex(name, { field })` on the table maintains a geohash companion
+ * so `withGeoIndex(name, q => q.near(point, radius) | q.within(bbox))` can answer
+ * proximity/bounding-box reads.
+ */
+interface GeoPoint {
+  /** Latitude in decimal degrees, `-90 … 90`. */
+  lat: number;
+  /** Longitude in decimal degrees, `-180 … 180`. */
+  lng: number;
+}
+/**
+ * A latitude/longitude point (WGS84 decimal degrees). Parses an object with
+ * finite `lat` ∈ `[-90, 90]` and `lng` ∈ `[-180, 180]`; any other shape or an
+ * out-of-range coordinate throws a {@link ValidationError}. Pair with a table's
+ * `.geoIndex(name, { field })` to enable `near` / `within` reads.
+ */
+declare const geoPoint: () => ColumnValidator<GeoPoint, GeoPoint>;
 declare const literal: <T extends bigint | boolean | number | string | null>(literalValue: T) => ColumnValidator<T, T>;
 declare const array: <V extends Validator>(inner: V) => ColumnValidator<Infer<V>[], Infer<V>[]>;
+/**
+ * Split a value-type map into optional + required keys: any member whose value
+ * type includes `undefined` becomes an optional key. The single optionality rule
+ * shared by object-shape inference ({@link ObjectShapeType}) and args-map
+ * inference (`InferValidatorMap` in `./validator-map`), so the two can never
+ * drift. (`InsertShape` stays separate — it additionally `Exclude`s `undefined`
+ * from the optional value, a deliberate insert-type difference.)
+ */
+type OptionalizeShape<M> = { [K in keyof M as undefined extends M[K] ? K : never]?: M[K]; } & { [K in keyof M as undefined extends M[K] ? never : K]: M[K]; };
 type ObjectShape = Record<string, Validator>;
-type ObjectShapeType<S extends ObjectShape> = { [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]> } & { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]> };
+type ObjectShapeType<S extends ObjectShape> = OptionalizeShape<{ [K in keyof S]: Infer<S[K]>; }>;
 declare const objectValidator: <S extends ObjectShape>(shape: S) => ColumnValidator<ObjectShapeType<S>, ObjectShapeType<S>>;
 declare const record: <K extends Validator<string>, V extends Validator>(keyValidator: K, valueValidator: V) => ColumnValidator<Record<Infer<K>, Infer<V>>, Record<Infer<K>, Infer<V>>>;
 declare const union: <Vs extends ReadonlyArray<Validator>>(...members: Vs) => ColumnValidator<Infer<Vs[number]>, Infer<Vs[number]>>;
 declare const optional: <V extends Validator>(inner: V) => ColumnValidator<Infer<V> | undefined, Infer<V> | undefined>;
 declare const any: () => ColumnValidator<unknown, unknown>;
 /**
-* Infer the output type of a Standard Schema v1 object. When the schema omits
-* `~standard.types` (it is optional in the spec), falls back to `unknown` so
-* callers always get a usable type rather than `never`.
-*/
+ * Infer the output type of a Standard Schema v1 object. When the schema omits
+ * `~standard.types` (it is optional in the spec), falls back to `unknown` so
+ * callers always get a usable type rather than `never`.
+ */
 type InferStandardOutput<S extends StandardSchemaV1> = S["~standard"]["types"] extends {
   output: infer O;
 } ? O : unknown;
 /**
-* Wrap any Standard Schema v1 validator (`zod`, `valibot`, `arktype`, …) so it
-* can be used as an **args** validator in `query`/`mutation`/`action`. The
-* wrapped validator's output type is inferred from `~standard.types.output`
-* when declared; falls back to `unknown` when the schema omits the types field.
-*
-* **Args-only.** `v.from(...)` validators must not be used as table columns —
-* `defineTable` checks the `kind` and throws a clear error if you try.
-*
-* **Sync-only.** Standard Schema allows async `validate`; Lunora args
-* validation is synchronous and throws when a Promise is returned.
-*/
+ * Wrap any Standard Schema v1 validator (`zod`, `valibot`, `arktype`, …) so it
+ * can be used as an **args** validator in `query`/`mutation`/`action`. The
+ * wrapped validator's output type is inferred from `~standard.types.output`
+ * when declared; falls back to `unknown` when the schema omits the types field.
+ *
+ * **Args-only.** `v.from(...)` validators must not be used as table columns —
+ * `defineTable` checks the `kind` and throws a clear error if you try.
+ *
+ * **Sync-only.** Standard Schema allows async `validate`; Lunora args
+ * validation is synchronous and throws when a Promise is returned.
+ */
 declare const from: <S extends StandardSchemaV1>(schema: S) => ColumnValidator<InferStandardOutput<S>, InferStandardOutput<S>>;
 /**
-* True when `validator` is `v.from(...)` or structurally wraps one through
-* `v.optional` / `v.array` / `v.object` / `v.record` / `v.union`. `defineTable`
-* uses it to reject Standard-Schema-backed validators anywhere in a column —
-* not just at the top level — since they are args-only and have no SQL column
-* type. The nested children live on the validator's `_meta` (`inner`, `shape`,
-* `members`, `keyValidator`/`valueValidator`) and are themselves validators.
-*/
+ * True when `validator` is `v.from(...)` or structurally wraps one through
+ * `v.optional` / `v.array` / `v.object` / `v.record` / `v.union`. `defineTable`
+ * uses it to reject Standard-Schema-backed validators anywhere in a column —
+ * not just at the top level — since they are args-only and have no SQL column
+ * type. The nested children live on the validator's `_meta` (`inner`, `shape`,
+ * `members`, `keyValidator`/`valueValidator`) and are themselves validators.
+ */
 declare const isOrWrapsFromValidator: (validator: Validator) => boolean;
 /**
-* The inner validator wrapped by `v.optional(inner)`, or `undefined` for any
-* other validator. The nested child lives on the validator's internal `_meta`
-* bag; this accessor keeps that knowledge inside `@lunora/values` (the package
-* that owns validator internals) so consumers don't reach into `_meta`
-* themselves. Used by `@lunora/server`'s `defineEnv` to coerce through a leading
-* `v.optional(...)`.
-* @returns The inner validator if `v.optional(...)`, otherwise `undefined`.
-*/
+ * The inner validator wrapped by `v.optional(inner)`, or `undefined` for any
+ * other validator. The nested child lives on the validator's internal `_meta`
+ * bag; this accessor keeps that knowledge inside `@lunora/values` (the package
+ * that owns validator internals) so consumers don't reach into `_meta`
+ * themselves. Used by `@lunora/server`'s `defineEnv` to coerce through a leading
+ * `v.optional(...)`.
+ * @returns The inner validator if `v.optional(...)`, otherwise `undefined`.
+ */
 declare const optionalInner: (validator: Validator) => Validator | undefined;
 /**
-* Validator/codec namespace. Each factory returns a {@link Validator} with a
-* runtime `parse`/`safeParse` plus a phantom `__type` field for inference.
-*/
+ * Validator/codec namespace. Each factory returns a {@link Validator} with a
+ * runtime `parse`/`safeParse` plus a phantom `__type` field for inference.
+ */
 declare const v: {
   any: typeof any;
   array: typeof array;
@@ -291,6 +334,7 @@ declare const v: {
   bytes: typeof bytes;
   date: typeof date;
   from: typeof from;
+  geoPoint: typeof geoPoint;
   id: typeof id;
   literal: typeof literal;
   null: typeof nullValidator;
@@ -304,35 +348,35 @@ declare const v: {
   union: typeof union;
 };
 /**
-* A JSON Schema node (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally a
-* loose bag — Lunora only emits a known subset, but consumers (OpenAPI/OpenRPC
-* builders, Swagger UI, form generators) treat it as an opaque schema object.
-*/
+ * A JSON Schema node (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally a
+ * loose bag — Lunora only emits a known subset, but consumers (OpenAPI/OpenRPC
+ * builders, Swagger UI, form generators) treat it as an opaque schema object.
+ */
 interface JsonSchema {
   [keyword: string]: unknown;
 }
 /**
-* Structural reader over a validator-like node. The shared mapping algorithm
-* ({@link jsonSchemaFromNode}) is parameterized by this interface so the same
-* switch/recursion serves both inputs Lunora maps to JSON Schema: the runtime
-* `@lunora/values` validator (children + metadata live on `_meta`), and the
-* build-time validator IR consumed by codegen (children are plain fields, with
-* no runtime metadata — so `constraints`/`isNullable` may be inert there).
-*
-* A reader normalizes a `TNode` to the small set of children/leaves the mapper
-* recurses over. Composite accessors (`inner`/`shape`/`members`/`valueChild`)
-* return the same `TNode` type so the mapper can recurse uniformly; leaf concerns
-* that differ between the two sources — how a literal's `const` is computed,
-* whether a `.check()`/`.meta()` constraint fragment exists, whether `.nullable()`
-* was applied — are delegated wholesale to the reader.
-*/
+ * Structural reader over a validator-like node. The shared mapping algorithm
+ * ({@link jsonSchemaFromNode}) is parameterized by this interface so the same
+ * switch/recursion serves both inputs Lunora maps to JSON Schema: the runtime
+ * `@lunora/values` validator (children + metadata live on `_meta`), and the
+ * build-time validator IR consumed by codegen (children are plain fields, with
+ * no runtime metadata — so `constraints`/`isNullable` may be inert there).
+ *
+ * A reader normalizes a `TNode` to the small set of children/leaves the mapper
+ * recurses over. Composite accessors (`inner`/`shape`/`members`/`valueChild`)
+ * return the same `TNode` type so the mapper can recurse uniformly; leaf concerns
+ * that differ between the two sources — how a literal's `const` is computed,
+ * whether a `.check()`/`.meta()` constraint fragment exists, whether `.nullable()`
+ * was applied — are delegated wholesale to the reader.
+ */
 interface SchemaNodeReader<TNode> {
   /**
-  * The `.check()`/`.meta()` JSON Schema fragment to shallow-merge onto the
-  * node, or `undefined` when none (the IR side never carries one). Constraint
-  * keys win over the base on conflict so a refinement can tighten — never
-  * silently weaken — the schema.
-  */
+   * The `.check()`/`.meta()` JSON Schema fragment to shallow-merge onto the
+   * node, or `undefined` when none (the IR side never carries one). Constraint
+   * keys win over the base on conflict so a refinement can tighten — never
+   * silently weaken — the schema.
+   */
   constraints: (node: TNode) => JsonSchema | undefined;
   /** Inner child of an `array`/`optional` node. May be absent on the IR side. */
   inner: (node: TNode) => TNode | undefined;
@@ -341,10 +385,10 @@ interface SchemaNodeReader<TNode> {
   /** Discriminating validator kind. */
   kind: (node: TNode) => ValidatorKind;
   /**
-  * The JSON Schema `const` fragment for a `literal` node. Computed differently
-  * per source — runtime reads the live `_meta.value`; the IR parses verbatim
-  * source text — so the reader owns it entirely.
-  */
+   * The JSON Schema `const` fragment for a `literal` node. Computed differently
+   * per source — runtime reads the live `_meta.value`; the IR parses verbatim
+   * source text — so the reader owns it entirely.
+   */
   literalSchema: (node: TNode) => JsonSchema;
   /** Member nodes of a `union`. */
   members: (node: TNode) => ReadonlyArray<TNode>;
@@ -356,62 +400,109 @@ interface SchemaNodeReader<TNode> {
   valueChild: (node: TNode) => TNode | undefined;
 }
 /**
-* The single validator→JSON-Schema mapping algorithm, shared by the runtime
-* `toJsonSchema` (over `@lunora/values` validators) and codegen's IR-backed
-* mapper. It walks a node recursively via the supplied {@link SchemaNodeReader},
-* so nested objects/arrays/unions/records are fully expanded (never collapsed to
-* one level).
-*
-* `date`/`timestamp` are epoch-millisecond numbers in Lunora (not ISO strings),
-* so they schema as integers; `bigint` schemas as an int64 (JSON has no bigint
-* type, so `format: int64` is the conventional OpenAPI carrier); `bytes` is an
-* `ArrayBuffer`, surfaced as base64 per JSON Schema 2020-12 content encoding.
-*
-* A `.check()`/`.meta()` JSON Schema fragment (when the reader exposes one) is
-* shallow-merged onto the node — constraint keys win on conflict. A `.nullable()`
-* node widens to also accept `null`; constraints describe the underlying value,
-* so they ride inside the non-null branch rather than on the wrapping `anyOf`.
-*/
+ * The single validator→JSON-Schema mapping algorithm, shared by the runtime
+ * `toJsonSchema` (over `@lunora/values` validators) and codegen's IR-backed
+ * mapper. It walks a node recursively via the supplied {@link SchemaNodeReader},
+ * so nested objects/arrays/unions/records are fully expanded (never collapsed to
+ * one level).
+ *
+ * `date`/`timestamp` are epoch-millisecond numbers in Lunora (not ISO strings),
+ * so they schema as integers; `bigint` schemas as an int64 (JSON has no bigint
+ * type, so `format: int64` is the conventional OpenAPI carrier); `bytes` is an
+ * `ArrayBuffer`, surfaced as base64 per JSON Schema 2020-12 content encoding.
+ *
+ * A `.check()`/`.meta()` JSON Schema fragment (when the reader exposes one) is
+ * shallow-merged onto the node — constraint keys win on conflict. A `.nullable()`
+ * node widens to also accept `null`; constraints describe the underlying value,
+ * so they ride inside the non-null branch rather than on the wrapping `anyOf`.
+ */
 declare const jsonSchemaFromNode: <TNode>(node: TNode, reader: SchemaNodeReader<TNode>) => JsonSchema;
 /**
-* Build `{ type: "object", properties, required, additionalProperties: false }`
-* from a node shape. A `v.optional(...)` property is the only thing that drops
-* out of `required`; every other property is required.
-*/
+ * Build `{ type: "object", properties, required, additionalProperties: false }`
+ * from a node shape. A `v.optional(...)` property is the only thing that drops
+ * out of `required`; every other property is required.
+ */
 declare const objectSchemaFromNodes: <TNode>(shape: Record<string, TNode>, reader: SchemaNodeReader<TNode>) => JsonSchema;
 /**
-* Convert a single `@lunora/values` validator to a JSON Schema node (Draft
-* 2020-12 / OpenAPI 3.1). A thin wrapper over the shared {@link jsonSchemaFromNode}
-* core with the runtime {@link validatorReader}; see that core for the full
-* kind→schema mapping (date/timestamp → epoch-ms integer, bigint → int64, bytes →
-* base64, id → annotated string, literal → `const`, optionality via the parent
-* `required` list, `.nullable()` widening, `.check()`/`.meta()` constraint merge).
-*/
+ * Convert a single `@lunora/values` validator to a JSON Schema node (Draft
+ * 2020-12 / OpenAPI 3.1). A thin wrapper over the shared {@link jsonSchemaFromNode}
+ * core with the runtime {@link validatorReader}; see that core for the full
+ * kind→schema mapping (date/timestamp → epoch-ms integer, bigint → int64, bytes →
+ * base64, id → annotated string, literal → `const`, optionality via the parent
+ * `required` list, `.nullable()` widening, `.check()`/`.meta()` constraint merge).
+ */
 declare const toJsonSchema: (validator: Validator) => JsonSchema;
 /**
-* Convert a function's argument validators (a name-to-validator map) into a
-* single JSON Schema object. Non-`optional` arguments are `required`; the result
-* is the request `params`/`args` schema an OpenAPI operation or OpenRPC method
-* advertises. An empty arg map yields an empty (but valid) object schema.
-*/
+ * Convert a function's argument validators (a name-to-validator map) into a
+ * single JSON Schema object. Non-`optional` arguments are `required`; the result
+ * is the request `params`/`args` schema an OpenAPI operation or OpenRPC method
+ * advertises. An empty arg map yields an empty (but valid) object schema.
+ */
 declare const argsToJsonSchema: (args: Record<string, Validator>) => JsonSchema;
 /** Map of validators describing a record of named fields (a function's args, a step's args, an HTTP query/body/params). */
 type ValidatorMap = Record<string, Validator>;
-/** Infer the object type from a {@link ValidatorMap} — optional validators (`v.optional`) become optional keys. */
-type InferValidatorMap<A extends ValidatorMap> = { [K in keyof A as undefined extends Infer<A[K]> ? K : never]?: Infer<A[K]> } & { [K in keyof A as undefined extends Infer<A[K]> ? never : K]: Infer<A[K]> };
-/**
-* Validate each declared field of `source` through its validator, re-wrapping
-* any {@link ValidationError} with a `label.&lt;key>:` prefix and the rebuilt path
-* `[key, ...error.path]` so the failure points at the offending field. Optional
-* fields absent from the source are skipped (so `v.optional` passes and a
-* required validator fails on `undefined`).
-*
-* The single arg-/field-parsing implementation shared across the framework — the
-* procedure builder (label `args`), the HTTP route builder (`searchParams` /
-* `body` / `params`), and `@lunora/workflow`'s reusable steps (`step args`) — so
-* the error-prefixing and optional-skip semantics can't drift apart. The `label`
-* is the only thing each caller varies.
-*/
+/**
+ * Infer the object type from a {@link ValidatorMap} — optional validators
+ * (`v.optional`) become optional keys. Shares the single optionality rule with
+ * `ObjectShapeType` via {@link OptionalizeShape}, so args-map and object-shape
+ * inference can never drift.
+ */
+type InferValidatorMap<A extends ValidatorMap> = OptionalizeShape<{ [K in keyof A]: Infer<A[K]>; }>;
+/**
+ * A precompiled fast-path parser for one {@link ValidatorMap}. Returns the fully
+ * built, validated record on a confident success, or the {@link DEFER_VALIDATION}
+ * sentinel to hand the input back to the interpreted parser.
+ *
+ * The contract is soundness, not completeness: a compiled parser may return
+ * {@link DEFER_VALIDATION} for any input it is not certain about (the interpreted
+ * path then runs and either succeeds or throws the canonical error), but it must
+ * NEVER return a built record for input the interpreted parser would reject, and
+ * the record it returns must be byte-for-byte what the interpreted parser would
+ * have produced. This lets `@lunora/codegen` emit zero-allocation structural
+ * checks (the common case) while every error message and every tricky validator
+ * still flows through the single interpreted implementation below — so error
+ * contracts can never drift.
+ *
+ * The `source` parameter is intentionally `any`: the codegen-emitted body is
+ * plain JavaScript (no type annotations — it must also be loadable via
+ * `new Function` in the compiler's differential tests) that index-walks the input
+ * to arbitrary depth, which strict TypeScript forbids on `unknown`/`object`. An
+ * `any` input lets the emitted structural checks type-check cleanly while the
+ * RESULT stays strongly typed; soundness is enforced by the differential test
+ * harness, not the input type.
+ */
+type CompiledValidatorMap = (source: any) => Record<string, unknown> | typeof DEFER_VALIDATION;
+/**
+ * Sentinel a {@link CompiledValidatorMap} returns to defer to the interpreted
+ * parser. A unique symbol (never a valid parse result — {@link parseValidatorMap}
+ * always yields a record) so the seam can distinguish "compiled handled it" from
+ * "compiled bailed" with a single identity check and no per-call allocation.
+ */
+declare const DEFER_VALIDATION: unique symbol;
+/**
+ * Install a compiled fast-path parser for `validators`. Idempotent-ish: a second
+ * install overwrites the first (codegen emits each map once, so this only matters
+ * if a host installs by hand). See {@link CompiledValidatorMap} for the contract
+ * the parser must honour.
+ */
+declare const installCompiledValidatorMap: (validators: object, compiled: CompiledValidatorMap) => void;
+/**
+ * Validate each declared field of `source` through its validator, re-wrapping
+ * any {@link ValidationError} with a `label.&lt;key>:` prefix and the rebuilt path
+ * `[key, ...error.path]` so the failure points at the offending field. Optional
+ * fields absent from the source are skipped (so `v.optional` passes and a
+ * required validator fails on `undefined`).
+ *
+ * The single arg-/field-parsing implementation shared across the framework — the
+ * procedure builder (label `args`), the HTTP route builder (`searchParams` /
+ * `body` / `params`), and `@lunora/workflow`'s reusable steps (`step args`) — so
+ * the error-prefixing and optional-skip semantics can't drift apart. The `label`
+ * is the only thing each caller varies.
+ *
+ * When a codegen-emitted {@link CompiledValidatorMap} is installed for this exact
+ * `validators` object, the fast path runs first; it either returns the finished
+ * record (a confident success — the common case) or {@link DEFER_VALIDATION}, in
+ * which case the interpreted loop below runs and owns the result (and any error).
+ */
 declare const parseValidatorMap: (validators: ValidatorMap, source: Record<string, unknown>, label: string) => Record<string, unknown>;
-declare const VERSION = "0.0.0";
-export { type CheckOptions, type Column, type ColumnMeta, type ColumnValidator, type Id, type Infer, type InferInsert, type InferSelect, type InferStandardOutput, type InferValidatorMap, type InsertShape, type JsonSchema, type JsonSchemaFragment, type MetaOptions, type SchemaNodeReader, type SelectShape, type ServerDefaultContext, type TimestampColumnValidator, VERSION, ValidationError, type ValidationPath, type Validator, type ValidatorKind, type ValidatorMap, argsToJsonSchema, describeValue, formatPath, isOrWrapsFromValidator, jsonSchemaFromNode, objectSchemaFromNodes, optionalInner, parseValidatorMap, toJsonSchema, v };
+export { type CheckOptions, type Column, type ColumnMeta, type ColumnValidator, type CompiledValidatorMap, DEFER_VALIDATION, type GeoPoint, type Id, type Infer, type InferInsert, type InferSelect, type InferStandardOutput, type InferValidatorMap, type InsertShape, type JsonSchema, type JsonSchemaFragment, type MetaOptions, type SchemaNodeReader, type SelectShape, type ServerDefaultContext, type TimestampColumnValidator, ValidationError, type ValidationPath, type Validator, type ValidatorKind, type ValidatorMap, argsToJsonSchema, describeValue, formatPath, installCompiledValidatorMap, isOrWrapsFromValidator, jsonSchemaFromNode, objectSchemaFromNodes, optionalInner, parseValidatorMap, toJsonSchema, v };