@lunora/values 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/index.d.mts

@@ -2,15 +2,15 @@ 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"]`.
-*
-* 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.
-*/
+ * 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;
@@ -22,43 +22,50 @@ declare class ValidationError extends LunoraError {
   });
 }
 /**
-* 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.
-*/
+ * 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">`. */
+/**
+ * A cyrb53 string hash — fast, well-distributed, 53-bit, with good avalanche
+ * behaviour. Public-domain (bryc). Two independent accumulators seeded from
+ * `seed` are mixed and combined; we down-fold the 53-bit result to an unsigned
+ * 32-bit integer for faker's seed.
+ */
+declare const cyrb53: (text: string, seed?: number) => number;
+/** Branded id type, e.g. `Id<"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;
@@ -66,10 +73,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;
@@ -77,39 +84,47 @@ 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)`.
+   *
+   * For the common length/format/range cases, prefer the named shortcuts
+   * (`v.string().min(1)`, `.max(n)`, `.length(n)`, `.pattern(re)`, `.email()`,
+   * `.url()`; `v.number().min(n)`, `.max(n)`, `.int()`, `.positive()`;
+   * `v.array(...).min(n)`, `.max(n)`) — each is sugar over this same
+   * `.check(predicate, { schema })` path, so the predicate and the JSON Schema
+   * keyword are set together and can never drift apart. `.check()` remains the
+   * escape hatch for anything the shortcuts don't cover, e.g.
+   * `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) => {
+  parse: (value: unknown, options?: ParseOptions) => T;
+  safeParse: (value: unknown, options?: ParseOptions) => {
     error: ValidationError;
     ok: false;
   } | {
@@ -120,10 +135,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;
@@ -134,24 +149,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. */
@@ -161,9 +176,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: {
@@ -172,17 +187,24 @@ 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>;
   /** Recompute the field on every patch/replace when not explicitly provided. */
   $onUpdateFn: (function_: () => TSelect) => ColumnValidator<TSelect, TInsert>;
-  /** Override the inferred select/insert type without changing runtime parsing (e.g. `v.string().$type&lt;Id&lt;"users">>()`). */
+  /**
+   * Override the type `Infer<>` gives this validator without changing runtime
+   * parsing (e.g. `v.string().$type<Brand>()`). An unchecked assertion: the
+   * parser still accepts any value of the base kind, so codegen's `Doc_*` /
+   * `Insert_*` / procedure-arg types keep the base type (`string`) — the one
+   * the stored value is actually guaranteed to have. For a document id use
+   * `v.id("users")`, which is checked.
+   */
   $type: <TOverride>() => ColumnValidator<TOverride, TOverride>;
   /** Refinement predicate run after parsing — see {@link Validator.check}. Chainable; preserves column modifiers. */
   check: (predicate: (value: TSelect) => boolean, options?: CheckOptions | string) => ColumnValidator<TSelect, TInsert>;
@@ -193,38 +215,118 @@ 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>;
 }
