@atscript/db 0.1.154 → 0.1.155

package/dist/agg.d.cts

@@ -1,3 +1,3 @@
-import { r as TResolvedBucket } from "./buckets-jy8BfswO.cjs";
+import { r as TResolvedBucket } from "./buckets-DcWm3SLt.cjs";
 import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-42CSpGDR.cjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/agg.d.mts

@@ -1,3 +1,3 @@
-import { r as TResolvedBucket } from "./buckets-CBKL_ZWE.mjs";
+import { r as TResolvedBucket } from "./buckets-goCoky8v.mjs";
 import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-Wo-smrYV.mjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/{buckets-jy8BfswO.d.cts → buckets-DcWm3SLt.d.cts}

@@ -594,7 +594,9 @@ type DbResponse<Data, Nav, Q> = [keyof Nav] extends [never] ? Data : string exte
  * otherwise trips up every adapter author.
  *
  * For union types (e.g., from flattened `{...} | {...}` objects):
- * - If all members resolve to the same type → returns that type (strong type)
+ * - `null` / `undefined` members are left out (since 0.1.155): `T | null`
+ *   resolves to the design type of `T`
+ * - If all other members resolve to the same type → returns that type (strong type)
  * - If members disagree → returns `'union'` (out of scope for type management)
  */
 declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
@@ -1545,8 +1547,21 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
    * adapter handles natively are NOT filled — the field stays absent so the
    * engine's own default applies. The version column is never touched.
+   * A nested field (`audit.createdAt`) is filled inside its object, only when
+   * that object is present (an absent or `null` embedded object stays so), and
+   * in every object of an array on the way; a field inside a JSON value or an
+   * array has no column default, so the SDK fills its function default too.
    */
   protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /** {@link _nestedDefaultFillable} per nested default path. */
+  private _fillableDefaults?;
+  /**
+   * Whether every parent of the nested default `field` is one object type —
+   * an object, `T | null` of one, or an array of one. Below a tuple or a
+   * union of several types the default cannot be placed (the item it belongs
+   * to is unknown), so it is not filled.
+   */
+  private _nestedDefaultFillable;
   /**
    * Parsed `@db.default 'literal'` values that are primitives — reused for
    * every row (an object / array default is parsed per row: each row gets
@@ -2878,6 +2893,24 @@ declare abstract class BaseDbAdapter {
    * Optional — only relational adapters implement this.
    */
   dropTable?(): Promise<void>;
