@abloatai/ablo 0.26.0 → 0.28.0

package/dist/schema/ddlLock.js

@@ -1,30 +1,25 @@
 /**
- * Safe-DDL LOCKING knobs — the ONE reader for how a schema change acquires
- * (and retries for) table locks, shared by BOTH executors of the provision
- * plan:
+ * Lock settings for schema-change (DDL) statements. When a schema push alters a
+ * table, these values control how quickly the change gives up on a contended
+ * lock and how many times it retries. The command-line `ablo migrate` and the
+ * host that applies a schema push both resolve their lock behavior through this
+ * module, so tuning the environment variables below changes both paths the same
+ * way.
  *
- *   - `ablo migrate` (cli/migrate.ts) — the customer runs the DDL themselves
- *   - the hosted executor (`apps/sync-server/src/schema/ddlExec.ts`)
+ * The defaults follow the standard safe-migration recipe: a short `lock_timeout`
+ * so a blocked `ALTER` aborts quickly instead of parking an `ACCESS EXCLUSIVE`
+ * lock request at the head of the queue — which would freeze every other query
+ * on that table behind it — paired with a bounded retry-and-backoff on the
+ * resulting timeout.
  *
- * The two used to carry copy-pasted constants and had already drifted: the
- * server honored `ABLO_SCHEMA_LOCK_ATTEMPTS` while the CLI hardcoded 5, so an
- * operator tuning the knob got it applied by hosted push but silently ignored
- * by `ablo migrate`. Both now resolve through here.
- *
- * The settings themselves are the battle-tested ones every mature migration
- * tool uses (GitLab `with_lock_retries`, Strong Migrations, Doctolib
- * `safe-pg-migrations`): a LOW `lock_timeout` so a blocked ALTER aborts fast
- * instead of parking an ACCESS EXCLUSIVE request at the head of the lock
- * queue (which would freeze every query on that table behind it), plus a
- * bounded retry-with-backoff on the `55P03` abort.
- *
- * Env knobs (read at CALL time, not import time, so tests and long-lived
- * processes see updates): `ABLO_SCHEMA_LOCK_TIMEOUT` / `ABLO_SCHEMA_LOCK_ATTEMPTS`
- * — the older `ABLO_DDL_*` names are still honored so existing setups don't
- * break.
+ * The environment variables are read each time a resolver is called, not once
+ * at import, so a long-running process or a test that changes them sees the
+ * update: `ABLO_SCHEMA_LOCK_TIMEOUT` and `ABLO_SCHEMA_LOCK_ATTEMPTS`. The older
+ * `ABLO_DDL_*` names are also accepted.
  */
-/** Postgres SQLSTATE `lock_not_available` — a `lock_timeout` abort. The ONE
- *  retryable DDL failure; everything else is a real error. */
+/** The Postgres SQLSTATE `55P03` (`lock_not_available`), raised when a statement
+ *  gives up waiting for a lock after `lock_timeout`. This is the one DDL failure
+ *  worth retrying; any other error is a genuine problem. */
 export const PG_LOCK_NOT_AVAILABLE = '55P03';
 const DEFAULT_LOCK_TIMEOUT = '5s';
 const DEFAULT_MAX_LOCK_ATTEMPTS = 5;

package/dist/schema/diff.d.ts

