@rvoh/dream 2.34.0 → 2.36.0

package/dist/esm/src/encrypt/defaultEncryptedColumnName.js

@@ -0,0 +1,10 @@
+import pascalize from '../helpers/pascalize.js';
+/**
+ * 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) {
+    return `encrypted${pascalize(propertyName)}`;
+}

package/dist/esm/src/encrypt/index.js

@@ -41,14 +41,30 @@ 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(encrypted, { algorithm, key }, legacyOpts) {
+    static decrypt(encrypted, { algorithm, key }, legacyOpts, { onLegacyKeyUsed } = {}) {
         if (legacyOpts)
-            return this.attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts);
+            return this.attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts, onLegacyKeyUsed);
         if (!key)
             throw new MissingEncryptionKey();
         if ([null, undefined].includes(encrypted))
@@ -65,7 +81,31 @@ export default class Encrypt {
             }
         }
     }
-    static attemptDecryptionWithLegacyKeys(encrypted, currentOpts, legacyOpts) {
+    /**
+     * 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 reencrypt(encrypted, currentOpts, legacyOpts) {
+        return this.encrypt(this.decrypt(encrypted, currentOpts, legacyOpts), currentOpts);
+    }
+    static attemptDecryptionWithLegacyKeys(encrypted, currentOpts, legacyOpts, onLegacyKeyUsed) {
         let currentKeyError;
         try {
             return this.decrypt(encrypted, currentOpts);
@@ -75,14 +115,19 @@ export default class Encrypt {
                 throw err;
             currentKeyError = err;
         }
+        let decrypted;
         try {
-            return this.decrypt(encrypted, legacyOpts);
+            decrypted = this.decrypt(encrypted, legacyOpts);
         }
         catch (err) {
             if (!(err instanceof DecryptionError))
                 throw err;
             throw new DecryptionRotationError(currentKeyError, err);
         }
+        // called outside the try above, so an error the callback throws is never
+        // mistaken for the legacy key failing
+        onLegacyKeyUsed?.();
+        return decrypted;
     }
     /**
      * Generates a base64-encoded random key suitable for the given algorithm.
@@ -100,11 +145,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).
@@ -116,8 +176,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) {
         switch (algorithm) {

package/dist/esm/src/errors/DoNotSetEncryptedFieldsDirectly.js

@@ -13,6 +13,10 @@ export default class DoNotSetEncryptedFieldsDirectly extends Error {
 Do not set @Encrypted columns directly. Instead, set their accessors, so that
 those fields can be encrypted by Dream internally.
 
+Writes that bypass setters, such as setAttribute, setAttributes and
+updateAttributes, accept a value for an @Encrypted column only when it is
+ciphertext that decrypts with this app's encryption keys, or null.
+
 Dream class: ${this.dreamClass.sanitizedName}
 Problematic setter: ${this.encryptedColumnName}
 Setter to be used instead: ${this.encryptedProperty}`;

package/dist/esm/src/errors/associations/UnrecognizedAssociationConditionKeys.js

@@ -0,0 +1,25 @@
+export default class UnrecognizedAssociationConditionKeys extends Error {
+    associationName;
+    unrecognizedKeys;
+    acceptedKeys;
+    methodName;
+    constructor(associationName, unrecognizedKeys, acceptedKeys, methodName) {
+        super();
+        this.associationName = associationName;
+        this.unrecognizedKeys = unrecognizedKeys;
+        this.acceptedKeys = acceptedKeys;
+        this.methodName = methodName;
+    }
+    get message() {
+        const source = this.methodName
+            ? `in the object passed to ${this.methodName}('${this.associationName}')`
+            : `in the condition on the "${this.associationName}" association`;
+        return `
+Unrecognized key${this.unrecognizedKeys.length === 1 ? '' : 's'} ${source}: ${this.unrecognizedKeys.join(', ')}
+Accepted keys: ${this.acceptedKeys.join(', ')}
+
+Where-clauses on an association go under \`and\`, \`andNot\` or \`andAny\`, e.g.:
+  { and: { email: 'how@yadoin' } }
+`;
+    }
+}

package/dist/esm/src/helpers/Env.js

@@ -34,6 +34,22 @@ export default class Env {
         const parsedVal = parseInt(val, 10);
         return (parsedVal.toString() === val ? parsedVal : undefined);
     }
+    /**
+     * 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) {
         return this.optional(env) === '1';
     }
@@ -51,9 +67,21 @@ export default class Env {
     unsetInteger(env) {
         delete process.env[env];
     }
+    /**
+     * 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) {
         process.env[env] = '1';
     }
+    /**
+     * 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) {
         delete process.env[env];
     }

package/dist/esm/src/helpers/cli/generateDreamContent.js

@@ -1,5 +1,6 @@
 import pluralize from 'pluralize-esm';
 import serializerGlobalNameFromFullyQualifiedModelName from '../../serializer/helpers/serializerGlobalNameFromFullyQualifiedModelName.js';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import camelize from '../camelize.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import pascalize from '../pascalize.js';
@@ -189,7 +190,7 @@ public ${associationForeignKey}: DreamColumn<${modelClassName}, '${associationNa
     };
 }
 export function createEncryptedAttribute(attributeName, attribute, modelClassName) {
-    const encryptedColumnName = camelize(`encrypted_${attributeName}`);
+    const encryptedColumnName = defaultEncryptedColumnName(attributeName);
     const content = `
 @deco.Encrypted()
 public ${camelize(attributeName)}: DreamColumn<${modelClassName}, '${encryptedColumnName}'>`;

package/dist/esm/src/helpers/cli/generateFactoryContent.js

@@ -46,7 +46,7 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
         switch (safeAttributeType) {
             case 'belongsto': {
                 // When `Model@alias:belongs_to`, the factory property uses the alias;
-                // otherwise it uses the model's last namespace segment (legacy form).
+                // otherwise it uses the model's last namespace segment.
                 const attributeVariable = aliasName ? camelize(aliasName) : camelize(attributeName.split('/').pop());
                 const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
                 const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);

package/dist/esm/src/helpers/cli/generateMigrationContent.js

@@ -4,6 +4,7 @@ import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
 import NoColumnsToAlterMigration from '../../errors/NoColumnsToAlterMigration.js';
 import UnparseableMigrationColumn from '../../errors/UnparseableMigrationColumn.js';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
@@ -141,7 +142,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 columnDefs.push(generateBooleanStr(attributeName, { omitInlineNonNull }));
                 break;
             case 'encrypted':
-                attributeName = `encrypted_${attributeName}`;
+                attributeName = snakeify(defaultEncryptedColumnName(attributeName));
                 columnDefs.push(generateColumnStr(attributeName, 'text', descriptors, {
                     omitInlineNonNull,
                     skipUniqueHeuristic: true,
@@ -183,13 +184,12 @@ export default function generateMigrationContent({ connectionName = 'default', t
     // time rather than generation time. Fail loudly here instead.
     //
     // This guard is scoped to the standalone `g:migration` `-to-`/`-from-` flow
-    // only (`stiChildClassName` is unset there). `g:sti-child` legitimately
-    // calls this function in alter mode with zero `columnsWithTypes` — a
-    // zero-attribute STI child is a documented use case (see `g:sti-child`'s
-    // help example in src/cli/index.ts), and `generateStiMigrationContent`
-    // handles the type-column/check-constraint machinery separately from the
-    // `columnDefs` this check inspects, so an empty `columnDefs` there is
-    // expected, not a sign of a mistyped/unparseable column list.
+    // only (`stiChildClassName` is unset there); STI child migrations skip it.
+    // `g:sti-child` writes no migration for a child declared with no columns
+    // (see `generateDream`), so an STI child migration reaches this point with
+    // an empty `columnDefs` only when none of its declarations produced a
+    // column (e.g. only `has_one`/`has_many` ones), and it then emits the bare
+    // `.alterTable(...).execute()` described above.
     if (altering &&
         columnDefs.length === 0 &&
         table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
@@ -472,7 +472,7 @@ function generateBelongsToStr(connectionName, associationName, { primaryKeyType,
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
     const references = lookupReferencesTable(associationName, originalAssociationName);
     // When the user passed `Model@alias:belongs_to`, the column name comes from
-    // the alias; otherwise it's the model's last segment (existing behavior).
+    // the alias; otherwise it's the model's last segment.
     const columnNameSource = aliasName ? snakeify(aliasName) : associationName.split('/').pop();
     return `.addColumn('${associationNameToForeignKey(columnNameSource)}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
 }

package/dist/esm/src/helpers/cli/generateSerializerContent.js

@@ -40,6 +40,16 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
         ? `import { ${uniq(dreamImports).join(', ')} } from '@rvoh/dream'\n`
         : '';
     const additionalImportsStr = uniq(additionalImports).join('');
+    // An STI base renders the `type` discriminator in its summary serializers,
+    // so each default serializer, and each STI child serializer, inherits it.
+    const rendersStiType = stiBaseSerializer &&
+        columnsWithTypes.some(attr => {
+            const [name, type] = attr.split(':');
+            return name === 'type' && !isAssociationType(type);
+        });
+    const stiTypeAttribute = rendersStiType
+        ? `\n    .attribute('type', { openapi: { type: 'string', enum: [(StiChildClass ?? ${modelClassName}).sanitizedName] } })`
+        : '';
     const buildSerializerPair = (variantSuffix) => {
         const summaryName = variantSerializerClassName(localSerializerBase, variantSuffix, 'summary');
         const defaultName = variantSerializerClassName(localSerializerBase, variantSuffix, 'default');
@@ -50,15 +60,17 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
             ? `${variantSerializerClassName(parentSerializerBase, variantSuffix, 'default')}(${modelClassName}, ${modelSerializerArgs})`
             : `${summaryName}(${stiBaseSerializer ? 'StiChildClass, ' : ''}${modelSerializerArgs})`;
         const summary = `export const ${summaryName} = ${modelSerializerSignature} =>
-  ${summaryExtends}${isSTI ? '' : `\n    .attribute('id')`}`;
+  ${summaryExtends}${isSTI ? '' : `\n    .attribute('id')`}${stiTypeAttribute}`;
         const defaultBody = columnsWithTypes
             .map(attr => {
             const [name, type] = attr.split(':');
             if (name === undefined)
                 return '';
-            if (['belongsto', 'hasone', 'hasmany'].includes(camelize(type)?.toLowerCase()))
+            if (isAssociationType(type))
                 return '';
-            return `\n    ${attribute(modelClassName, name, type, attr, stiBaseSerializer)}`;
+            if (rendersStiType && name === 'type')
+                return '';
+            return `\n    ${attribute(name, type, attr)}`;
         })
             .join('');
         const def = `export const ${defaultName} = ${modelSerializerSignature} =>
@@ -75,16 +87,17 @@ function variantSerializerClassName(serializerBase, variantSuffix, kind) {
         ? `${serializerBase}${variantSuffix}SummarySerializer`
         : `${serializerBase}${variantSuffix}Serializer`;
 }
-function attribute(modelClassName, name, type, attr, stiBaseSerializer) {
-    if (name === 'type' && stiBaseSerializer) {
-        return `.attribute('type', { openapi: { type: 'string', enum: [(StiChildClass ?? ${modelClassName}).sanitizedName] } })`;
-    }
+function isAssociationType(type) {
+    return ['belongsto', 'hasone', 'hasmany'].includes(camelize(type)?.toLowerCase());
+}
+function attribute(name, type, attr) {
     switch (type) {
         case 'json':
         case 'jsonb':
+            return `.attribute('${camelize(name)}', { openapi: { type: 'object', properties: { } } })`;
         case 'json[]':
         case 'jsonb[]':
-            return `.attribute('${camelize(name)}', { openapi: { type: 'object', properties: { } } })`;
+            return `.attribute('${camelize(name)}', { openapi: { type: 'array', items: { type: 'object', properties: { } } } })`;
         default:
             return `.attribute('${camelize(name)}'${attributeOptionsSpecifier(type, attr)})`;
     }

package/dist/esm/src/serializer/SerializerRenderer.js

@@ -1,3 +1,4 @@
+import Dream from '../Dream.js';
 import RendersManyMustReceiveArray from '../errors/serializers/RendersManyMustReceiveArray.js';
 import compact from '../helpers/compact.js';
 import round from '../helpers/round.js';
@@ -8,7 +9,7 @@ import { DateTime } from '../utils/datetime/DateTime.js';
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
 import inferSerializerFromDreamOrViewModel from './helpers/inferSerializerFromDreamOrViewModel.js';
-import { serializerForAssociatedClass } from './helpers/serializerForAssociatedClass.js';
+import { serializersForAssociatedClass } from './helpers/serializersForAssociatedClass.js';
 export default class SerializerRenderer {
     serializerBuilder;
     passthroughData;
@@ -95,19 +96,16 @@ export default class SerializerRenderer {
                 case 'rendersOne': {
                     const outputAttributeName = this.setCase(attribute.options.as ?? attribute.name);
                     const associatedObject = data[attribute.name];
-                    let serializer = null;
-                    if (associatedObject) {
-                        serializer = serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name));
-                    }
-                    else if (attribute.options.flatten) {
-                        /**
-                         * Only used when flatten: true, and the associated model is null, in which case,
-                         * we need something to determine the keys that will be flattened into the
-                         * rendering serializer
-                         */
-                        serializer = serializerForAssociatedClass(data, attribute.name, attribute.options);
+                    if (!associatedObject && attribute.options.flatten) {
+                        return {
+                            ...accumulator,
+                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), passthroughData),
+                        };
                     }
