@rvoh/dream 2.34.0 → 2.36.0

package/dist/types/src/dream-app/index.d.ts

@@ -238,9 +238,43 @@ export default class DreamApp {
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
     set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : ApplyOpt extends 'sortableScopeLockTimeout' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
-    on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : never): void;
+    /**
+     * Registers a callback for an app-level event. Callbacks for the same
+     * event run in the order they were registered.
+     *
+     * - `'db:log'`: called with a {@link KyselyLogEvent} each time a query on a
+     *   Dream database connection completes or fails.
+     * - `'repl:start'`: called, and awaited, with the console's REPL context
+     *   when the Dream console starts.
+     * - `'encryption:legacy-key-used'`: called with an
+     *   {@link EncryptionLegacyKeyUsedEvent} when reading an `@deco.Encrypted`
+     *   property needed the `legacy` column encryption key, not `current`, to
+     *   open the stored value. Use it during a key rotation to find rows still
+     *   encrypted with the old key. The property decrypts on every read, so a
+     *   record whose value is still under the old key fires the event each time
+     *   the property is read. A row nobody reads never fires it, so a quiet
+     *   event does not prove that `legacy` is safe to drop;
+     *   `Model.reencryptEncryptedColumns()` rewrites every row instead. Neither
+     *   it nor the migration helpers fire the event. The callback runs
+     *   synchronously inside the property read, and an error it throws
+     *   propagates from that read. Reading the same property of the same
+     *   record inside the callback returns its value without firing the event
+     *   again, so a callback can read the property and assign the value back,
+     *   which re-encrypts it under `current` for the record's next save. That
+     *   holds only while the callback runs synchronously: a callback that
+     *   reads the property after an `await` fires the event again from that
+     *   read, so an `async` callback should read the property before its
+     *   first `await`.
+     *
+     * ```ts
+     * dreamApp.on('encryption:legacy-key-used', ({ dream, property }) => {
+     *   console.warn(`${dream.constructor.name} ${dream.primaryKeyValue()} ${property} still uses the legacy key`)
+     * })
+     * ```
+     */
+    on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : T extends 'encryption:legacy-key-used' ? (event: EncryptionLegacyKeyUsedEvent) => void : never): void;
 }