+/**
+ * A {@link ColumnValidator} for `v.string()` with ergonomic refinement
+ * shortcuts. Each method is sugar over `.check(predicate, { schema })` — it
+ * sets the runtime predicate AND the matching JSON Schema keyword in one call
+ * so the two can never drift (see the module-level `.check()` docstring for
+ * the underlying two-part mechanism). Chainable among each other; `.check()`/
+ * `.meta()` compose after them but the return narrows to the base
+ * {@link ColumnValidator} (no further refinement shortcuts after that point).
+ */
+interface StringColumnValidator extends ColumnValidator<string, string> {
+  /** Require a valid email address (`format: "email"`). Uses a pragmatic (non-RFC-5322-exhaustive) pattern. */
+  email: () => StringColumnValidator;
+  /** Require exactly `length` characters (`minLength`/`maxLength` both set to `length`). */
+  length: (length: number) => StringColumnValidator;
+  /** Require at most `max` characters (`maxLength`). */
+  max: (max: number) => StringColumnValidator;
+  /** Require at least `min` characters (`minLength`). */
+  min: (min: number) => StringColumnValidator;
+  /**
+   * Require the value to match `pattern` (JSON Schema `pattern` set from
+   * `pattern.source`; emitted `pattern` does not encode `pattern.flags` — a
+   * case-insensitive `/i` regex, for instance, emits a flag-less JSON Schema
+   * pattern). A `g`/`y`-flagged `pattern` is tested statelessly (its
+   * `lastIndex` is never consulted or advanced), so a single validator
+   * instance gives the same answer for the same input on every call.
+   */
+  pattern: (pattern: RegExp) => StringColumnValidator;
+  /**
+   * Require a valid `http:`/`https:` URL (`format: "uri"`). Parseable by the
+   * WHATWG `URL` constructor is necessary but not sufficient — schemes such as
+   * `javascript:`, `data:`, `file:`, and `vbscript:` all parse successfully but
+   * are rejected here, since accepting them lets a validated "link" field carry
+   * an XSS payload straight into an anchor's `href` or `window.location` at
+   * render time.
+   */
+  url: () => StringColumnValidator;
+}
+/**
+ * A {@link ColumnValidator} for `v.number()` with ergonomic refinement
+ * shortcuts — see {@link StringColumnValidator} for the delegation pattern.
+ */
+interface NumberColumnValidator extends ColumnValidator<number, number> {
+  /** Require an integer value (`Number.isInteger`); JSON Schema `type` narrows to `"integer"`. */
+  int: () => NumberColumnValidator;
+  /** Require at most `max` (`maximum`). */
+  max: (max: number) => NumberColumnValidator;
+  /** Require at least `min` (`minimum`). */
+  min: (min: number) => NumberColumnValidator;
+  /** Require a value strictly greater than zero (`exclusiveMinimum: 0`). */
+  positive: () => NumberColumnValidator;
+}
+/**
+ * A {@link ColumnValidator} for `v.object(...)`, carrying the `.strip()` opt-out.
+ */
+interface ObjectColumnValidator<T> extends ColumnValidator<T, T> {
+  /**
+   * Drop keys this shape does not declare, even under `.output()`.
+   *
+   * Only meaningful there — input parsing strips already. Say it when the
+   * narrowing is deliberate (trimming an internal field off a row before it
+   * reaches a client); without it, an undeclared key on the way OUT is an
+   * error, because the alternative is deleting server data silently.
+   */
+  strip: () => ObjectColumnValidator<T>;
+}
+/**
+ * A {@link ColumnValidator} for `v.array(...)` with ergonomic length-refinement
+ * shortcuts — see {@link StringColumnValidator} for the delegation pattern.
+ */
+interface ArrayColumnValidator<TItem> extends ColumnValidator<TItem[], TItem[]> {
+  /** Require at most `max` items (`maxItems`). */
+  max: (max: number) => ArrayColumnValidator<TItem>;
+  /** Require at least `min` items (`minItems`). */
+  min: (min: number) => ArrayColumnValidator<TItem>;
+}
 /** The type a validator/column presents on **select** (reads). */
 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]> };
-/**
-* 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>;
+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]>; };
+/** Options for {@link Validator.parse} / {@link Validator.safeParse}. */
+interface ParseOptions {
+  /** See {@link ParseContext.rejectUnknownKeys}. */
+  rejectUnknownKeys?: boolean;
+}
+declare const string: () => StringColumnValidator;
+declare const number: () => NumberColumnValidator;
 /** Epoch-millisecond timestamp (`number`). Pair with `.defaultNow()` for an insert-time clock. */
 declare const timestamp: () => TimestampColumnValidator;
 /** Calendar date stored as an epoch-millisecond `number`. Pair with `.defaultNow()` for an insert-time clock. */