-                    const serializerBuilder = serializer?.(attribute.options.flatten ? (associatedObject ?? {}) : associatedObject, 
+                    const serializer = associatedObject
+                        ? serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name))
+                        : null;
+                    const serializerBuilder = serializer?.(associatedObject, 
                     // passthrough data going into the serializer is the argument that gets
                     // used in the custom attribute callback function
                     passthroughData);
@@ -178,6 +176,60 @@ export default class SerializerRenderer {
         }, renderedAttributes);
         return renderedAttributes;
     }
+    /**
+     * 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.
+     */
+    nullFlattenedAttributes(serializers, passthroughData, serializersBeingFlattened = new Set()) {
+        return serializers.reduce((flattenedKeys, serializer) => {
+            // a serializer reached again, e.g. one that flattens itself directly or through others, or
+            // one that two polymorphic targets or two STI children both flatten, adds no keys the first
+            // walk through it did not
+            if (serializersBeingFlattened.has(serializer))
+                return flattenedKeys;
+            serializersBeingFlattened.add(serializer);
+            const serializerBuilder = serializer(undefined, passthroughData);
+            const dreamClass = serializerBuilder instanceof DreamSerializerBuilder
+                ? serializerBuilder['$typeForOpenapi']
+                : null;
+            return serializerBuilder['attributes'].reduce((keys, attribute) => {
+                const attributeType = attribute.type;
+                switch (attributeType) {
+                    case 'attribute':
+                    case 'delegatedAttribute':
+                    case 'rendersMany':
+                        keys[this.setCase(attribute.options?.as ?? attribute.name)] = null;
+                        return keys;
+                    case 'customAttribute':
+                        if (!attribute.options.flatten)
+                            keys[this.setCase(attribute.name)] = null;
+                        return keys;
+                    case 'rendersOne':
+                        if (!attribute.options.flatten) {
+                            keys[this.setCase(attribute.options.as ?? attribute.name)] = null;
+                            return keys;
+                        }
+                        return {
+                            ...keys,
+                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(dreamClass, attribute.name, attribute.options), passthroughData, serializersBeingFlattened),
+                        };
+                    default: {
+                        // protection so that if a new ValidationType is ever added, this will throw a type error at build time
+                        const _never = attributeType;
+                        throw new Error(`Unhandled serializer attribute type: ${_never}`);
+                    }
+                }
+            }, flattenedKeys);
+        }, {});
+    }
     setCase(attr) {
         switch (this.renderOpts.casing) {
             case 'camel':

package/dist/esm/src/serializer/builders/DreamSerializerBuilder.js

@@ -26,9 +26,10 @@ export default class DreamSerializerBuilder {
      *   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:
@@ -52,12 +53,14 @@ export default class DreamSerializerBuilder {
      *     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)
@@ -69,27 +72,26 @@ export default class DreamSerializerBuilder {
      * @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(targetName, name, options) {
+    delegatedAttribute(targetName, name, ...options) {
         this.attributes.push({
             type: 'delegatedAttribute',
             targetName: targetName,
             name: name,
-            options: options ?? {},
+            options: options[0] ?? {},
         });
         return this;
     }
@@ -99,17 +101,24 @@ export default class DreamSerializerBuilder {
      * 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
@@ -122,20 +131,18 @@ export default class DreamSerializerBuilder {
      *   { 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, fn, options) {
@@ -143,7 +150,7 @@ export default class DreamSerializerBuilder {
             type: 'customAttribute',
             name,
             fn,
-            options: options,
+            options,
         });
         return this;
     }
@@ -157,9 +164,18 @@ export default class DreamSerializerBuilder {
      * @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