@@ -1,61 +1,74 @@
 /**
- * Schema diff + migration planning — the pure core of the managed-migration loop.
+ * Computes the migration plan that turns one schema into another. Given two
+ * serialized schemas — the one currently active and the one being pushed — it
+ * produces an ordered list of {@link MigrationStep}s describing how to evolve the
+ * database, and a {@link MigrationClassification} that separates the risky parts
+ * into warnings (they run, but may lose or risk data on a non-empty table) and
+ * unexecutable steps (they fail on a non-empty table unless a backfill or default
+ * is supplied). This module only plans: it has no database dependency and emits no
+ * SQL, so it can be unit-tested exhaustively and reused by the command-line tools.
+ * Turning a step into SQL and running it happens in the host implementation, which
+ * owns the column-type mapping and row-security rules.
  *
- * Given two serialized schemas (the active one and the one being pushed), produce
- * an ordered list of {@link MigrationStep}s describing how to evolve the database,
- * and a {@link MigrationClassification} splitting the risky parts into *warnings*
- * (execute but may lose/risk data) and *unexecutable* steps (fail on a non-empty
- * table without a backfill/default). SQL emission and execution live elsewhere
- * (server-side, where the type map + RLS live); this module is intentionally pure
- * and DB-free so it is exhaustively unit-testable and reusable by the CLI.
+ * A few design choices worth knowing about:
+ *  - Renames are supplied as data through {@link RenameHints}, not guessed. Without
+ *    a hint, a removed field plus an added field reads as a drop followed by an add,
+ *    which is the safe (lossy) default; a hint tells the planner they are the same
+ *    field under a new name.
+ *  - Destructive changes fall into two tiers — warnings versus unexecutable — and a
+ *    type change carries its own sub-tier ({@link CastSafety}: safe, risky, or not
+ *    castable) that decides between an in-place `ALTER COLUMN … TYPE` and a lossy
+ *    drop-and-recreate.
+ *  - A single {@link FieldChanges} value records which facets of a column changed
+ *    (type, nullability, enum values, index) so one `alter_field` step covers them
+ *    all instead of several separate steps.
  *
- * Design borrowed from mature tools:
- *  - **Drizzle Kit**: keep the differ pure and inject RENAME decisions as data
- *    (the {@link RenameHints} resolver seam) rather than guessing — the same
- *    engine is then headless-testable and drivable by an interactive prompt.
- *  - **Prisma migration engine**: a two-tier destructive classification
- *    (warning vs unexecutable) and a type-change sub-tier
- *    (safe / risky / not-castable) that decides in-place `ALTER TYPE` vs a
- *    lossy drop-and-recreate.
- *  - **Atlas**: a single `alter_field` step carrying *which* facets changed
- *    (type / nullability / enum / index) instead of N discrete alter steps.
- *
- * Step ordering is the expand→contract sequence (add before drop, widen before
- * narrow): create models → rename → add columns (always nullable) → alter →
- * drop columns → drop models. NOT NULL is never set on add — it is an
- * `alter_field` nullability change that a backfill must precede.
+ * Steps come back in expand-then-contract order — add before drop, widen before
+ * narrow: create models, rename, add columns (always nullable), alter, drop columns,
+ * drop models. A newly added column is never created `NOT NULL`; making a column
+ * required is a separate nullability change that a backfill must run before.
  */
 import type { FieldMeta } from './field.js';
 import type { SchemaJSON } from './serialize.js';
 export type FieldType = FieldMeta['type'];
 /** Whether a Postgres `ALTER COLUMN … TYPE` can preserve the existing data. */
 export type CastSafety = 'safe' | 'risky' | 'notCastable';
+/** Records a column's type change and how safely Postgres can carry it out. */
 export interface FieldTypeChange {
     readonly from: FieldType;
     readonly to: FieldType;
-    /** `safe` → plain ALTER TYPE; `risky` → ALTER w/ USING (may fail per-row);
-     *  `notCastable` → drop-and-recreate (data loss). */
+    /** How the type change is carried out: `safe` runs a plain `ALTER COLUMN … TYPE`;
+     *  `risky` runs one with a `USING` cast that may fail on some rows; `notCastable`
+     *  drops and recreates the column, losing its data. */
     readonly cast: CastSafety;
 }
-/** `isOptional` transition. `true → false` is the dangerous direction. */
+/** Records a change to whether a field is optional. Going from optional to required
+ *  (`true → false`) is the dangerous direction: it fails if any existing row holds
+ *  a null. */
 export interface NullabilityChange {
     readonly fromOptional: boolean;
     readonly toOptional: boolean;
 }
+/** Records which allowed values an enum field gained and lost. Removing a value is
+ *  the risky part — existing rows still holding it violate the new constraint. */
 export interface EnumValuesChange {
     readonly added: readonly string[];
     readonly removed: readonly string[];
 }
+/** Records a change to whether a field is indexed (`from` was, `to` will be). */
 export interface IndexChange {
     readonly from: boolean;
     readonly to: boolean;
 }
-/** Physical column-name transition for a stable logical field. */
+/** Records a change to the physical database column name backing a field whose
+ *  logical name stayed the same. */
 export interface FieldColumnChange {
     readonly from: string;
     readonly to: string;
 }