+  /**
+   * Schema sync (since 0.1.155): copies the values of `source` — a text
+   * column holding a whole value as JSON (the layout atscript-db ≤ 0.1.154
+   * gave a `T | null` object or a union field) — into the columns that
+   * replace it, in rows where `source` is not NULL and every target is NULL.
+   * A malformed JSON value or one that does not convert to a target's type
+   * throws (the table's sync entry errors before anything is dropped).
+   * Optional — relational adapters implement it.
+   */
+  copyFromJsonColumn?(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
+  /**
+   * Schema sync (since 0.1.155): rewrites the values of the text column
+   * `column` that are not JSON as JSON strings (`abc` → `"abc"`), before the
+   * column becomes a JSON column — the layout ≤ 0.1.154 stored a mixed
+   * union's string member as plain text. Idempotent.
+   * Optional — relational adapters implement it.
+   */
+  jsonifyTextColumn?(column: string): Promise<void>;
   /**
    * Drops one or more columns from the table.
    * Used by schema sync to remove stale columns no longer in the schema.
@@ -2921,7 +2954,7 @@ declare abstract class BaseDbAdapter {
   dropTablesByName(tableNames: string[]): Promise<void>;
   /**
    * Whether the table has at least one row. Schema sync uses it in the
-   * pre-flight phase to refuse a primary-key change on a populated table.
+   * pre-flight phase to check a primary-key change on a populated table.
    * Override with an EXISTS/LIMIT 1 probe — this default is `count() > 0`,
    * a full scan on some engines, and it can only answer for the adapter's
    * OWN table: for another `tableName` (or on an administrative adapter
@@ -2955,12 +2988,26 @@ declare abstract class BaseDbAdapter {
   getObjectKind?(name: string): Promise<TDbObjectKind | undefined>;
   /**
    * Rewrites the table's primary key from `change.from` to `change.to`.
-   * Called only on an EMPTY table (schema sync refuses populated ones) after
-   * new columns were added and before stale columns are dropped, so both
-   * column sets exist. Adapters without it fall back to {@link recreateTable}.
+   * Called on an empty table, or (since 0.1.155) on a populated one whose
+   * rows already satisfy the new key ({@link countKeyViolations} answered
+   * `0`), after new columns were added and before stale columns are dropped,
+   * so both column sets exist. Adapters without it fall back to
+   * {@link recreateTable}.
    * @since 0.1.128
    */
   rebuildPrimaryKey?(change: TPrimaryKeyChange): Promise<void>;
+  /**
+   * How many rows of the live table `columns` cannot hold as a primary key:
+   * rows with a NULL (or missing value) in one of them, plus every row that
+   * shares its values with another. Schema sync rebuilds the key of a
+   * populated table only when this answers `0`, and refuses the run with the
+   * count otherwise. Optional — without it a populated key change is refused.
+   *
+   * @param tableName - Check this table instead of the adapter's own (the OLD
+   *   name of a table that is about to be renamed).
+   * @since 0.1.155
+   */
+  countKeyViolations?(columns: readonly string[], tableName?: string): Promise<number>;
   /**
    * Renames a table/collection from `oldName` to the adapter's current table name.
    * Used by schema sync when `@db.table.renamed` is present.
@@ -3006,6 +3053,16 @@ declare abstract class BaseDbAdapter {
   formatValue?(field: TDbFieldMeta): TValueFormatterPair | ((value: unknown) => unknown) | undefined;
 }
 //#endregion
+//#region src/shared/union-shape.d.ts
+/**
+ * Whether a value at a path is always there (`"required"`), may be NULL /
+ * missing (`"nullable"` — the path or an ancestor object is optional or a
+ * `| null` union), or is declared by only some members of a union of objects
+ * on the way (`"partial"` — `card` of `payment: Card | Bank` when only
+ * `Card` declares it). Ordered: each is weaker than the previous one.
+ */
+type TPathPresence = "required" | "nullable" | "partial";
+//#endregion
 //#region src/table/table-metadata.d.ts
 /** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
 declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
@@ -3142,8 +3199,42 @@ declare class TableMetadata {
   private _alwaysAddressable?;
   private _collateMap;
   private _columnFromMap;
+  /** The annotated type `build()` ran on — the root of {@link presence}. */
+  private _rootType?;
+  private readonly _presence;
   constructor(nestedObjects: boolean);
   get isBuilt(): boolean;
+  /**
+   * Whether the value of the LOGICAL field `path` is always there, may be
+   * NULL / missing, or is declared by only some members of a union of
+   * objects on the way ({@link TPathPresence}); `undefined` inside an array.
+   * @since 0.1.155
+   */
+  presence(path: string): TPathPresence | undefined;
+  /**
+   * Whether the LOGICAL field `path` can hold NULL (or be missing): it or a
+   * parent object is optional or a `| null` union, or only some members of
+   * a union of objects declare it. Inside an array: the field or a parent
+   * is optional.
+   * @since 0.1.155
+   */
+  isNullable(path: string): boolean;
+  private _objectLeaves?;
+  /**
+   * The stored fields under the object field `path` that a null test on the
+   * object reads (`rewriteObjectNullTests`, since 0.1.155): its leaf columns
+   * on relational storage, its scalar / array / JSON fields on document
+   * storage (not inside an array or a JSON value). `undefined` when `path`
+   * is no stored object (a leaf, a `@db.json` / encrypted / ignored field,
+   * a navigation relation, inside a JSON value, unknown).
+   */
+  objectLeaves(path: string): readonly string[] | undefined;
+  /**
+   * Whether the column of `path` is nullable: {@link isNullable}, except
+   * inside an array (document storage only), where the field's own
+   * optionality counts.
+   */
+  private _columnNullable;
   /**
    * {@link documentPath} over this table's `columnMap`. A `@db.column.derived`
    * field has no stored path of its own: it maps to its source leaf.
@@ -3184,10 +3275,13 @@ declare class TableMetadata {
    * into the synthetic flat entry of the prop's path, so a member's
    * annotations would reach the column (DDL type, size, default). Since
    * atscript 0.1.103 a built-in primitive member carries its built-in
-   * annotations (`number.timestamp.created | null` → `@db.default.now`,
-   * `string.char` → `@expect.maxLength 1`). Rebuild such an entry from the
-   * prop's own annotations plus the non-`db.*` annotations of named members
-   * (aliases, interfaces), so the column is described as before 0.1.103.
+   * annotations (`string.char` → `@expect.maxLength 1`). Rebuild such an
+   * entry from the prop's own annotations plus the non-`db.*` annotations of
+   * named members (aliases, interfaces), so the column is described as before
+   * 0.1.103. Exception: the one non-`null` member of `T | null` is the
+   * column's type, so its `db.*` annotations apply too — `createdAt:
+   * number.timestamp.created | null` gets `@db.default.now` like
+   * `createdAt: number.timestamp.created`.
    */
   private _dropMemberMetadata;
   /**
@@ -3973,6 +4067,22 @@ interface TExistingColumn {
  * @since 0.1.141
  */
 type TDerivedChangeReason = "kind" | "expression" | "type";
+/**
+ * One column {@link BaseDbAdapter.copyFromJsonColumn} fills from the JSON
+ * text of a column the previous layout stored a whole value in (since 0.1.155).
+ */
+interface TJsonCopyTarget {
+  /** Physical column to fill. */
+  column: string;
+  /** Path of the value inside the source JSON (logical property names). */
+  path: readonly string[];
+  /**
+   * How the value is read: `text` — a scalar as text, cast to the column
+   * type; `boolean` — a JSON boolean; `json` — the sub-value as JSON.
+   */
+  kind: "text" | "boolean" | "json";
+  field: TDbFieldMeta;
+}
 /** Result of comparing desired schema against existing database columns. */
 interface TColumnDiff {
   added: TDbFieldMeta[];
@@ -4573,4 +4683,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbInsertResult as $, DbSpace as $t, TColumnDiff as A, TRelationFilterJunction as An, TReferencingForeignKey as At, TDbDefaultFn as B, TDbEncryptionOptions as Bn, TWriteOptions as Bt, NavPropsOf$1 as C, AtscriptDbReadable as Cn, TIdDescriptor as Ct, PrimaryKeyOf$1 as D, REL_FILTER_MAX_NODES as Dn, TMetaResponse as Dt, OwnPropsOf$1 as E, REL_FILTER_MAX_DEPTH as En, TInsertOptions as Et, TDbActionLevel as F, forEachResolvedRelation as Fn, TTableOptionDiff as Ft, TDbIndex as G, TGenericLogger as Gn, WithRelation$1 as Gt, TDbDeleteResult as H, FieldMappingStrategy as Hn, TypedWithRelation as Ht, TDbActionProcessor as I, hasRelationOp as In, TTableResolver as It, TDbInsertIgnoreOptions as J, TRowOrderKey as Jn, isGeoPointType as Jt, TDbIndexField as K, TExprAggregate as Kn, TableMetadata as Kt, TDbActionTargetSummary as L, isResolvedRelationFilter as Ln, TTouchManyOptions as Lt, TCrudPermissions as M, TRelationStaticFilter as Mn, TRowResolveOptions as Mt, TDbActionInfo as N, andFilters as Nn, TSearchIndexInfo as Nt, TCascadeResolver as O, ResolvedRelationFilter as On, TMetadataOverrides as Ot, TDbActionIntent as P, containsRelationFilter as Pn, TSyncColumnResult as Pt, TDbInsertManyResult as Q, TViewCapability as Qt, TDbAvailableActions as R, relationStaticFilter as Rn, TValueFormatterPair as Rt, FlatOf$1 as S, TCascadePin as Sn, TFkLookupTarget as St, NullsPlacement$1 as T, resolveDesignType as Tn, TIdentification as Tt, TDbFieldMeta as U, TReadControls as Un, Uniquery$1 as Ut, TDbDefaultValue as V, DocumentFieldMapper as Vn, TWriteTableResolver as Vt, TDbForeignKey as W, NoopLogger as Wn, UniqueryControls$1 as Wt, TDbInsertIgnoreSlot as X, ALL_VIEW_CAPABILITIES as Xt, TDbInsertIgnoreResult as Y, UniquSelect as Yn, ALL_BUCKET_UNITS as Yt, TDbInsertManyIgnoreResult as Z, BaseDbAdapter as Zt, DbPatch as _, isFieldRef as _n, TExistingColumn as _t, isJsonValueField as a, isViewType as an, TDbStorageType as at, FieldOpsFor as b, IntegrityStrategy as bn, TFieldMeta as bt, resolveCalendarBuckets as c, AtscriptExprNode$1 as cn, TDbWriteAction as ct, AggregateFn$1 as d, AtscriptQueryFieldRef$1 as dn, TDbWriteGuard as dt, TAdapterFactory as en, TDbObjectKind as et, AggregateQuery$1 as f, AtscriptQueryNode$1 as fn, TDbWriteGuardContext as ft, DbControls as g, evaluateExpr as gn, TEnsureTableOptions as gt, AtscriptDbWritable as h, TViewPlan as hn, TDerivedColumn as ht, isBucketableField as i, isAtscriptDbView as in, TDbRemoveGuardContext as it, TCrudOp as j, TRelationFilterTable as jn, TRelationInfo as jt, TCascadeTarget as k, TRelGuardState as kn, TPrimaryKeyChange as kt, AggregateControls as l, AtscriptOrderItem as ln, TDbWriteCheck as lt, AtscriptDbTableLike as m, TViewJoin as mn, TDerivedChangeReason as mt, TComputedSelect as n, AtscriptDbView as nn, TDbRelation as nt, jsonValueAncestor as o, TViewReadPlan as on, TDbUpdateOptions as ot, AggregateResult as p, AtscriptRef as pn, TDeleteOptions as pt, TDbIndexType as q, TFirstLast as qn, isGeoIndexableType as qt, TResolvedBucket as r, TViewColumnMapping as rn, TDbRemoveGuard as rt, normalizeComputedSelect as s, aliasTargetOf as sn, TDbUpdateResult as st, TBucketFieldSource as t, TDbSpaceOptions as tn, TDbReferentialAction as tt, AggregateExpr$1 as u, AtscriptQueryComparison as un, TDbWriteCheckContext as ut, DbQuery as v, translateQueryTree as vn, TExistingForeignKey as vt, NullableOptional as w, DbResponse as wn, TIdResolveOptions as wt, FilterExpr$1 as x, NativeIntegrity as xn, TFkLookupResolver as xt, DbRow as y, AtscriptDbTable as yn, TExistingTableOption as yt, TDbCollation as z, DbEncryption as zn, TViewJsonType as zt };
+export { TDbInsertResult as $, BaseDbAdapter as $t, TColumnDiff as A, ResolvedRelationFilter as An, TPrimaryKeyChange as At, TDbDefaultFn as B, relationStaticFilter as Bn, TViewJsonType as Bt, NavPropsOf$1 as C, NativeIntegrity as Cn, TIdDescriptor as Ct, PrimaryKeyOf$1 as D, resolveDesignType as Dn, TJsonCopyTarget as Dt, OwnPropsOf$1 as E, DbResponse as En, TInsertOptions as Et, TDbActionLevel as F, andFilters as Fn, TSyncColumnResult as Ft, TDbIndex as G, TReadControls as Gn, UniqueryControls$1 as Gt, TDbDeleteResult as H, TDbEncryptionOptions as Hn, TWriteTableResolver as Ht, TDbActionProcessor as I, containsRelationFilter as In, TTableOptionDiff as It, TDbInsertIgnoreOptions as J, TExprAggregate as Jn, isGeoIndexableType as Jt, TDbIndexField as K, NoopLogger as Kn, WithRelation$1 as Kt, TDbActionTargetSummary as L, forEachResolvedRelation as Ln, TTableResolver as Lt, TCrudPermissions as M, TRelationFilterJunction as Mn, TRelationInfo as Mt, TDbActionInfo as N, TRelationFilterTable as Nn, TRowResolveOptions as Nt, TCascadeResolver as O, REL_FILTER_MAX_DEPTH as On, TMetaResponse as Ot, TDbActionIntent as P, TRelationStaticFilter as Pn, TSearchIndexInfo as Pt, TDbInsertManyResult as Q, ALL_VIEW_CAPABILITIES as Qt, TDbAvailableActions as R, hasRelationOp as Rn, TTouchManyOptions as Rt, FlatOf$1 as S, IntegrityStrategy as Sn, TFkLookupTarget as St, NullsPlacement$1 as T, AtscriptDbReadable as Tn, TIdentification as Tt, TDbFieldMeta as U, DocumentFieldMapper as Un, TypedWithRelation as Ut, TDbDefaultValue as V, DbEncryption as Vn, TWriteOptions as Vt, TDbForeignKey as W, FieldMappingStrategy as Wn, Uniquery$1 as Wt, TDbInsertIgnoreSlot as X, TRowOrderKey as Xn, TPathPresence as Xt, TDbInsertIgnoreResult as Y, TFirstLast as Yn, isGeoPointType as Yt, TDbInsertManyIgnoreResult as Z, UniquSelect as Zn, ALL_BUCKET_UNITS as Zt, DbPatch as _, TViewPlan as _n, TExistingColumn as _t, isJsonValueField as a, TViewColumnMapping as an, TDbStorageType as at, FieldOpsFor as b, translateQueryTree as bn, TFieldMeta as bt, resolveCalendarBuckets as c, TViewReadPlan as cn, TDbWriteAction as ct, AggregateFn$1 as d, AtscriptOrderItem as dn, TDbWriteGuard as dt, TViewCapability as en, TDbObjectKind as et, AggregateQuery$1 as f, AtscriptQueryComparison as fn, TDbWriteGuardContext as ft, DbControls as g, TViewJoin as gn, TEnsureTableOptions as gt, AtscriptDbWritable as h, AtscriptRef as hn, TDerivedColumn as ht, isBucketableField as i, AtscriptDbView as in, TDbRemoveGuardContext as it, TCrudOp as j, TRelGuardState as jn, TReferencingForeignKey as jt, TCascadeTarget as k, REL_FILTER_MAX_NODES as kn, TMetadataOverrides as kt, AggregateControls as l, aliasTargetOf as ln, TDbWriteCheck as lt, AtscriptDbTableLike as m, AtscriptQueryNode$1 as mn, TDerivedChangeReason as mt, TComputedSelect as n, TAdapterFactory as nn, TDbRelation as nt, jsonValueAncestor as o, isAtscriptDbView as on, TDbUpdateOptions as ot, AggregateResult as p, AtscriptQueryFieldRef$1 as pn, TDeleteOptions as pt, TDbIndexType as q, TGenericLogger as qn, TableMetadata as qt, TResolvedBucket as r, TDbSpaceOptions as rn, TDbRemoveGuard as rt, normalizeComputedSelect as s, isViewType as sn, TDbUpdateResult as st, TBucketFieldSource as t, DbSpace as tn, TDbReferentialAction as tt, AggregateExpr$1 as u, AtscriptExprNode$1 as un, TDbWriteCheckContext as ut, DbQuery as v, evaluateExpr as vn, TExistingForeignKey as vt, NullableOptional as w, TCascadePin as wn, TIdResolveOptions as wt, FilterExpr$1 as x, AtscriptDbTable as xn, TFkLookupResolver as xt, DbRow as y, isFieldRef as yn, TExistingTableOption as yt, TDbCollation as z, isResolvedRelationFilter as zn, TValueFormatterPair as zt };

package/dist/{buckets-CBKL_ZWE.d.mts → buckets-goCoky8v.d.mts}

@@ -594,7 +594,9 @@ type DbResponse<Data, Nav, Q> = [keyof Nav] extends [never] ? Data : string exte
  * otherwise trips up every adapter author.
  *
  * For union types (e.g., from flattened `{...} | {...}` objects):
- * - If all members resolve to the same type → returns that type (strong type)
+ * - `null` / `undefined` members are left out (since 0.1.155): `T | null`
+ *   resolves to the design type of `T`
+ * - If all other members resolve to the same type → returns that type (strong type)
  * - If members disagree → returns `'union'` (out of scope for type management)
  */
 declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
@@ -1545,8 +1547,21 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
    * adapter handles natively are NOT filled — the field stays absent so the
    * engine's own default applies. The version column is never touched.
+   * A nested field (`audit.createdAt`) is filled inside its object, only when
+   * that object is present (an absent or `null` embedded object stays so), and
+   * in every object of an array on the way; a field inside a JSON value or an
+   * array has no column default, so the SDK fills its function default too.
    */
   protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /** {@link _nestedDefaultFillable} per nested default path. */
+  private _fillableDefaults?;
+  /**
+   * Whether every parent of the nested default `field` is one object type —
+   * an object, `T | null` of one, or an array of one. Below a tuple or a
+   * union of several types the default cannot be placed (the item it belongs
+   * to is unknown), so it is not filled.
+   */
+  private _nestedDefaultFillable;
   /**
    * Parsed `@db.default 'literal'` values that are primitives — reused for
    * every row (an object / array default is parsed per row: each row gets
@@ -2878,6 +2893,24 @@ declare abstract class BaseDbAdapter {
    * Optional — only relational adapters implement this.
    */
   dropTable?(): Promise<void>;
+  /**
+   * Schema sync (since 0.1.155): copies the values of `source` — a text
+   * column holding a whole value as JSON (the layout atscript-db ≤ 0.1.154
+   * gave a `T | null` object or a union field) — into the columns that
+   * replace it, in rows where `source` is not NULL and every target is NULL.
+   * A malformed JSON value or one that does not convert to a target's type
+   * throws (the table's sync entry errors before anything is dropped).
+   * Optional — relational adapters implement it.
+   */
+  copyFromJsonColumn?(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
+  /**
+   * Schema sync (since 0.1.155): rewrites the values of the text column
+   * `column` that are not JSON as JSON strings (`abc` → `"abc"`), before the
+   * column becomes a JSON column — the layout ≤ 0.1.154 stored a mixed
+   * union's string member as plain text. Idempotent.
+   * Optional — relational adapters implement it.
+   */
+  jsonifyTextColumn?(column: string): Promise<void>;
   /**
    * Drops one or more columns from the table.
    * Used by schema sync to remove stale columns no longer in the schema.
@@ -2921,7 +2954,7 @@ declare abstract class BaseDbAdapter {
   dropTablesByName(tableNames: string[]): Promise<void>;
   /**
    * Whether the table has at least one row. Schema sync uses it in the
-   * pre-flight phase to refuse a primary-key change on a populated table.
+   * pre-flight phase to check a primary-key change on a populated table.
    * Override with an EXISTS/LIMIT 1 probe — this default is `count() > 0`,
    * a full scan on some engines, and it can only answer for the adapter's
    * OWN table: for another `tableName` (or on an administrative adapter
@@ -2955,12 +2988,26 @@ declare abstract class BaseDbAdapter {
   getObjectKind?(name: string): Promise<TDbObjectKind | undefined>;
   /**
    * Rewrites the table's primary key from `change.from` to `change.to`.
-   * Called only on an EMPTY table (schema sync refuses populated ones) after
-   * new columns were added and before stale columns are dropped, so both
-   * column sets exist. Adapters without it fall back to {@link recreateTable}.
+   * Called on an empty table, or (since 0.1.155) on a populated one whose
+   * rows already satisfy the new key ({@link countKeyViolations} answered
+   * `0`), after new columns were added and before stale columns are dropped,
+   * so both column sets exist. Adapters without it fall back to
+   * {@link recreateTable}.
    * @since 0.1.128
    */
   rebuildPrimaryKey?(change: TPrimaryKeyChange): Promise<void>;
+  /**
+   * How many rows of the live table `columns` cannot hold as a primary key:
+   * rows with a NULL (or missing value) in one of them, plus every row that
+   * shares its values with another. Schema sync rebuilds the key of a
+   * populated table only when this answers `0`, and refuses the run with the
+   * count otherwise. Optional — without it a populated key change is refused.
+   *
+   * @param tableName - Check this table instead of the adapter's own (the OLD
+   *   name of a table that is about to be renamed).
+   * @since 0.1.155
+   */
+  countKeyViolations?(columns: readonly string[], tableName?: string): Promise<number>;
   /**
    * Renames a table/collection from `oldName` to the adapter's current table name.
    * Used by schema sync when `@db.table.renamed` is present.
@@ -3006,6 +3053,16 @@ declare abstract class BaseDbAdapter {
   formatValue?(field: TDbFieldMeta): TValueFormatterPair | ((value: unknown) => unknown) | undefined;
 }
 //#endregion
+//#region src/shared/union-shape.d.ts
+/**
+ * Whether a value at a path is always there (`"required"`), may be NULL /
+ * missing (`"nullable"` — the path or an ancestor object is optional or a
+ * `| null` union), or is declared by only some members of a union of objects
+ * on the way (`"partial"` — `card` of `payment: Card | Bank` when only
+ * `Card` declares it). Ordered: each is weaker than the previous one.
+ */
+type TPathPresence = "required" | "nullable" | "partial";
+//#endregion
 //#region src/table/table-metadata.d.ts
 /** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
 declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
@@ -3142,8 +3199,42 @@ declare class TableMetadata {
   private _alwaysAddressable?;
   private _collateMap;
   private _columnFromMap;
+  /** The annotated type `build()` ran on — the root of {@link presence}. */
+  private _rootType?;
+  private readonly _presence;
   constructor(nestedObjects: boolean);
   get isBuilt(): boolean;
+  /**
+   * Whether the value of the LOGICAL field `path` is always there, may be
+   * NULL / missing, or is declared by only some members of a union of
+   * objects on the way ({@link TPathPresence}); `undefined` inside an array.
+   * @since 0.1.155
+   */
+  presence(path: string): TPathPresence | undefined;
+  /**
+   * Whether the LOGICAL field `path` can hold NULL (or be missing): it or a
+   * parent object is optional or a `| null` union, or only some members of
+   * a union of objects declare it. Inside an array: the field or a parent
+   * is optional.
+   * @since 0.1.155
+   */
+  isNullable(path: string): boolean;
+  private _objectLeaves?;
+  /**
+   * The stored fields under the object field `path` that a null test on the
+   * object reads (`rewriteObjectNullTests`, since 0.1.155): its leaf columns
+   * on relational storage, its scalar / array / JSON fields on document
+   * storage (not inside an array or a JSON value). `undefined` when `path`
+   * is no stored object (a leaf, a `@db.json` / encrypted / ignored field,
+   * a navigation relation, inside a JSON value, unknown).
+   */
+  objectLeaves(path: string): readonly string[] | undefined;
+  /**
+   * Whether the column of `path` is nullable: {@link isNullable}, except
+   * inside an array (document storage only), where the field's own
+   * optionality counts.
+   */
+  private _columnNullable;
   /**
    * {@link documentPath} over this table's `columnMap`. A `@db.column.derived`
    * field has no stored path of its own: it maps to its source leaf.
@@ -3184,10 +3275,13 @@ declare class TableMetadata {
    * into the synthetic flat entry of the prop's path, so a member's
    * annotations would reach the column (DDL type, size, default). Since
    * atscript 0.1.103 a built-in primitive member carries its built-in
-   * annotations (`number.timestamp.created | null` → `@db.default.now`,
-   * `string.char` → `@expect.maxLength 1`). Rebuild such an entry from the
-   * prop's own annotations plus the non-`db.*` annotations of named members
-   * (aliases, interfaces), so the column is described as before 0.1.103.
+   * annotations (`string.char` → `@expect.maxLength 1`). Rebuild such an
+   * entry from the prop's own annotations plus the non-`db.*` annotations of
+   * named members (aliases, interfaces), so the column is described as before
+   * 0.1.103. Exception: the one non-`null` member of `T | null` is the
+   * column's type, so its `db.*` annotations apply too — `createdAt:
+   * number.timestamp.created | null` gets `@db.default.now` like
+   * `createdAt: number.timestamp.created`.
    */
   private _dropMemberMetadata;
   /**
@@ -3973,6 +4067,22 @@ interface TExistingColumn {
  * @since 0.1.141
  */
 type TDerivedChangeReason = "kind" | "expression" | "type";
+/**
+ * One column {@link BaseDbAdapter.copyFromJsonColumn} fills from the JSON
+ * text of a column the previous layout stored a whole value in (since 0.1.155).
+ */
+interface TJsonCopyTarget {
+  /** Physical column to fill. */
+  column: string;
+  /** Path of the value inside the source JSON (logical property names). */
+  path: readonly string[];
+  /**
+   * How the value is read: `text` — a scalar as text, cast to the column
+   * type; `boolean` — a JSON boolean; `json` — the sub-value as JSON.
+   */
+  kind: "text" | "boolean" | "json";
+  field: TDbFieldMeta;
+}
 /** Result of comparing desired schema against existing database columns. */
 interface TColumnDiff {
   added: TDbFieldMeta[];
@@ -4573,4 +4683,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbInsertResult as $, DbSpace as $t, TColumnDiff as A, TRelationFilterJunction as An, TReferencingForeignKey as At, TDbDefaultFn as B, TDbEncryptionOptions as Bn, TWriteOptions as Bt, NavPropsOf$1 as C, AtscriptDbReadable as Cn, TIdDescriptor as Ct, PrimaryKeyOf$1 as D, REL_FILTER_MAX_NODES as Dn, TMetaResponse as Dt, OwnPropsOf$1 as E, REL_FILTER_MAX_DEPTH as En, TInsertOptions as Et, TDbActionLevel as F, forEachResolvedRelation as Fn, TTableOptionDiff as Ft, TDbIndex as G, TGenericLogger as Gn, WithRelation$1 as Gt, TDbDeleteResult as H, FieldMappingStrategy as Hn, TypedWithRelation as Ht, TDbActionProcessor as I, hasRelationOp as In, TTableResolver as It, TDbInsertIgnoreOptions as J, TRowOrderKey as Jn, isGeoPointType as Jt, TDbIndexField as K, TExprAggregate as Kn, TableMetadata as Kt, TDbActionTargetSummary as L, isResolvedRelationFilter as Ln, TTouchManyOptions as Lt, TCrudPermissions as M, TRelationStaticFilter as Mn, TRowResolveOptions as Mt, TDbActionInfo as N, andFilters as Nn, TSearchIndexInfo as Nt, TCascadeResolver as O, ResolvedRelationFilter as On, TMetadataOverrides as Ot, TDbActionIntent as P, containsRelationFilter as Pn, TSyncColumnResult as Pt, TDbInsertManyResult as Q, TViewCapability as Qt, TDbAvailableActions as R, relationStaticFilter as Rn, TValueFormatterPair as Rt, FlatOf$1 as S, TCascadePin as Sn, TFkLookupTarget as St, NullsPlacement$1 as T, resolveDesignType as Tn, TIdentification as Tt, TDbFieldMeta as U, TReadControls as Un, Uniquery$1 as Ut, TDbDefaultValue as V, DocumentFieldMapper as Vn, TWriteTableResolver as Vt, TDbForeignKey as W, NoopLogger as Wn, UniqueryControls$1 as Wt, TDbInsertIgnoreSlot as X, ALL_VIEW_CAPABILITIES as Xt, TDbInsertIgnoreResult as Y, UniquSelect as Yn, ALL_BUCKET_UNITS as Yt, TDbInsertManyIgnoreResult as Z, BaseDbAdapter as Zt, DbPatch as _, isFieldRef as _n, TExistingColumn as _t, isJsonValueField as a, isViewType as an, TDbStorageType as at, FieldOpsFor as b, IntegrityStrategy as bn, TFieldMeta as bt, resolveCalendarBuckets as c, AtscriptExprNode$1 as cn, TDbWriteAction as ct, AggregateFn$1 as d, AtscriptQueryFieldRef$1 as dn, TDbWriteGuard as dt, TAdapterFactory as en, TDbObjectKind as et, AggregateQuery$1 as f, AtscriptQueryNode$1 as fn, TDbWriteGuardContext as ft, DbControls as g, evaluateExpr as gn, TEnsureTableOptions as gt, AtscriptDbWritable as h, TViewPlan as hn, TDerivedColumn as ht, isBucketableField as i, isAtscriptDbView as in, TDbRemoveGuardContext as it, TCrudOp as j, TRelationFilterTable as jn, TRelationInfo as jt, TCascadeTarget as k, TRelGuardState as kn, TPrimaryKeyChange as kt, AggregateControls as l, AtscriptOrderItem as ln, TDbWriteCheck as lt, AtscriptDbTableLike as m, TViewJoin as mn, TDerivedChangeReason as mt, TComputedSelect as n, AtscriptDbView as nn, TDbRelation as nt, jsonValueAncestor as o, TViewReadPlan as on, TDbUpdateOptions as ot, AggregateResult as p, AtscriptRef as pn, TDeleteOptions as pt, TDbIndexType as q, TFirstLast as qn, isGeoIndexableType as qt, TResolvedBucket as r, TViewColumnMapping as rn, TDbRemoveGuard as rt, normalizeComputedSelect as s, aliasTargetOf as sn, TDbUpdateResult as st, TBucketFieldSource as t, TDbSpaceOptions as tn, TDbReferentialAction as tt, AggregateExpr$1 as u, AtscriptQueryComparison as un, TDbWriteCheckContext as ut, DbQuery as v, translateQueryTree as vn, TExistingForeignKey as vt, NullableOptional as w, DbResponse as wn, TIdResolveOptions as wt, FilterExpr$1 as x, NativeIntegrity as xn, TFkLookupResolver as xt, DbRow as y, AtscriptDbTable as yn, TExistingTableOption as yt, TDbCollation as z, DbEncryption as zn, TViewJsonType as zt };
+export { TDbInsertResult as $, BaseDbAdapter as $t, TColumnDiff as A, ResolvedRelationFilter as An, TPrimaryKeyChange as At, TDbDefaultFn as B, relationStaticFilter as Bn, TViewJsonType as Bt, NavPropsOf$1 as C, NativeIntegrity as Cn, TIdDescriptor as Ct, PrimaryKeyOf$1 as D, resolveDesignType as Dn, TJsonCopyTarget as Dt, OwnPropsOf$1 as E, DbResponse as En, TInsertOptions as Et, TDbActionLevel as F, andFilters as Fn, TSyncColumnResult as Ft, TDbIndex as G, TReadControls as Gn, UniqueryControls$1 as Gt, TDbDeleteResult as H, TDbEncryptionOptions as Hn, TWriteTableResolver as Ht, TDbActionProcessor as I, containsRelationFilter as In, TTableOptionDiff as It, TDbInsertIgnoreOptions as J, TExprAggregate as Jn, isGeoIndexableType as Jt, TDbIndexField as K, NoopLogger as Kn, WithRelation$1 as Kt, TDbActionTargetSummary as L, forEachResolvedRelation as Ln, TTableResolver as Lt, TCrudPermissions as M, TRelationFilterJunction as Mn, TRelationInfo as Mt, TDbActionInfo as N, TRelationFilterTable as Nn, TRowResolveOptions as Nt, TCascadeResolver as O, REL_FILTER_MAX_DEPTH as On, TMetaResponse as Ot, TDbActionIntent as P, TRelationStaticFilter as Pn, TSearchIndexInfo as Pt, TDbInsertManyResult as Q, ALL_VIEW_CAPABILITIES as Qt, TDbAvailableActions as R, hasRelationOp as Rn, TTouchManyOptions as Rt, FlatOf$1 as S, IntegrityStrategy as Sn, TFkLookupTarget as St, NullsPlacement$1 as T, AtscriptDbReadable as Tn, TIdentification as Tt, TDbFieldMeta as U, DocumentFieldMapper as Un, TypedWithRelation as Ut, TDbDefaultValue as V, DbEncryption as Vn, TWriteOptions as Vt, TDbForeignKey as W, FieldMappingStrategy as Wn, Uniquery$1 as Wt, TDbInsertIgnoreSlot as X, TRowOrderKey as Xn, TPathPresence as Xt, TDbInsertIgnoreResult as Y, TFirstLast as Yn, isGeoPointType as Yt, TDbInsertManyIgnoreResult as Z, UniquSelect as Zn, ALL_BUCKET_UNITS as Zt, DbPatch as _, TViewPlan as _n, TExistingColumn as _t, isJsonValueField as a, TViewColumnMapping as an, TDbStorageType as at, FieldOpsFor as b, translateQueryTree as bn, TFieldMeta as bt, resolveCalendarBuckets as c, TViewReadPlan as cn, TDbWriteAction as ct, AggregateFn$1 as d, AtscriptOrderItem as dn, TDbWriteGuard as dt, TViewCapability as en, TDbObjectKind as et, AggregateQuery$1 as f, AtscriptQueryComparison as fn, TDbWriteGuardContext as ft, DbControls as g, TViewJoin as gn, TEnsureTableOptions as gt, AtscriptDbWritable as h, AtscriptRef as hn, TDerivedColumn as ht, isBucketableField as i, AtscriptDbView as in, TDbRemoveGuardContext as it, TCrudOp as j, TRelGuardState as jn, TReferencingForeignKey as jt, TCascadeTarget as k, REL_FILTER_MAX_NODES as kn, TMetadataOverrides as kt, AggregateControls as l, aliasTargetOf as ln, TDbWriteCheck as lt, AtscriptDbTableLike as m, AtscriptQueryNode$1 as mn, TDerivedChangeReason as mt, TComputedSelect as n, TAdapterFactory as nn, TDbRelation as nt, jsonValueAncestor as o, isAtscriptDbView as on, TDbUpdateOptions as ot, AggregateResult as p, AtscriptQueryFieldRef$1 as pn, TDeleteOptions as pt, TDbIndexType as q, TGenericLogger as qn, TableMetadata as qt, TResolvedBucket as r, TDbSpaceOptions as rn, TDbRemoveGuard as rt, normalizeComputedSelect as s, isViewType as sn, TDbUpdateResult as st, TBucketFieldSource as t, DbSpace as tn, TDbReferentialAction as tt, AggregateExpr$1 as u, AtscriptExprNode$1 as un, TDbWriteCheckContext as ut, DbQuery as v, evaluateExpr as vn, TExistingForeignKey as vt, NullableOptional as w, TCascadePin as wn, TIdResolveOptions as wt, FilterExpr$1 as x, AtscriptDbTable as xn, TFkLookupResolver as xt, DbRow as y, isFieldRef as yn, TExistingTableOption as yt, TDbCollation as z, isResolvedRelationFilter as zn, TValueFormatterPair as zt };