-export type DreamHookEventType = 'db:log' | 'repl:start';
+export type DreamHookEventType = 'db:log' | 'repl:start' | 'encryption:legacy-key-used';
 export interface DreamAppOpts {
     projectRoot: string;
     primaryKeyType: LegacyCompatiblePrimaryKeyType;
@@ -373,6 +407,26 @@ interface SegmentedEncryptionOptions {
 export interface DreamAppSpecialHooks {
     dbLog: ((event: KyselyLogEvent) => void)[];
     replStart: ((context: Context) => void | Promise<void>)[];
+    encryptionLegacyKeyUsed: ((event: EncryptionLegacyKeyUsedEvent) => void)[];
+}
+/**
+ * Passed to `dreamApp.on('encryption:legacy-key-used', ...)` callbacks.
+ */
+export interface EncryptionLegacyKeyUsedEvent {
+    /**
+     * The record whose `@deco.Encrypted` property was read. Its class and
+     * `primaryKeyValue()` identify the row; a record not yet saved has no
+     * primary key.
+     */
+    dream: Dream;
+    /**
+     * The `@deco.Encrypted` property that was read, e.g. `'phone'`.
+     */
+    property: string;
+    /**
+     * The column holding the property's ciphertext, e.g. `'encryptedPhone'`.
+     */
+    encryptedColumnName: string;
 }
 export interface DreamAppInitOptions {
     bypassDreamIntegrityChecks?: boolean;

package/dist/types/src/encrypt/InternalEncrypt.d.ts

@@ -1,6 +1,25 @@
+import { DecryptCallbacks } from './index.js';
 export default class InternalEncrypt {
     static encryptColumn(data: any): string | null;
-    static decryptColumn(data: any): unknown;
+    /**
+     * Decrypts `data` with the column keys, current then legacy.
+     * `onLegacyKeyUsed` is passed to `Encrypt.decrypt`, so it is called only
+     * when the legacy key opened the value.
+     */
+    static decryptColumn(data: any, callbacks?: DecryptCallbacks): unknown;
+    /**
+     * Encrypts `data`, a column's ciphertext, again with the current column key
+     * (see `Encrypt.reencrypt`), opening it with the current key or, failing
+     * that, the legacy one. It does not call `onLegacyKeyUsed`.
+     */
+    static reencryptColumn(data: any): string | null;
+    /**
+     * Whether `data` is ciphertext that the column keys (current, then legacy)
+     * open to a value `decryptColumn` returns. A missing column encryption
+     * config or key still throws, since that is a configuration error rather
+     * than a property of `data`.
+     */
+    static isDecryptableColumnCiphertext(data: string): boolean;
     private static doEncryption;
     private static doDecryption;
 }

package/dist/types/src/encrypt/defaultEncryptedColumnName.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The column that holds an `@deco.Encrypted` property's ciphertext when the
+ * decorator is not given one: the property's name, pascalized and prefixed
+ * with `encrypted`. `secretPhone`, or `secret_phone`, gives
+ * `encryptedSecretPhone`, which is the `encrypted_secret_phone` column.
+ */
+export default function defaultEncryptedColumnName(propertyName: string): string;

package/dist/types/src/encrypt/index.d.ts

@@ -19,12 +19,50 @@ export default class Encrypt {
      *
      * `MissingEncryptionKey` propagates from either form when a key is missing.
      *
+     * **`onLegacyKeyUsed`** (optional fourth argument): during a key rotation,
+     * tells you which values still need the legacy key. It is called with no
+     * arguments, synchronously, before a three-arg call returns a value that
+     * the legacy key opened. It is not called when the current key opens the
+     * value, when decryption throws, or in the two-arg form. An error it
+     * throws propagates from `decrypt` as is.
+     *
+     * ```ts
+     * const value = Encrypt.decrypt<string>(
+     *   encrypted,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey },
+     *   { onLegacyKeyUsed: () => console.warn('this value is still encrypted with the old key') }
+     * )
+     * ```
+     *
+     * @throws MissingEncryptionKey
+     * @throws DecryptionError
+     * @throws DecryptionParseError
+     * @throws DecryptionRotationError
+     */
+    static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions, { onLegacyKeyUsed }?: DecryptCallbacks): RetType | null;
+    /**
+     * Opens `encrypted` as {@link Encrypt.decrypt} does, with `currentOpts` and,
+     * when they do not open it, `legacyOpts`, and encrypts the value again with
+     * `currentOpts`, so that reading it no longer needs the legacy key. Use it
+     * during a key rotation for a value stored outside an `@deco.Encrypted`
+     * column, such as a cookie; `Model.reencryptEncryptedColumns()` does this
+     * for every value of a model's encrypted properties.
+     *
+     * ```ts
+     * const rewritten = Encrypt.reencrypt(
+     *   storedValue,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey }
+     * )
+     * ```
+     *
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
      * @throws DecryptionRotationError
      */
-    static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions): RetType | null;
+    static reencrypt(encrypted: string, currentOpts: EncryptOptions, legacyOpts?: DecryptOptions): string;
     private static attemptDecryptionWithLegacyKeys;
     /**
      * Generates a base64-encoded random key suitable for the given algorithm.
@@ -42,11 +80,26 @@ export default class Encrypt {
      *    to decrypt via `legacy` fallback.
      * 4. For cookies, wait at least the cookie `maxAge` so all in-flight
      *    cookies have either expired or been re-issued under the new key. For
-     *    `@Encrypted` columns, re-encrypt every existing row under the new
-     *    key (read each row and write it back; the setter re-encrypts with
-     *    `current`).
+     *    `@Encrypted` columns, re-encrypt every existing row under the new key
+     *    by calling `reencryptEncryptedColumns()` on each model that has
+     *    encrypted properties (`await User.reencryptEncryptedColumns()`), in
+     *    each environment, from a console or a script rather than a migration.
+     *    Run it only once every server in that environment runs with the new
+     *    `current`: a server still on the old `current` keeps writing old-key
+     *    values that its single pass over the table can miss. Writing old-key
+     *    ciphertext straight into a backing column (`setAttribute`,
+     *    `setAttributes` or `updateAttributes` given the backing column) after
+     *    it has run also puts an old-key value back. For any other value
+     *    encrypted with these keys, {@link Encrypt.reencrypt} rewrites it.
      * 5. Drop `legacy` from config and deploy again.
      *
+     * To see which values still need the old key while `legacy` is
+     * configured, register `dreamApp.on('encryption:legacy-key-used', ...)`,
+     * which fires each time reading an `@Encrypted` property needed `legacy`
+     * to open the value, or pass `onLegacyKeyUsed` to {@link Encrypt.decrypt}
+     * for values you decrypt yourself. A value nobody reads never fires
+     * either, so silence alone does not show that `legacy` is safe to drop.
+     *
      * ## When to rotate
      *
      * - On a scheduled cadence (90–180 days is a reasonable policy default).
@@ -58,8 +111,15 @@ export default class Encrypt {
      * - For cookies: at least the cookie `maxAge`, so in-flight sessions are
      *   not forced to re-authenticate.
      * - For `@Encrypted` columns: until every existing row has been
-     *   re-encrypted under the new key. Dropping `legacy` early will cause
-     *   `DecryptionRotationError` on any not-yet-rewritten row.
+     *   re-encrypted under the new key. Once `legacy` is dropped, reading the
+     *   `@Encrypted` property of a row that is still under the old key throws
+     *   `DecryptionError`, the same error a tampered or corrupted value
+     *   throws, so the error class alone cannot show that `legacy` was
+     *   dropped too early. `DecryptionRotationError` is thrown only while
+     *   `legacy` is configured and neither key opens the value. Neither class
+     *   extends the other, so code that catches `DecryptionRotationError`
+     *   during a rotation must also catch `DecryptionError` to handle such a
+     *   read once `legacy` is dropped.
      */
     static generateKey(algorithm: EncryptAlgorithm): string;
     static validateKey(base64EncodedKey: string, algorithm: EncryptAlgorithm): boolean;
@@ -68,6 +128,15 @@ export interface EncryptOptions extends BaseOptions {
 }
 export interface DecryptOptions extends BaseOptions {
 }
+export interface DecryptCallbacks {
+    /**
+     * Called with no arguments, synchronously, before a three-arg
+     * {@link Encrypt.decrypt} returns a value that the legacy key opened.
+     * Never called when the current key opens the value, when decryption
+     * throws, or in the two-arg form.
+     */
+    onLegacyKeyUsed?: () => void;
+}
 interface BaseOptions {
     algorithm: EncryptAlgorithm;
     key: string;

package/dist/types/src/errors/associations/UnrecognizedAssociationConditionKeys.d.ts

@@ -0,0 +1,8 @@
+export default class UnrecognizedAssociationConditionKeys extends Error {
+    private associationName;
+    private unrecognizedKeys;
+    private acceptedKeys;
+    private methodName;
+    constructor(associationName: string, unrecognizedKeys: string[], acceptedKeys: readonly string[], methodName: string | null);
+    get message(): string;
+}

package/dist/types/src/helpers/Env.d.ts

@@ -18,12 +18,40 @@ export default class Env<T extends {
     } | undefined, ReturnType extends OptionalConfig extends undefined ? number : OptionalConfig extends {
         optional: boolean;
     } ? OptionalConfig['optional'] extends true ? number | undefined : number : number>(env: IntegerEnvs, opts?: OptionalConfig): ReturnType;
+    /**
+     * Reads a boolean environment variable. Only the exact string `"1"` is
+     * true. Every other value is false, including `"true"`, `"TRUE"`, `"yes"`
+     * and `""`, and so is an unset variable.
+     *
+     * ```ts
+     * // FEATURE_FLAG=1
+     * AppEnv.boolean('FEATURE_FLAG') // true
+     *
+     * // FEATURE_FLAG=true
+     * AppEnv.boolean('FEATURE_FLAG') // false
+     * ```
+     *
+     * @param env - the name of the environment variable
+     * @returns `true` when the variable is exactly `"1"`, otherwise `false`
+     */
     boolean(env: BooleanEnvs): boolean;
     setString(env: StringEnvs, val: string | undefined): void;
     unsetString(env: StringEnvs): void;
     setInteger(env: IntegerEnvs, val: number | undefined): void;
     unsetInteger(env: IntegerEnvs): void;
+    /**
+     * Sets a boolean environment variable to `"1"`, the only value
+     * {@link Env.boolean} reads as true.
+     *
+     * @param env - the name of the environment variable
+     */
     setBoolean(env: BooleanEnvs): void;
+    /**
+     * Deletes a boolean environment variable. {@link Env.boolean} reads an
+     * unset variable as false, since only the exact string `"1"` is true.
+     *
+     * @param env - the name of the environment variable
+     */
     unsetBoolean(env: BooleanEnvs): void;
     protected required(variable: string): string;
     protected optional(variable: string): string | undefined;

package/dist/types/src/package-exports/openapi.d.ts

@@ -1,2 +1,2 @@
 export { openapiPrimitiveTypes, openapiShorthandPrimitiveTypes } from '../dream/constants.js';
-export { type CommonOpenapiSchemaObjectFields, type OpenapiAllTypes, type OpenapiDescription, type OpenapiFormats, type OpenapiNumberFormats, type OpenapiPrimitiveBaseTypes, type OpenapiPrimitiveTypes, type OpenapiSchemaArray, type OpenapiSchemaArrayShorthand, type OpenapiSchemaBase, type OpenapiSchemaBody, type OpenapiSchemaBodyShorthand, type OpenapiSchemaCommonFields, type OpenapiSchemaExpressionAllOf, type OpenapiSchemaExpressionAnyOf, type OpenapiSchemaExpressionOneOf, type OpenapiSchemaExpressionRef, type OpenapiSchemaExpressionRefSchemaShorthand, type OpenapiSchemaInteger, type OpenapiSchemaNull, type OpenapiSchemaNumber, type OpenapiSchemaObject, type OpenapiSchemaObjectAllOf, type OpenapiSchemaObjectAllOfShorthand, type OpenapiSchemaObjectAnyOf, type OpenapiSchemaObjectAnyOfShorthand, type OpenapiSchemaObjectBase, type OpenapiSchemaObjectBaseShorthand, type OpenapiSchemaObjectOneOf, type OpenapiSchemaObjectOneOfShorthand, type OpenapiSchemaObjectShorthand, type OpenapiSchemaPrimitiveGeneric, type OpenapiSchemaProperties, type OpenapiSchemaPropertiesShorthand, type OpenapiSchemaShorthandExpressionAllOf, type OpenapiSchemaShorthandExpressionAnyOf, type OpenapiSchemaShorthandExpressionOneOf, type OpenapiSchemaShorthandExpressionSerializableRef, type OpenapiSchemaShorthandExpressionSerializerRef, type OpenapiSchemaShorthandPrimitiveGeneric, type OpenapiSchemaString, type OpenapiShorthandAllTypes, type OpenapiShorthandPrimitiveBaseTypes, type OpenapiShorthandPrimitiveTypes, type OpenapiTypeField, type OpenapiTypeFieldObject, } from '../types/openapi.js';
+export { type CommonOpenapiSchemaObjectFields, type OpenapiAllTypes, type OpenapiDescription, type OpenapiFormats, type OpenapiNumberFormats, type OpenapiPrimitiveBaseTypes, type OpenapiPrimitiveTypes, type OpenapiSchemaArray, type OpenapiSchemaArrayShorthand, type OpenapiSchemaBase, type OpenapiSchemaBody, type OpenapiSchemaBodyShorthand, type OpenapiSchemaCombinatorFields, type OpenapiSchemaCommonFields, type OpenapiSchemaExpressionAllOf, type OpenapiSchemaExpressionAnyOf, type OpenapiSchemaExpressionOneOf, type OpenapiSchemaExpressionRef, type OpenapiSchemaExpressionRefSchemaShorthand, type OpenapiSchemaInteger, type OpenapiSchemaNull, type OpenapiSchemaNumber, type OpenapiSchemaObject, type OpenapiSchemaObjectAllOf, type OpenapiSchemaObjectAllOfShorthand, type OpenapiSchemaObjectBase, type OpenapiSchemaObjectBaseShorthand, type OpenapiSchemaObjectShorthand, type OpenapiSchemaPrimitiveGeneric, type OpenapiSchemaProperties, type OpenapiSchemaPropertiesShorthand, type OpenapiSchemaShorthandExpressionAllOf, type OpenapiSchemaShorthandExpressionAnyOf, type OpenapiSchemaShorthandExpressionOneOf, type OpenapiSchemaShorthandExpressionSerializableRef, type OpenapiSchemaShorthandExpressionSerializerRef, type OpenapiSchemaShorthandPrimitiveGeneric, type OpenapiSchemaString, type OpenapiShorthandAllTypes, type OpenapiShorthandPrimitiveBaseTypes, type OpenapiShorthandPrimitiveTypes, type OpenapiTypeField, type OpenapiTypeFieldObject, } from '../types/openapi.js';

package/dist/types/src/package-exports/types.d.ts

@@ -1,5 +1,5 @@
 export { type DecoratorContext } from '../decorators/DecoratorContextType.js';
-export { type EncryptAlgorithm, type EncryptOptions } from '../encrypt/index.js';
+export { type DecryptCallbacks, type EncryptAlgorithm, type EncryptOptions } from '../encrypt/index.js';
 export { type RoundingPrecision } from '../helpers/round.js';
 export { type Camelized, type Hyphenized, type Pascalized, type Snakeified } from '../helpers/stringCasing.js';
 export { type SerializerRendererOpts } from '../serializer/SerializerRenderer.js';
@@ -14,5 +14,5 @@ export { type DurationObject, type DurationUnit, type WeekdayName } from '../typ
 export { type DreamAssociationMetadata, type DreamAttributes, type DreamClassAssociationAndStatement, type DreamClassColumn, type DreamColumn, type DreamColumnNames, type DreamOrViewModelClassSerializerKey, type DreamOrViewModelSerializerKey, type DreamParamSafeAttributes, type DreamParamSafeColumnNames, type DreamSerializable, type DreamSerializableArray, type DreamSerializerKey, type DreamSerializers, type DreamVirtualColumns, type UpdateableAssociationProperties, type UpdateableProperties, type ViewModel, type ViewModelClass, } from '../types/dream.js';
 export { type DreamModelSerializerType, type InternalAnyTypedSerializerRendersMany, type InternalAnyTypedSerializerRendersOne, type SerializerCasing, type SimpleObjectSerializerType, } from '../types/serializer.js';
 export { type ValidationType } from '../types/validation.js';
-export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, type DreamDbConfig, } from '../dream-app/index.js';
+export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, type DreamDbConfig, type EncryptionLegacyKeyUsedEvent, } from '../dream-app/index.js';
 export { type WhereStatementForDream, type WhereStatementForDreamClass, } from '../types/associations/shared.js';

package/dist/types/src/serializer/SerializerRenderer.d.ts

@@ -10,5 +10,18 @@ export default class SerializerRenderer {
     private renderOpts;
     constructor(serializerBuilder: DreamSerializerBuilder<any, any> | ObjectSerializerBuilder<any, any> | null | undefined, passthroughData?: object, { casing }?: SerializerRendererOpts);
     render(): Record<string, any> | null;
+    /**
+     * The keys a flattened `rendersOne` adds to the parent's payload when its associated object is
+     * null: each key any of `serializers` declares, set to `null`. There are several serializers when
+     * the association is a polymorphic BelongsTo, one for each target class, or when the associated
+     * class is an STI base, one for each child, and their keys are unioned.
+     *
+     * Each serializer is built with `undefined` data to read its declarations, as Psychic's OpenAPI
+     * generation and `preloadFor` build it, and nothing is rendered: no attribute callback runs and
+     * no association of the missing object is read. A flattened `rendersOne` it declares adds its
+     * own serializers' keys the same way. A flattened `customAttribute` adds none, since only its
+     * callback knows its keys.
+     */
+    private nullFlattenedAttributes;
     private setCase;
 }

package/dist/types/src/serializer/builders/DreamSerializerBuilder.d.ts

@@ -1,6 +1,6 @@
 import Dream from '../../Dream.js';
 import { DreamOrViewModelSerializerKey, DreamVirtualColumns, NonJsonDreamColumnNames, ViewModel, ViewModelClass } from '../../types/dream.js';
-import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
+import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, CustomAttributeOptions, DelegatedAttributeOptionsArgs, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
 import { SerializerRendererOpts } from '../SerializerRenderer.js';
 export type DreamPropertiesToExclude = keyof Dream | 'serializers';
 export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dream, MaybeNullDataType extends Dream | null, PassthroughDataType = any, DataType extends Exclude<MaybeNullDataType, null> = Exclude<MaybeNullDataType, null>> {
@@ -54,7 +54,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      */
     attribute(name: NonJsonDreamColumnNames<DataType> & keyof DataType & 'type', options?: AutomaticSerializerAttributeOptionsForType): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute(name: DreamVirtualColumns<DataType>[number], options?: SerializerAttributeOptionsForVirtualColumn): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
-    attribute<MaybeAttributeName extends NonJsonDreamColumnNames<DataType> | (keyof DataType & string), AttributeName extends MaybeAttributeName extends NonJsonDreamColumnNames<DataType> ? never : Exclude<keyof DataType, DreamPropertiesToExclude> & string>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
+    attribute<AttributeName extends Exclude<keyof DataType & string, NonJsonDreamColumnNames<DataType> | DreamPropertiesToExclude>>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute<AttributeName extends NonJsonDreamColumnNames<DataType> & keyof DataType & string>(name: AttributeName, options?: AutomaticSerializerAttributeOptions): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     /**
      * Includes an attribute from a nested object in the serialized output.
@@ -65,9 +65,10 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   2. `required: false` → omits the key entirely from the rendered output
      *   3. otherwise → renders `null`
      *
-     * When the target is a Dream model, OpenAPI types may be automatically inferred
-     * for standard database columns. For json/jsonb columns or non-Dream targets,
-     * the `openapi` option is required.
+     * When the target is a Dream model, a non-json column's OpenAPI shape is inferred
+     * from the column, so its `openapi` option takes only a `description`. json/jsonb
+     * columns and non-Dream targets have no shape to infer, so they require a full
+     * `openapi` shape.
      *
      * `optional` and `required` are not aliases — they encode different things and can
      * be used together:
@@ -91,12 +92,14 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *     a discriminator string when the association is actually missing produces a response
      *     indistinguishable from "association present with that type," which is misleading)
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
-     *     columns, optional for standard Dream columns (where types are inferred)
-     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
-     *     key is still rendered (as `null`). For Dream models, this is auto-inferred
-     *     from optional BelongsTo associations. Use this when delegating through a
-     *     HasOne or other nullable association.
+     *     columns. On a non-json Dream column, whose shape is inferred, it takes only a
+     *     `description` (and, on the STI `type` column, a `type: 'string'` and `enum`)
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema:
+     *     Psychic adds `null` to the rendered schema (e.g., `type: 'string'` becomes
+     *     `type: ['string', 'null']`, and a `$ref` becomes `anyOf: [{ $ref }, { type: 'null' }]`).
+     *     OpenAPI-only — the key is still rendered (as `null`). For Dream models, this is
+     *     auto-inferred from optional BelongsTo associations. Use this when delegating
+     *     through a HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape (not available when delegating
      *     to a `'type'` STI discriminator column, which is always a string enum)
@@ -108,52 +111,45 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * @example
      * ```typescript
      * // Delegate to a Dream association's column (type inferred)
-     * .delegatedAttribute('currentLocalizedText', 'title', { openapi: 'string' })
+     * .delegatedAttribute('currentLocalizedText', 'title')
      *
      * // With default value for null target or attribute
-     * .delegatedAttribute('user', 'displayName', {
-     *   openapi: { type: 'string' },
-     *   default: 'Unknown User'
-     * })
+     * .delegatedAttribute('user', 'displayName', { default: 'Unknown User' })
      *
      * // Rename the output key
-     * .delegatedAttribute('profile', 'avatarUrl', {
-     *   openapi: 'string',
-     *   as: 'avatar'
+     * .delegatedAttribute('profile', 'avatarUrl', { as: 'avatar' })
+     *
+     * // A json/jsonb column has no shape to infer, so it declares one
+     * .delegatedAttribute('user', 'preferences', {
+     *   openapi: { type: 'object', properties: { theme: 'string' } }
      * })
      * ```
      */
-    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, options?: AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType & {
-        optional?: boolean;
-        required?: false;
-    } : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn & {
-        optional?: boolean;
-    } : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? (AutomaticSerializerAttributeOptions & {
-        optional?: boolean;
-    }) | (NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    }) : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    } : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    }): this;
+    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, ...options: DelegatedAttributeOptionsArgs<AssociatedModelType, TargetAttributeName>): this;
     /**
      * Includes a computed value in the serialized output.
      *
      * Executes a callback function to generate a custom attribute value.
      * The `openapi` option is always required since the return type cannot be inferred.
      *
+     * The callback's return value renders as is, so any fallback or rounding belongs in the
+     * callback.
+     *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
      * @param options - Configuration options:
      *   - `openapi` - (required) OpenAPI schema definition for the computed value
-     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
-     *   - `default` - Value to use when the callback returns undefined
      *   - `flatten` - When `true`, spreads the returned object's properties directly into the
-     *     parent serialized output instead of nesting them under `name`; the `openapi` option
-     *     should then define each flattened property individually
-     *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
-     *     during rendering; does not affect the OpenAPI shape
+     *     parent serialized output instead of nesting them under `name`. The `openapi` option
+     *     then describes the whole returned object, not each property, because Psychic adds it
+     *     to the parent's schema as an `allOf` branch: either an object schema with full
+     *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
+     *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
+     *     what that serializer renders. A serializer ref with `many: true` does not type-check
+     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
+     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     another attribute takes the value of whichever is declared later; under the `allOf`,
+     *     that value must match both schemas
      *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
      *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
@@ -166,25 +162,21 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   { openapi: { type: 'string' } }
      * )
      *
-     * // Flattened object properties
+     * // Flattened object properties: `openapi` describes the whole returned object
      * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
      *   flatten: true,
      *   openapi: {
-     *     lat: { type: 'number' },
-     *     lng: { type: 'number' }
+     *     type: 'object',
+     *     required: ['lat', 'lng'],
+     *     properties: {
+     *       lat: { type: 'number' },
+     *       lng: { type: 'number' }
+     *     }
      *   }
      * })
-     *
-     * // With decimal precision
-     * .customAttribute('averageRating', () => calculateAverage(ratings), {
-     *   openapi: 'decimal',
-     *   precision: 2
-     * })
      * ```
      */