-/** The facets of a single column that changed (Atlas-style bitmask, as data). */
+/** The set of facets of a single column that changed. Each optional member is
+ *  present only when that facet actually changed, so one `alter_field` step can
+ *  describe several simultaneous changes to the same column. */
 export interface FieldChanges {
     readonly column?: FieldColumnChange;
     readonly type?: FieldTypeChange;
@@ -63,6 +76,9 @@ export interface FieldChanges {
     readonly enumValues?: EnumValuesChange;
     readonly indexed?: IndexChange;
 }
+/** One step in a migration plan. The `kind` tag names the operation and the
+ *  remaining fields carry its target and payload. {@link diffSchema} emits these in
+ *  expand-then-contract order, and the host implementation lowers each to SQL. */
 export type MigrationStep = {
     readonly kind: 'create_model';
     readonly model: string;
@@ -96,10 +112,11 @@ export type MigrationStep = {
     readonly changes: FieldChanges;
 };
 /**
- * Rename decisions, injected as data (Drizzle's resolver seam). Without a hint,
- * a removed+added pair reads as drop+add (lossy) — the same safe default Prisma
- * takes. `field.model` refers to the model key in the NEXT schema (post any
- * model rename).
+ * Tells {@link diffSchema} which removed-and-added pairs are really renames. Supply
+ * these as data because the planner cannot safely guess: without a hint, a field
+ * that disappears and a field that appears read as a drop followed by an add, which
+ * loses the column's data. Each field rename names its model by the model's key in
+ * the new schema, after any model rename has been applied.
  */
 export interface RenameHints {
     readonly models?: readonly {
@@ -112,6 +129,9 @@ export interface RenameHints {
         readonly to: string;
     }[];
 }
+/** Reports how safely a field's type can change from `from` to `to`. The same type
+ *  in and out is always safe; anything else is looked up in the cast-safety matrix
+ *  and defaults to `notCastable` when no entry exists. */
 export declare function classifyCast(from: FieldType, to: FieldType): CastSafety;
 /**
  * Diff two serialized schemas into an ordered, expand→contract migration plan.
@@ -120,56 +140,73 @@ export declare function classifyCast(from: FieldType, to: FieldType): CastSafety
  * drop+add.
  */
 export declare function diffSchema(prev: SchemaJSON | null, next: SchemaJSON, hints?: RenameHints): MigrationStep[];
+/**
+ * Why a migration step is flagged as a warning — a change that runs but may lose or
+ * risk data on a non-empty table. Each code corresponds to one destructive step
+ * kind that {@link classifyMigration} recognizes.
+ */
 export type WarningCode = 'drop_model' | 'drop_field' | 'risky_cast' | 'lossy_recreate' | 'enum_value_removed'
-/** A model disappears from what this plane's READERS resolve, without any
- *  table being dropped. Emitted by the server's push gate (not
- *  `classifyMigration`) when a first sandbox push shadows the production
- *  artifact that sandbox readers were served via the registry's sandbox→production
- *  fallback. The data plane is untouched — the loss is visibility. */
+/** A model stops being served to readers even though no table is dropped. This is
+ *  raised when a push is accepted, not by {@link classifyMigration}, and the loss
+ *  is visibility, not data — the underlying rows are left untouched. */
  | 'remove_model';
+/** Why a migration step is unexecutable — it fails on a non-empty table unless a
+ *  default or backfill is supplied. Both cases introduce a requirement that existing
+ *  rows might not satisfy. */
 export type BlockerCode = 'required_field_added' | 'made_required';
+/**
+ * One flagged change in a classified migration plan. {@link code} says what kind of
+ * risk it is, {@link model} and the optional {@link field} say where, and
+ * {@link detail} is a human-readable explanation suitable for showing to a
+ * developer.
+ */
 export interface MigrationSignal {
     readonly code: WarningCode | BlockerCode;
     readonly model: string;
     readonly field?: string;
     readonly detail: string;
     /**
-     * Reader-visibility context for a removal that shadows an existing artifact:
-     * the active schema this push is being diffed against. Lets the CLI show the
-     * baseline — version + WHEN it was pushed — so "incompatible" isn't a mystery
-     * (e.g. a first sandbox push diffed against a months-old production schema).
+     * Extra context for a removal signal: the previously active schema this push was
+     * compared against. Tools use it to show which baseline made the push look
+     * incompatible — its version and when it was pushed — so the warning is not a
+     * mystery.
      */
     readonly shadowed?: {
         readonly environment: string;
         readonly version: number;
-        /** ISO timestamp the shadowed artifact was activated/pushed, or null. */
+        /** ISO 8601 timestamp when the compared-against schema was pushed, or null. */
         readonly pushedAt: string | null;
-        /** Who pushed it (e.g. `apikey:…`), or null. */
+        /** Who pushed the compared-against schema, or null. */
         readonly pushedBy: string | null;
     };
 }
+/** The result of classifying a migration plan: its flagged changes split by
+ *  severity. Produced by {@link classifyMigration} and read by
+ *  {@link isAutoApplicable} and {@link unresolvedBlockers}. */
 export interface MigrationClassification {
-    /** Execute but may lose or risk data on a non-empty table. */
+    /** Changes that run but may lose or risk data on a non-empty table. */
     readonly warnings: readonly MigrationSignal[];
-    /** Will fail on a non-empty table unless a default/backfill is supplied. */
+    /** Changes that fail on a non-empty table unless a default or backfill is supplied. */
     readonly unexecutable: readonly MigrationSignal[];
 }
 /**
- * Classify a plan's steps into Prisma-style warnings vs unexecutable. The IR
- * carries no per-field default, so a non-optional `add_field` is conservatively
- * unexecutable (a backfill or default resolves it) — we cannot prove a default
- * exists. Classification is rule-based (schema-derived); the runtime layer can
- * downgrade a signal to a no-op when the target table is empty.
+ * Sorts a plan's steps into {@link MigrationClassification.warnings} and
+ * {@link MigrationClassification.unexecutable}. Because a step carries no per-field
+ * default, adding a required field is treated conservatively as unexecutable — the
+ * classifier cannot prove a default exists, so a backfill or default must resolve
+ * it. The classification is derived from the schema alone; whoever runs the plan can
+ * still downgrade a flagged step to a no-op once it finds the target table is empty.
  */
 export declare function classifyMigration(steps: readonly MigrationStep[]): MigrationClassification;
-/** Convenience: a plan is safe to auto-apply iff it has no unexecutable steps. */
+/** Whether a plan is safe to apply automatically — true when it has no unexecutable
+ *  steps. Warnings do not block auto-apply; only unexecutable steps do. */
 export declare function isAutoApplicable(classification: MigrationClassification): boolean;
 /**
- * A constant value to seed into existing rows so an otherwise-`unexecutable`
- * step becomes safe: a required field added to a non-empty table, or a field
- * made required while NULLs exist. Deliberately a CONSTANT (not an SQL
- * expression) — arbitrary backfill logic is out of scope; this serves the
- * common "new column defaults to X" case only. `value` is typed to the field.
+ * A constant value to write into existing rows so an otherwise-unexecutable step can
+ * run: a required field added to a non-empty table, or a field made required while
+ * some rows hold null. This is intentionally a single constant, not an SQL
+ * expression — it covers the common "new column defaults to X" case; anything more
+ * elaborate is out of scope.
  */
 export interface BackfillValue {
     readonly model: string;
@@ -177,11 +214,12 @@ export interface BackfillValue {
     readonly value: string | number | boolean;
 }
 /**
- * Does a provided backfill resolve this blocker? Only the two row-dependent
- * blockers (`required_field_added`, `made_required`) are backfill-resolvable; a
- * data-loss *warning* is not — that always needs `force`.
+ * Reports whether a supplied backfill resolves this blocker. Only the two
+ * row-dependent blockers — `required_field_added` and `made_required` — can be
+ * resolved with a backfill; a data-loss warning cannot, and must be accepted
+ * explicitly instead.
  */
 export declare function isBlockerResolved(signal: MigrationSignal, backfills: readonly BackfillValue[]): boolean;
-/** The unexecutable signals NOT covered by a supplied backfill. Empty → the push
- *  can proceed (modulo the separate `warnings`/`force` gate). */
+/** The unexecutable signals that the supplied backfills do not cover. An empty
+ *  result means no blocker remains, though any warnings are still gated separately. */
 export declare function unresolvedBlockers(classification: MigrationClassification, backfills: readonly BackfillValue[]): readonly MigrationSignal[];

package/dist/schema/diff.js

@@ -1,29 +1,32 @@
 /**
- * Schema diff + migration planning — the pure core of the managed-migration loop.
+ * Computes the migration plan that turns one schema into another. Given two
+ * serialized schemas — the one currently active and the one being pushed — it
+ * produces an ordered list of {@link MigrationStep}s describing how to evolve the
+ * database, and a {@link MigrationClassification} that separates the risky parts
+ * into warnings (they run, but may lose or risk data on a non-empty table) and
+ * unexecutable steps (they fail on a non-empty table unless a backfill or default
+ * is supplied). This module only plans: it has no database dependency and emits no
+ * SQL, so it can be unit-tested exhaustively and reused by the command-line tools.
+ * Turning a step into SQL and running it happens in the host implementation, which
+ * owns the column-type mapping and row-security rules.
  *
- * Given two serialized schemas (the active one and the one being pushed), produce
- * an ordered list of {@link MigrationStep}s describing how to evolve the database,
- * and a {@link MigrationClassification} splitting the risky parts into *warnings*
- * (execute but may lose/risk data) and *unexecutable* steps (fail on a non-empty
- * table without a backfill/default). SQL emission and execution live elsewhere
- * (server-side, where the type map + RLS live); this module is intentionally pure
- * and DB-free so it is exhaustively unit-testable and reusable by the CLI.
+ * A few design choices worth knowing about:
+ *  - Renames are supplied as data through {@link RenameHints}, not guessed. Without
+ *    a hint, a removed field plus an added field reads as a drop followed by an add,
+ *    which is the safe (lossy) default; a hint tells the planner they are the same
+ *    field under a new name.
+ *  - Destructive changes fall into two tiers — warnings versus unexecutable — and a
+ *    type change carries its own sub-tier ({@link CastSafety}: safe, risky, or not
+ *    castable) that decides between an in-place `ALTER COLUMN … TYPE` and a lossy
+ *    drop-and-recreate.
+ *  - A single {@link FieldChanges} value records which facets of a column changed
+ *    (type, nullability, enum values, index) so one `alter_field` step covers them
+ *    all instead of several separate steps.
  *
- * Design borrowed from mature tools:
- *  - **Drizzle Kit**: keep the differ pure and inject RENAME decisions as data
- *    (the {@link RenameHints} resolver seam) rather than guessing — the same
- *    engine is then headless-testable and drivable by an interactive prompt.
- *  - **Prisma migration engine**: a two-tier destructive classification
- *    (warning vs unexecutable) and a type-change sub-tier
- *    (safe / risky / not-castable) that decides in-place `ALTER TYPE` vs a
- *    lossy drop-and-recreate.
- *  - **Atlas**: a single `alter_field` step carrying *which* facets changed
- *    (type / nullability / enum / index) instead of N discrete alter steps.
- *
- * Step ordering is the expand→contract sequence (add before drop, widen before
- * narrow): create models → rename → add columns (always nullable) → alter →
- * drop columns → drop models. NOT NULL is never set on add — it is an
- * `alter_field` nullability change that a backfill must precede.
+ * Steps come back in expand-then-contract order — add before drop, widen before
+ * narrow: create models, rename, add columns (always nullable), alter, drop columns,
+ * drop models. A newly added column is never created `NOT NULL`; making a column
+ * required is a separate nullability change that a backfill must run before.
  */
 // ── Cast safety matrix ────────────────────────────────────────────────────────
 // Keyed `${from}->${to}` over the 6 sync field types. Targets that map to TEXT
@@ -50,6 +53,9 @@ const CAST = {
     'string->json': 'risky', 'enum->json': 'risky', 'number->json': 'notCastable',
     'boolean->json': 'notCastable', 'date->json': 'notCastable',
 };
+/** Reports how safely a field's type can change from `from` to `to`. The same type
+ *  in and out is always safe; anything else is looked up in the cast-safety matrix
+ *  and defaults to `notCastable` when no entry exists. */
 export function classifyCast(from, to) {
     if (from === to)
         return 'safe';
@@ -197,11 +203,12 @@ export function diffSchema(prev, next, hints = {}) {
     return [...creates, ...renames, ...fieldSteps, ...drops];
 }
 /**
- * Classify a plan's steps into Prisma-style warnings vs unexecutable. The IR
- * carries no per-field default, so a non-optional `add_field` is conservatively
- * unexecutable (a backfill or default resolves it) — we cannot prove a default
- * exists. Classification is rule-based (schema-derived); the runtime layer can
- * downgrade a signal to a no-op when the target table is empty.
+ * Sorts a plan's steps into {@link MigrationClassification.warnings} and
+ * {@link MigrationClassification.unexecutable}. Because a step carries no per-field
+ * default, adding a required field is treated conservatively as unexecutable — the
+ * classifier cannot prove a default exists, so a backfill or default must resolve
+ * it. The classification is derived from the schema alone; whoever runs the plan can
+ * still downgrade a flagged step to a no-op once it finds the target table is empty.
  */
 export function classifyMigration(steps) {
     const warnings = [];
@@ -259,22 +266,24 @@ export function classifyMigration(steps) {
     }
     return { warnings, unexecutable };
 }
-/** Convenience: a plan is safe to auto-apply iff it has no unexecutable steps. */
+/** Whether a plan is safe to apply automatically — true when it has no unexecutable
+ *  steps. Warnings do not block auto-apply; only unexecutable steps do. */
 export function isAutoApplicable(classification) {
     return classification.unexecutable.length === 0;
 }
 /**
- * Does a provided backfill resolve this blocker? Only the two row-dependent
- * blockers (`required_field_added`, `made_required`) are backfill-resolvable; a
- * data-loss *warning* is not — that always needs `force`.
+ * Reports whether a supplied backfill resolves this blocker. Only the two
+ * row-dependent blockers — `required_field_added` and `made_required` — can be
+ * resolved with a backfill; a data-loss warning cannot, and must be accepted
+ * explicitly instead.
  */
 export function isBlockerResolved(signal, backfills) {
     if (signal.code !== 'required_field_added' && signal.code !== 'made_required')
         return false;
     return backfills.some((b) => b.model === signal.model && b.field === signal.field);
 }
-/** The unexecutable signals NOT covered by a supplied backfill. Empty → the push
- *  can proceed (modulo the separate `warnings`/`force` gate). */
+/** The unexecutable signals that the supplied backfills do not cover. An empty
+ *  result means no blocker remains, though any warnings are still gated separately. */
 export function unresolvedBlockers(classification, backfills) {
     return classification.unexecutable.filter((s) => !isBlockerResolved(s, backfills));
 }

package/dist/schema/field.d.ts

@@ -1,9 +1,10 @@
 /**
- * Schema Field Helpers
- *
- * Thin wrappers around Zod that add sync-engine metadata (type tag, indexed).
- * Metadata is stored in `z.describe()` as a JSON-encoded string so it
- * survives `.optional()`, `.nullable()`, and `.default()` chain calls.
+ * Field builders for schema definitions. Each helper — {@link field}.string(),
+ * .number(), .enum(), and so on — returns an ordinary Zod schema with a little
+ * sync-engine metadata attached (its type tag and whether it is indexed) plus a
+ * couple of chainable methods. The metadata is tucked into the schema's description
+ * as a JSON string so it survives `.optional()`, `.nullable()`, and `.default()`
+ * chaining, and {@link resolveFieldMeta} reads it back out as a {@link FieldMeta}.
  *
  * Usage:
  *   import { field } from '@abloatai/ablo/schema';
@@ -23,9 +24,11 @@
  *   });
  */
 import { z } from 'zod';
-/** Runtime metadata for a schema field, readable via `ModelDef.fields`. */
+/** The sync-engine metadata describing one field, available at runtime through a
+ *  model's `fields` map. The {@link field} builders attach it, and the migration
+ *  planner, type generator, and OpenAPI generator all read it. */
 export interface FieldMeta {
-    /** Sync-engine type tag (maps to storage/serialization hints). */
+    /** Sync-engine type tag, which maps to storage and serialization hints. */
     type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'json';
     /** Whether the field was marked optional via `.optional()` or `.nullable()`. */
     isOptional: boolean;
@@ -48,53 +51,44 @@ export interface FieldMeta {
  */
 export declare function getFieldMeta(schema: z.ZodType): FieldMeta | null;
 /**
- * Fallback: infer FieldMeta directly from a raw Zod schema when no
- * `field.*()` metadata was attached.
- *
- * Walks through `.optional()` / `.nullable()` / `.default()` wrappers
- * to find the inner primitive, then maps Zod's `_def.typeName` to
- * the sync-engine type tag. Used by `resolveFieldMeta` and by
- * `model()` / `query()` at definition time.
- *
- * Kept as an internal helper rather than exported directly — the
- * public API is `resolveFieldMeta`, which combines this fallback
- * with the `getFieldMeta` fast path.
+ * Infers a {@link FieldMeta} from a plain Zod schema that carries no field-builder
+ * metadata — for example a bare `z.string()`. It unwraps `.optional()`,
+ * `.nullable()`, and `.default()` to reach the inner type, then maps that Zod type
+ * to a sync-engine type tag. Most callers should use {@link resolveFieldMeta}
+ * instead, which tries the attached metadata first and falls back to this.
  */
 export declare function inferFieldMetaFromZod(schema: z.ZodType): FieldMeta;
 /**
- * Resolve FieldMeta for any Zod schema — whether it was built with
- * `field.*()` (which attaches sync-engine metadata) or with raw Zod
- * (which requires fallback inference from `_def.typeName`).
- *
- * This is the single public entry point for "given a Zod field, tell
- * me its sync-engine type tag and optionality." Both `model()` and
- * `query()` use it to populate their `fields` / `inputFields` maps at
- * definition time, and the schema serializer reads those maps at
- * serialization time.
+ * Resolves a {@link FieldMeta} for any Zod schema, whether it was built with a
+ * {@link field} builder (which attaches metadata) or with plain Zod (which needs
+ * inference). This is the single entry point for "given a Zod field, tell me its
+ * sync-engine type tag and whether it is optional"; the model and query builders use
+ * it to populate their field maps, and the serializer reads those maps.
  *
- * Contract: always returns a value. Never returns null. Unknown Zod
- * types fall through to `'string'` — this is intentional and matches
- * the existing behavior that was previously duplicated in
- * `model.ts:inferMetaFromZod`.
+ * It always returns a value and never returns null. A Zod type it does not recognize
+ * falls through to the `string` tag by design.
  */
 export declare function resolveFieldMeta(schema: z.ZodType): FieldMeta;
+/** A Zod schema returned by a {@link field} builder — the underlying Zod type plus
+ *  two chainable methods: `indexed()` marks the field for a database index, and
+ *  `from(column)` overrides the physical column name it maps to. */
 export type FieldBuilder<T extends z.ZodType> = T & {
     indexed(): FieldBuilder<T>;
     from(column: string): FieldBuilder<T>;
 };
 export declare const field: {
-    /** String field */
+    /** Defines a text field. */
     readonly string: () => FieldBuilder<z.ZodString>;
-    /** Number field */
+    /** Defines a numeric field. */
     readonly number: () => FieldBuilder<z.ZodNumber>;
-    /** Boolean field */
+    /** Defines a true/false field. */
     readonly boolean: () => FieldBuilder<z.ZodBoolean>;
-    /** Date field */
+    /** Defines a timestamp field, represented as a JavaScript `Date`. */
     readonly date: () => FieldBuilder<z.ZodDate>;
-    /** Enum field with constrained string values */
+    /** Defines a field constrained to a fixed set of string values. */
     readonly enum: <const T extends readonly [string, ...string[]]>(values: T) => FieldBuilder<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>;
     /**
-     * JSON field. Three call shapes:
+     * Defines a JSON field, with three call shapes:
      *
      * ```ts
      * field.json()                                        // unknown JSON blob
@@ -102,9 +96,9 @@ export declare const field: {
      * field.json({ icon: z.string().default('default') }) // typed sub-properties with defaults
      * ```
      *
-     * The third form is the key DX feature for metadata fields. It wraps the
-     * plain object in `z.object()` automatically, and the model runtime generates
-     * a `${field}Json` getter that parses the JSON string on read, applies Zod
+     * The third form is especially handy for metadata fields. It wraps the plain
+     * object in `z.object()` automatically, and the model runtime adds a
+     * `${field}Json` getter that parses the JSON string on read, applies the Zod
      * defaults, and caches the result.
      *
      * Example:
@@ -124,8 +118,9 @@ export declare const field: {
      * ```
      */
     readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => FieldBuilder<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
-    /** Indexed string field (shorthand for `field.string().indexed()`). */
+    /** Defines an indexed text field — shorthand for `field.string().indexed()`. */
     readonly id: () => FieldBuilder<z.ZodString>;
 };
-/** Mark a Zod schema as indexed for fast lookups (function form). */
+/** Marks a Zod schema as indexed so lookups on it use a database index. This is the
+ *  standalone-function form of the `.indexed()` chain method. */
 export declare function indexed<T extends z.ZodType>(schema: T): T;