@@ -235,77 +337,174 @@ 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] };
+declare const array: <V extends Validator>(inner: V) => ArrayColumnValidator<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.)
+ *
+ * `undefined extends M[K]` is the type-level spelling of "the parser accepts
+ * this field absent" — the same question `acceptsAbsent` in
+ * `./json-schema-core` answers structurally. It is broader than
+ * `v.optional(...)` on purpose: `v.any()` returns its input unchanged, so it
+ * parses an absent field happily, and a `v.union(...)` with an `any`/optional
+ * member does too. Anything narrower would mark a key required that the runtime
+ * does not require — which is how a generated `_generated/api.ts` came to reject
+ * args the server accepts (issue #688).
+ */
+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> = OptionalizeShape<{ [K in keyof S]: Infer<S[K]> }>;
-declare const objectValidator: <S extends ObjectShape>(shape: S) => ColumnValidator<ObjectShapeType<S>, ObjectShapeType<S>>;
+type ObjectShapeType<S extends ObjectShape> = OptionalizeShape<{ [K in keyof S]: Infer<S[K]>; }>;
+declare const objectValidator: <S extends ObjectShape>(shape: S, stripUnknown?: boolean) => ObjectColumnValidator<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>;
+/** Every member of a shape made optional — the result of {@link partial}. */
+type PartialShape<S extends ObjectShape> = { [K in keyof S]: ColumnValidator<Infer<S[K]> | undefined, Infer<S[K]> | undefined>; };
+/**
+ * Wrap every member of a shape in {@link optional}.
+ *
+ * A patch-style procedure takes "any subset of these columns" — the same shape
+ * the table declares, with nothing required. Spelling that out by hand means a
+ * second copy of the shape that has to be kept in step with the first, and the
+ * failure when it drifts is quiet: a column added to the table is simply not
+ * accepted by the patch, and nothing typechecks it against the table.
+ *
+ * Takes and returns a *shape record* rather than a `v.object(...)`, so the one
+ * function serves both positions — a procedure's args map (`.input(...)`) and a
+ * nested object (`v.object(v.partial(shape))`).
+ *
+ * A member that is already `v.optional(...)` is passed through rather than
+ * double-wrapped, so this is idempotent.
+ *
+ * **Pass the fields a caller may patch, not a whole table's shape.** Handing this
+ * `schema.tables.x.shape` makes every present and *future* column client-writable:
+ * add `ownerId`, `role`, or `isVerified` to the table later and it silently joins
+ * the patch, with no diff on the procedure to review. Row-level policies do not
+ * close that — they decide which ROW you may write, not which fields — so the
+ * allow-list has to be here.
+ * @example
+ * ```ts
+ * const editable = { body: v.string(), title: v.string() };
+ *
+ * mutation.input({ id: v.id("threads"), ...v.partial(editable) }).mutation(…)
+ * ```
+ */
+declare const partial: <S extends ObjectShape>(shape: S) => PartialShape<S>;
 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`.
-*/
-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.
-*/
-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.
-*/
+ * The type a Standard Schema v1 object validates TO — what a read gets back.
+ *
+ * Defer to the spec's own helper rather than matching `~standard.types`: the spec
+ * declares that property optional (it is a phantom that never exists at runtime),
+ * so every real library types it as a union with `undefined`, and a hand-written
+ * `extends { output: infer O }` misses all of them. A schema that declares no
+ * `types` still resolves through the constraint to `unknown`.
+ */
+type InferStandardOutput<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+/**
+ * The type a Standard Schema v1 object validates FROM — what a write supplies.
+ *
+ * Distinct from {@link InferStandardOutput} only for a transforming schema
+ * (`z.string().transform(…)`, `z.coerce.number()`), where the value handed in is
+ * not the value stored. Identical for everything else.
+ */
+type InferStandardInput<S extends StandardSchemaV1> = StandardSchemaV1.InferInput<S>;
+/**
+ * Wrap any Standard Schema v1 validator (`zod`, `valibot`, `arktype`, …) so it
+ * can be used as an args validator in `query`/`mutation`/`action`, or as a table
+ * column. 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.
+ *
+ * **Columns are stored by the value's runtime type.** A shard row is a JSON
+ * document, so a `v.from()` column needs no SQL type of its own. For a
+ * `.global()` table it maps to a TEXT column holding whatever the encoder
+ * produces: a scalar is written verbatim (a `v.from(z.string())` column holds a
+ * bare `hello`, not `"hello"`), and an object or array is JSON-encoded. That is
+ * the same rule `v.union` and `v.any` follow, and it is why the column cannot be
+ * a Postgres/MySQL `JSON` column — a bare `hello` is not valid JSON.
+ *
+ * The consequence worth knowing: a stored *string* that itself looks like JSON
+ * (`'{"a":1}'`) is ambiguous on read and decodes to the parsed object. Declare
+ * the column with a concrete `v.*` type when the plain column type matters — for
+ * a comparison index, or to avoid that ambiguity.
+ *
+ * **Not seedable.** `@lunora/seed` cannot introspect an external schema to
+ * invent a valid value, so it refuses a `v.from()` column with an actionable
+ * error rather than generating one that fails validation on insert.
+ *
+ * **Sync-only.** Standard Schema allows async `validate`; Lunora validation is
+ * synchronous and throws when a Promise is returned.
+ *
+ * **Reads and writes can differ.** A write supplies the schema's INPUT and a read
+ * gets its OUTPUT back, because what is stored is `validate()`'s result. The two
+ * coincide for every non-transforming schema; they part for `z.coerce.number()`
+ * and friends, where typing the insert side as the output would demand the
+ * post-transform value from a caller whose value the validator is there to
+ * transform.
+ */
+declare const from: <S extends StandardSchemaV1>(schema: S) => ColumnValidator<InferStandardOutput<S>, InferStandardInput<S>>;
+/**
+ * True when `validator` is `v.from(...)` or structurally wraps one through
+ * `v.optional` / `v.array` / `v.object` / `v.record` / `v.union`. The nested
+ * children live on the validator's `_meta` (`inner`, `shape`, `members`,
+ * `keyValidator`/`valueValidator`) and are themselves validators.
+ *
+ * For tooling that must know whether a value is validated by an external
+ * Standard Schema rather than a concrete `v.*` type — a seeder that cannot
+ * invent a conforming value, a JSON Schema exporter that has nothing to
+ * describe. `defineTable` no longer calls it: a `v.from()` column is allowed
+ * and stores JSON, see {@link from}.
+ */
 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;
@@ -314,12 +513,14 @@ declare const v: {
   bytes: typeof bytes;
   date: typeof date;
   from: typeof from;
+  geoPoint: typeof geoPoint;
   id: typeof id;
   literal: typeof literal;
   null: typeof nullValidator;
   number: typeof number;
   object: typeof objectValidator;
   optional: typeof optional;
+  partial: typeof partial;
   record: typeof record;
   storage: typeof storage;
   string: typeof string;
@@ -327,47 +528,53 @@ 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`/`keyChild`/`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;
   /** Whether `.nullable()` was applied (runtime: `_meta.column.notNull === false`). */
   isNullable: (node: TNode) => boolean;
+  /**
+   * Key-child of a `record` node, mapped to `propertyNames`. May be absent on
+   * the IR side (and on a `v.record(v.string(), …)` whose key validator adds
+   * no constraint beyond `type: "string"` it is merely redundant, not wrong).
+   */
+  keyChild: (node: TNode) => TNode | undefined;
   /** 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>;
@@ -379,109 +586,137 @@ 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).
+ *
+ * Each node names the JSON CARRIER, not the decoded JS type — the transport
+ * decodes before the parser sees a value, so describing the JS type would
+ * advertise shapes no JSON body can hold. `date`/`timestamp` are
+ * epoch-millisecond numbers in Lunora (not ISO strings), so they schema as
+ * integers; `bigint` rides as an int64 decimal string, the same carrier the
+ * wire codec and `v.literal(5n)` use; `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.
-*/
+ * True when the parser accepts this node's field ABSENT — the only honest test
+ * for whether a key is optional.
+ *
+ * `kind === "optional"` used to be the whole test, which called two kinds
+ * required that parse `{}` happily: `v.any()` (its parser returns `undefined`
+ * unchanged) and a `v.union(...)` with an optional or `any` member (the union
+ * tries members, one of which accepts `undefined`). A contract that requires a
+ * field the server does not cannot be satisfied by a generated client.
+ *
+ * Shared beyond JSON Schema's `required`: `@lunora/codegen`'s api emitter runs it
+ * over the build-time validator IR to decide `key?: T` vs `key: T`, so the
+ * generated `_generated/api.ts` argument types, the emitted OpenAPI/OpenRPC
+ * specs, and `Infer`'s `undefined extends …` optionality rule all answer this
+ * one question the same way.
+ * @returns `true` when an absent value parses.
+ */
+declare const acceptsAbsent: <TNode>(node: TNode, reader: SchemaNodeReader<TNode>) => boolean;
+/**
+ * Build `{ type: "object", properties, required }` from a node shape.
+ *
+ * Deliberately NOT `additionalProperties: false`: `v.object` STRIPS an
+ * undeclared key rather than refusing it (only `.output()`'s
+ * `rejectUnknownKeys` mode refuses one, and it is not what this schema
+ * describes), so closing the object had a spec-validating client reject bodies
+ * the server accepts. Absent means allowed, which is what the parser does.
+ *
+ * `required` lists every key whose field cannot be absent — see
+ * {@link acceptsAbsent}.
+ */
 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. 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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).
-*/
+ * Validate each declared field of `source` through its validator, re-wrapping
+ * any {@link ValidationError} with a `label.<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>;
-export { type CheckOptions, type Column, type ColumnMeta, type ColumnValidator, type CompiledValidatorMap, DEFER_VALIDATION, 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 };
+export { type ArrayColumnValidator, type CheckOptions, type Column, type ColumnMeta, type ColumnValidator, type CompiledValidatorMap, DEFER_VALIDATION, type GeoPoint, type Id, type Infer, type InferInsert, type InferSelect, type InferStandardInput, type InferStandardOutput, type InferValidatorMap, type InsertShape, type JsonSchema, type JsonSchemaFragment, type MetaOptions, type NumberColumnValidator, type ObjectColumnValidator, type ParseOptions, type SchemaNodeReader, type SelectShape, type ServerDefaultContext, type StringColumnValidator, type TimestampColumnValidator, ValidationError, type ValidationPath, type Validator, type ValidatorKind, type ValidatorMap, acceptsAbsent, argsToJsonSchema, cyrb53, describeValue, formatPath, installCompiledValidatorMap, isOrWrapsFromValidator, jsonSchemaFromNode, objectSchemaFromNodes, optionalInner, parseValidatorMap, toJsonSchema, v };