-    customAttribute(name: string, fn: () => unknown, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        flatten?: boolean;
-    }): this;
+    customAttribute(name: string, fn: () => unknown, options: CustomAttributeOptions): this;
     /**
      * Includes a single associated object in the serialized output.
      *
@@ -195,9 +187,18 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * @param options - Configuration options:
      *   - `as` - Rename the association key in the serialized output
      *   - `flatten` - When `true`, spreads the rendered association's attributes directly into
-     *     the parent serialized output instead of nesting them under `name`. Be aware of
-     *     attribute shadowing: if the parent and flattened association share attribute names
-     *     (e.g., `id`), the flattened association's values overwrite the parent's
+     *     the parent serialized output instead of nesting them under `name`. Attributes render in
+     *     declaration order, so when the parent and the association share a key (e.g., `id`),
+     *     whichever is declared later wins: the association's value replaces an attribute declared
+     *     before the `rendersOne`, and an attribute declared after it replaces the association's.
+     *     When the association is `null`, every key its serializer declares renders as `null`
+     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
+     *     declares, and for an association to an STI base, every key the serializer of any of its
+     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
+     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
+     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
+     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
+     *     schemas, whichever declaration wins
      *   - `optional` - When `true`, allows the association to be null/missing without causing
      *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
      *     `rendersOne` expects the association to be present (mirroring the `optional` option on
@@ -251,7 +252,10 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
         as?: string;
         /**
          * If `true`, the rendered association's attributes are merged directly into
-         * the parent object instead of being nested under the association key.
+         * the parent object instead of being nested under the association key. A key
+         * the parent shares with the association takes the value of whichever is
+         * declared later, and when the association is `null`, every key its serializer
+         * declares renders as `null`. See the `flatten` option of `rendersOne`.
          */
         flatten?: boolean;
         /**