ghost 6.56.0 → 6.57.0

package/core/server/api/endpoints/email-post.js

@@ -36,7 +36,7 @@ const controller = {
             }
         },
         async query(frame) {
-            urlSerializerUtils.forceUrlRelationsWhenLazy(frame, 'posts');
+            urlSerializerUtils.forceUrlRelations(frame, 'posts');
 
             const model = await models.Post.findOne(Object.assign(frame.data, {status: 'sent'}), frame.options);
 

package/core/server/api/endpoints/previews.js

@@ -82,7 +82,7 @@ const controller = {
             await _addMemberContextToFrame(frame);
 
             // previews has no input serializer, so the URL force-load happens here
-            urlSerializerUtils.forceUrlRelationsWhenLazy(frame, 'posts');
+            urlSerializerUtils.forceUrlRelations(frame, 'posts');
 
             const model = await models.Post.findOne(Object.assign({status: 'all'}, frame.data), frame.options);
             if (!model) {

package/core/server/api/endpoints/search-index-public.js

@@ -4,8 +4,8 @@ const {requiredUrlColumns} = require('./utils/serializers/input/utils/url');
 const getPostServiceInstance = require('../../services/posts/posts-service-instance');
 const postsService = getPostServiceInstance();
 
-const urlRelationsWhenLazyRouting = () => {
-    const withRelated = urlService.facade.getRequiredRelations();
+const urlRelationsForRouting = () => {
+    const withRelated = urlService.getRequiredRelations();
     return withRelated.length ? {withRelated} : {};
 };
 
@@ -23,7 +23,7 @@ const controller = {
                 limit: '10000',
                 order: 'updated_at DESC',
                 columns: requiredUrlColumns('posts', ['id', 'slug', 'title', 'excerpt', 'url', 'updated_at', 'visibility']),
-                ...urlRelationsWhenLazyRouting()
+                ...urlRelationsForRouting()
             };
 
             return postsService.browsePosts(options);

package/core/server/api/endpoints/search-index.js

@@ -4,8 +4,8 @@ const {requiredUrlColumns} = require('./utils/serializers/input/utils/url');
 const getPostServiceInstance = require('../../services/posts/posts-service-instance');
 const postsService = getPostServiceInstance();
 
-const urlRelationsWhenLazyRouting = () => {
-    const withRelated = urlService.facade.getRequiredRelations();
+const urlRelationsForRouting = () => {
+    const withRelated = urlService.getRequiredRelations();
     return withRelated.length ? {withRelated} : {};
 };
 
@@ -26,7 +26,7 @@ const controller = {
                 limit: '10000',
                 order: 'updated_at DESC',
                 columns: requiredUrlColumns('posts', ['id', 'uuid', 'url', 'title', 'slug', 'status', 'published_at', 'visibility']),
-                ...urlRelationsWhenLazyRouting()
+                ...urlRelationsForRouting()
             };
 
             return postsService.browsePosts(options);
@@ -46,7 +46,7 @@ const controller = {
                 limit: '10000',
                 order: 'updated_at DESC',
                 columns: requiredUrlColumns('pages', ['id', 'uuid', 'url', 'title', 'slug', 'status', 'published_at', 'visibility']),
-                ...urlRelationsWhenLazyRouting()
+                ...urlRelationsForRouting()
             };
 
             return postsService.browsePosts(options);

package/core/server/api/endpoints/utils/serializers/input/authors.js

@@ -17,7 +17,7 @@ module.exports = {
     browse(apiConfig, frame) {
         debug('browse');
 
-        url.forceUrlColumnsWhenLazy(frame, 'authors');
+        url.forceUrlColumns(frame, 'authors');
 
         if (utils.isContentAPI(frame)) {
             setDefaultOrder(frame);
@@ -27,7 +27,7 @@ module.exports = {
     read(apiConfig, frame) {
         debug('read');
 
-        url.forceUrlColumnsWhenLazy(frame, 'authors');
+        url.forceUrlColumns(frame, 'authors');
 
         if (utils.isContentAPI(frame)) {
             setDefaultOrder(frame);

package/core/server/api/endpoints/utils/serializers/input/comments.js

@@ -24,7 +24,7 @@ module.exports = {
         });
 
         if (frame.options.withRelated.includes('post')) {
-            for (const relation of urlService.facade.getRequiredRelations()) {
+            for (const relation of urlService.getRequiredRelations()) {
                 const prefixed = `post.${relation}`;
                 if (!frame.options.withRelated.includes(prefixed)) {
                     frame.options.withRelated.push(prefixed);

package/core/server/api/endpoints/utils/serializers/input/pages.js

@@ -56,7 +56,7 @@ function defaultRelations(frame) {
         frame.options.withRelated = ['tags', 'authors', 'authors.roles', 'tiers', 'count.signups', 'count.paid_conversions'];
     }
 
-    url.forceUrlRelationsWhenLazy(frame, 'pages');
+    url.forceUrlRelations(frame, 'pages');
 }
 
 function setDefaultOrder(frame) {
@@ -126,7 +126,7 @@ module.exports = {
 
             setDefaultOrder(frame);
             forceVisibilityColumn(frame);
-            url.forceUrlRelationsWhenLazy(frame, 'pages');
+            url.forceUrlRelations(frame, 'pages');
         }
 
         if (!localUtils.isContentAPI(frame)) {
@@ -145,7 +145,7 @@ module.exports = {
             removeSourceFormats(frame);
             setDefaultOrder(frame);
             forceVisibilityColumn(frame);
-            url.forceUrlRelationsWhenLazy(frame, 'pages');
+            url.forceUrlRelations(frame, 'pages');
         }
 
         if (!localUtils.isContentAPI(frame)) {

package/core/server/api/endpoints/utils/serializers/input/posts.js

@@ -82,7 +82,7 @@ function defaultRelations(frame) {
         frame.options.withRelated = ['tags', 'authors', 'authors.roles', 'email', 'tiers', 'newsletter', 'count.clicks'];
     }
 
-    url.forceUrlRelationsWhenLazy(frame, 'posts');
+    url.forceUrlRelations(frame, 'posts');
 }
 
 function setDefaultOrder(frame) {
@@ -161,7 +161,7 @@ module.exports = {
             setDefaultOrder(frame);
             forceVisibilityColumn(frame);
             mapWithRelated(frame);
-            url.forceUrlRelationsWhenLazy(frame, 'posts');
+            url.forceUrlRelations(frame, 'posts');
         }
 
         if (!localUtils.isContentAPI(frame)) {
@@ -188,7 +188,7 @@ module.exports = {
 
             setDefaultOrder(frame);
             forceVisibilityColumn(frame);
-            url.forceUrlRelationsWhenLazy(frame, 'posts');
+            url.forceUrlRelations(frame, 'posts');
         }
 
         if (!localUtils.isContentAPI(frame)) {

package/core/server/api/endpoints/utils/serializers/input/tags.js

@@ -19,7 +19,7 @@ module.exports = {
     browse(apiConfig, frame) {
         debug('browse');
 
-        url.forceUrlColumnsWhenLazy(frame, 'tags');
+        url.forceUrlColumns(frame, 'tags');
 
         if (utils.isContentAPI(frame)) {
             setDefaultOrder(frame);

package/core/server/api/endpoints/utils/serializers/input/users.js

@@ -6,13 +6,13 @@ module.exports = {
         debug('browse');
 
         // Staff users route through the authors router types.
-        url.forceUrlColumnsWhenLazy(frame, 'authors');
+        url.forceUrlColumns(frame, 'authors');
     },
 
     read(apiConfig, frame) {
         debug('read');
 
-        url.forceUrlColumnsWhenLazy(frame, 'authors');
+        url.forceUrlColumns(frame, 'authors');
 
         if (frame.data.id === 'me' && frame.options.context && frame.options.context.user) {
             frame.data.id = frame.options.context.user;

package/core/server/api/endpoints/utils/serializers/input/utils/url.js

@@ -71,28 +71,41 @@ const forSetting = (attrs) => {
 // build a URL (e.g. status/visibility/slug), so the service would reject the
 // resource as thin. Force them back into the fetch and record them on the
 // frame — the output mapper strips them from the response after the URL is
-// built. No-op under the eager service (getRequiredFields → []).
-const forceUrlColumnsWhenLazy = (frame, routerType) => {
+// built. No-op when the routing config needs no extra columns.
+const forceUrlColumns = (frame, routerType, extraColumns = []) => {
     if (!Array.isArray(frame.options.columns) || !frame.options.columns.includes('url')) {
         return;
     }
-    const forced = urlService.facade.getRequiredFields(routerType).filter(field => !frame.options.columns.includes(field));
+    const required = new Set([...urlService.getRequiredFields(routerType), ...extraColumns]);
+    const missing = [...required].filter(field => !frame.options.columns.includes(field));
+    if (!missing.length) {
+        return;
+    }
+    // A read already carries the fields it was looked up by: `findOne` forges
+    // the model with them before the fetch, so they survive a narrowed
+    // `?fields=` list and the caller is served them today. Stripping those back
+    // out would take a field away — `posts/slug/:slug/?fields=url` still
+    // answers with its slug. They are still selected, because the lookup
+    // matches case-insensitively: the forged value can differ in case from the
+    // stored one, and the URL is built from whichever the model carries.
+    const carried = Object.keys(frame.data || {});
+    const forced = missing.filter(field => !carried.includes(field));
     if (forced.length) {
-        frame.forcedUrlColumns = forced;
-        frame.options.columns.push(...forced);
+        frame.forcedUrlColumns = {routerType, columns: forced};
     }
+    frame.options.columns.push(...missing);
 };
 
 // `url` is serialized for every post/page unless `?fields` narrows it away,
 // so the relations the lazy URL service reads (e.g. tags for a tag-filtered
 // collection) must be loaded whenever the URL will be built — not only for
 // the `?fields=url` case. Forced relations are recorded on the frame for the
-// output mapper to strip. No-op under the eager service.
-const forceUrlRelationsWhenLazy = (frame, routerType) => {
+// output mapper to strip. No-op when the routing config reads no relations.
+const forceUrlRelations = (frame, routerType) => {
     if (!localUtils.willSerializeUrl(frame)) {
         return;
     }
-    const relations = urlService.facade.getRequiredRelations();
+    const relations = urlService.getRequiredRelations();
     if (relations.length) {
         const requested = frame.options.withRelated || [];
         // a nested include covers its parent: `authors.roles` loads authors
@@ -105,13 +118,18 @@ const forceUrlRelationsWhenLazy = (frame, routerType) => {
             frame.options.withRelated = [...requested, ...forced];
         }
     }
-    forceUrlColumnsWhenLazy(frame, routerType);
+    // The URL is looked up by `model.id`, and Bookshelf matches eager-loaded
+    // rows back to their parent by the same key — so a `?fields=` list that
+    // omits it serializes /404/ and leaves the relations above unattached,
+    // silently and without a key on the model at all. A read looked up by id
+    // is covered by the carried-fields rule above.
+    forceUrlColumns(frame, routerType, ['id']);
 };
 
-// Options-object variant of forceUrlColumnsWhenLazy for endpoints that build
+// Options-object variant of forceUrlColumns for endpoints that build
 // their query options directly (search index).
 const requiredUrlColumns = (routerType, columns) => {
-    const required = urlService.facade.getRequiredFields(routerType).filter(field => !columns.includes(field));
+    const required = urlService.getRequiredFields(routerType).filter(field => !columns.includes(field));
     return required.length ? [...columns, ...required] : columns;
 };
 
@@ -120,5 +138,5 @@ module.exports.requiredUrlColumns = requiredUrlColumns;
 module.exports.forUser = forUser;
 module.exports.forTag = forTag;
 module.exports.forSetting = forSetting;
-module.exports.forceUrlColumnsWhenLazy = forceUrlColumnsWhenLazy;
-module.exports.forceUrlRelationsWhenLazy = forceUrlRelationsWhenLazy;
+module.exports.forceUrlColumns = forceUrlColumns;
+module.exports.forceUrlRelations = forceUrlRelations;

package/core/server/api/endpoints/utils/serializers/output/mappers/posts.js

@@ -136,8 +136,8 @@ module.exports = async (model, frame, options = {}) => {
     clean.post(jsonModel, frame);
 
     // Columns force-loaded for the URL computation, not requested by the caller.
-    if (frame.forcedUrlColumns) {
-        frame.forcedUrlColumns.forEach((column) => {
+    if (frame.forcedUrlColumns && frame.forcedUrlColumns.routerType === routerType) {
+        frame.forcedUrlColumns.columns.forEach((column) => {
             delete jsonModel[column];
         });
     }

package/core/server/api/endpoints/utils/serializers/output/mappers/tags.js

@@ -8,8 +8,8 @@ module.exports = (model, frame) => {
     clean.tag(jsonModel, frame);
 
     // Columns force-loaded for the URL computation, not requested by the caller.
-    if (frame.forcedUrlColumns) {
-        frame.forcedUrlColumns.forEach((column) => {
+    if (frame.forcedUrlColumns && frame.forcedUrlColumns.routerType === 'tags') {
+        frame.forcedUrlColumns.columns.forEach((column) => {
             delete jsonModel[column];
         });
     }

package/core/server/api/endpoints/utils/serializers/output/mappers/users.js

@@ -6,6 +6,14 @@ module.exports = (model, frame) => {
 
     url.forUser(model.id, jsonModel, frame.options);
 
+    // Force-loaded for the URL computation, not requested by the caller (the
+    // author permalink substitutes :slug, so `?fields=url` pulls it in).
+    if (frame.forcedUrlColumns && frame.forcedUrlColumns.routerType === 'authors') {
+        frame.forcedUrlColumns.columns.forEach((column) => {
+            delete jsonModel[column];
+        });
+    }
+
     clean.author(jsonModel, frame);
 
     return jsonModel;

package/core/server/api/endpoints/utils/serializers/output/utils/url.js

@@ -10,8 +10,9 @@ const forPost = (id, attrs, frame, type = 'posts') => {
     // type from `attrs` would silently fall back to 'posts' for pages.
     // The mapper that owns the resource always knows which it is.
     //
-    // `id` is passed separately for the same reason: without it, the eager
-    // facade's id-based fallback hits /404/ for every record.
+    // `id` is passed separately for the same reason: `?fields=url` strips it
+    // from `attrs`, and the URL service needs it for `:id` permalinks and to
+    // name the resource when it reports a problem.
     //
     // When `url` was not requested (`?fields=id,title`), don't compute it at
     // all — attrs is stripped to the requested columns, so the resource would
@@ -24,17 +25,23 @@ const forPost = (id, attrs, frame, type = 'posts') => {
         return attrs;
     }
 
-    // Diagnostic only: hand the compare-mode URL service the producing api
-    // endpoint. The parity/thin-resource logs capture a caller stack, but it
-    // truncates at the async api-framework boundary and never names the
-    // endpoint; the api-framework Frame carries it, so pass it through. Omitted
-    // for non-api callers (mentions, email) whose frame has no endpoint fields.
+    // Names the fetch that produced this resource. It matters on the degrade
+    // path: a thin resource is answered with a silent /404/, and the report is
+    // the only way back to the endpoint that under-fetched it. Ignored by URL
+    // generation itself; read only into that report.
     const options = {absolute: true};
     if (frame && (frame.docName || frame.method)) {
-        options.serializerContext = {apiType: frame.apiType, docName: frame.docName, method: frame.method};
+        options.serializerContext = {
+            apiType: frame.apiType,
+            docName: frame.docName,
+            method: frame.method,
+            withRelated: frame.options && frame.options.withRelated,
+            columns: frame.options && frame.options.columns,
+            forcedUrlRelations: frame.forcedUrlRelations
+        };
     }
 
-    attrs.url = urlService.facade.getUrlForResource({...attrs, id, type}, options);
+    attrs.url = urlService.getUrlForResource({...attrs, id, type}, options);
 
     /**
      * CASE: admin api should serve preview urls
@@ -71,7 +78,7 @@ const forPost = (id, attrs, frame, type = 'posts') => {
 
 const forUser = (id, attrs, options) => {
     if (!options.columns || (options.columns && options.columns.includes('url'))) {
-        attrs.url = urlService.facade.getUrlForResource({...attrs, id, type: 'authors'}, {absolute: true});
+        attrs.url = urlService.getUrlForResource({...attrs, id, type: 'authors'}, {absolute: true});
     }
 
     return attrs;
@@ -79,7 +86,7 @@ const forUser = (id, attrs, options) => {
 
 const forTag = (id, attrs, options) => {
     if (!options.columns || (options.columns && options.columns.includes('url'))) {
-        attrs.url = urlService.facade.getUrlForResource({...attrs, id, type: 'tags'}, {absolute: true});
+        attrs.url = urlService.getUrlForResource({...attrs, id, type: 'tags'}, {absolute: true});
     }
 
     return attrs;

package/core/server/data/migrations/versions/6.57/2026-08-04-18-00-00-store-custom-field-values-as-leaf-rows.js

@@ -0,0 +1,74 @@
+const logging = require('@tryghost/logging');
+const {createNonTransactionalMigration} = require('../../utils');
+const {addColumn, dropColumn, addUnique, dropUnique, addIndex, dropIndex} = require('../../../schema/commands');
+
+const TABLE = 'members_custom_field_values';
+
+// Named explicitly; the derived name would overrun MySQL's identifier limit, which
+// schema.test.js checks for every table.
+const LEAF_UNIQUE = 'members_custom_field_values_leaf_unique';
+
+// Values are discarded rather than converted: custom fields sit behind a private flag and
+// have never been released, so only a site deliberately opted in can hold one.
+async function discardStoredValues(knex) {
+    const discarded = await knex(TABLE).del();
+    if (discarded > 0) {
+        logging.warn(`Discarded ${discarded} custom field value(s): the storage format changed before the feature was released`);
+    }
+}
+
+// Column changes ask for `auto` so MySQL picks an in-place algorithm where it can; the
+// helpers otherwise default to a full table copy, which blocks writes.
+//
+// Two constraints shape the order of everything below.
+//
+// MySQL refuses to drop the last index serving a foreign key, counting any index whose
+// leftmost column is the referencing one, so each replacement is added before the thing
+// it replaces is dropped.
+//
+// This migration is not transactional, so a crash leaves the table half-changed with
+// nothing recorded as done and knex-migrator runs it again on the next boot. Every step
+// therefore tolerates having already happened: the constraint and index helpers swallow
+// that themselves, the column steps ask first.
+module.exports = createNonTransactionalMigration(
+    async function up(knex) {
+        // First, so nothing can collide with the new constraint.
+        await discardStoredValues(knex);
+
+        if (!await knex.schema.hasColumn(TABLE, 'path')) {
+            await addColumn(TABLE, 'path', knex, undefined, {algorithm: 'auto'});
+        }
+
+        // `member_id` stays leftmost, covering that foreign key the moment this exists.
+        await addUnique(TABLE, ['member_id', 'custom_field_id', 'path'], knex, LEAF_UNIQUE);
+        await dropUnique(TABLE, ['member_id', 'custom_field_id'], knex);
+
+        if (await knex.schema.hasColumn(TABLE, 'value_json')) {
+            await dropColumn(TABLE, 'value_json', knex, {}, {algorithm: 'auto'});
+        }
+        await addIndex(TABLE, ['custom_field_id', 'path'], knex);
+
+        // Only present after a rollback, where `down` adds it to keep a foreign key
+        // covered. Leaving it would be drift against a fresh install.
+        await dropIndex(TABLE, ['custom_field_id'], knex);
+    },
+    async function down(knex) {
+        // Rebuilding a composite would need the field-type catalog, which a migration must
+        // not read: it has to keep working when the catalog moves on.
+        await discardStoredValues(knex);
+
+        await addUnique(TABLE, ['member_id', 'custom_field_id'], knex);
+        await dropUnique(TABLE, ['member_id', 'custom_field_id', 'path'], knex, LEAF_UNIQUE);
+
+        // Back before the composite one goes, or MySQL has nothing covering that key.
+        await addIndex(TABLE, ['custom_field_id'], knex);
+        await dropIndex(TABLE, ['custom_field_id', 'path'], knex);
+
+        if (!await knex.schema.hasColumn(TABLE, 'value_json')) {
+            await addColumn(TABLE, 'value_json', knex, {type: 'text', maxlength: 65535, nullable: true}, {algorithm: 'auto'});
+        }
+        if (await knex.schema.hasColumn(TABLE, 'path')) {
+            await dropColumn(TABLE, 'path', knex, {}, {algorithm: 'auto'});
+        }
+    }
+);

package/core/server/data/migrations/versions/6.57/2026-08-04-18-54-14-reset-automation-email-analytics.js

@@ -0,0 +1,25 @@
+const logging = require('@tryghost/logging');
+const {createTransactionalMigration} = require('../../utils');
+
+module.exports = createTransactionalMigration(
+    async function up(knex) {
+        logging.info('Resetting automation email analytics counts');
+
+        const updatedRevisions = await knex('automation_action_revisions').update({
+            email_sent_count: null,
+            email_opened_count: null,
+            email_clicked_count: null
+        });
+
+        logging.info(`Reset automation email analytics counts for ${updatedRevisions} action revisions`);
+
+        const deletedRecipients = await knex('automated_email_recipients')
+            .whereNotNull('automation_action_revision_id')
+            .del();
+
+        logging.info(`Deleted ${deletedRecipients} automation email recipient rows`);
+    },
+    async function down() {
+        logging.info('Skipping rollback for automation email analytics reset');
+    }
+);

package/core/server/data/schema/commands.js

@@ -276,13 +276,18 @@ async function dropIndex(tableName, columns, transaction = db.knex) {
  * @param {string} tableName - name of the table to add unique constraint to
  * @param {string|string[]} columns - column(s) to form unique constraint with
  * @param {import('knex').Knex} [transaction] - connection object containing knex reference
+ * @param {string} [indexName] - name for the constraint; knex derives one from the table
+ * and every column when omitted, which can overrun MySQL's 64-character limit
  */
-async function addUnique(tableName, columns, transaction = db.knex) {
+async function addUnique(tableName, columns, transaction = db.knex, indexName) {
     try {
         logging.info(`Adding unique constraint for '${columns}' in table '${tableName}'`);
 
         return await transaction.schema.table(tableName, function (table) {
-            table.unique(columns);
+            // Knex derives a name from the table and every column when it is not given
+            // one, and that can overrun MySQL's 64-character identifier limit on a wide
+            // table or a constraint over several columns.
+            table.unique(columns, indexName ? {indexName} : undefined);
         });
     } catch (err) {
         if (err.code === 'SQLITE_ERROR') {
@@ -304,12 +309,14 @@ async function addUnique(tableName, columns, transaction = db.knex) {
  * @param {string|string[]} columns - column(s) unique constraint was formed
  * @param {import('knex').Knex} transaction - connection object containing knex reference
  */
-async function dropUnique(tableName, columns, transaction = db.knex) {
+async function dropUnique(tableName, columns, transaction = db.knex, indexName) {
     try {
         logging.info(`Dropping unique constraint for '${columns}' in table '${tableName}'`);
 
         return await transaction.schema.table(tableName, function (table) {
-            table.dropUnique(columns);
+            // Named constraints have to be dropped by that name: the one knex would
+            // derive from the columns is not what is on the table.
+            table.dropUnique(columns, indexName);
         });
     } catch (err) {
         if (err.code === 'SQLITE_ERROR') {
@@ -542,7 +549,16 @@ function createTable(table, transaction = db.knex, tableSpec = schema[table]) {
             });
         }
         if (tableSpec['@@UNIQUE_CONSTRAINTS@@']) {
-            tableSpec['@@UNIQUE_CONSTRAINTS@@'].forEach(unique => t.unique(unique));
+            tableSpec['@@UNIQUE_CONSTRAINTS@@'].forEach((unique) => {
+                // An entry is normally the columns alone, and knex names the constraint
+                // after the table and every one of them. The object form is for when
+                // that derived name would overrun MySQL's 64-character limit.
+                if (unique && typeof unique === 'object' && !Array.isArray(unique)) {
+                    t.unique(unique.columns, {indexName: unique.indexName});
+                } else {
+                    t.unique(unique);
+                }
+            });
         }
         if (tableSpec['@@PRIMARY_KEY@@']) {
             t.primary(tableSpec['@@PRIMARY_KEY@@']);

package/core/server/data/schema/schema.js

@@ -682,15 +682,34 @@ module.exports = {
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         custom_field_id: {type: 'string', maxlength: 24, nullable: false, references: 'members_custom_fields.id', cascadeDelete: true},
         member_id: {type: 'string', maxlength: 24, nullable: false, references: 'members.id', cascadeDelete: true},
-        // Exactly one value column is populated per row, chosen by the field
-        // type's storage type in @tryghost/custom-field-types, whose byte bound
-        // on long_text matches this column exactly.
+        // Which part of the field's value this row carries. A scalar has one part and
+        // stores it under the empty path; a composite stores one row per sub-field it
+        // fills, under that sub-field's key. Not nullable, because MySQL counts NULLs
+        // as distinct in a unique index and the constraint below would stop holding.
+        path: {type: 'string', maxlength: 191, nullable: false, defaultTo: ''},
+        // One row, one value: a part a member has not filled in has no row at all. The
+        // column stays nullable even so, because making it NOT NULL is only reachable
+        // through knex's dropNullable, which rewrites the column on MySQL and widens
+        // TEXT to MEDIUMTEXT — a migrated site would then accept sixteen megabytes in a
+        // column a fresh install bounds at 65,535 bytes. The bound matching long_text's
+        // exactly is worth more than the schema restating what the write path enforces.
         value_text: {type: 'text', maxlength: 65535, nullable: true},
-        value_json: {type: 'text', maxlength: 65535, nullable: true},
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true},
+        // Named, because the name knex derives from the table and all three columns is
+        // 65 characters and MySQL stops at 64. The migration that first created this
+        // table already shortened a column for the same reason; a third column spends
+        // what headroom that bought.
         '@@UNIQUE_CONSTRAINTS@@': [
-            ['member_id', 'custom_field_id']
+            {columns: ['member_id', 'custom_field_id', 'path'], indexName: 'members_custom_field_values_leaf_unique'}
+        ],
+        // What a segment filter looks up: every member holding a given value for a
+        // given part of a given field. The value itself is not in the index — it is
+        // TEXT, so MySQL would need a prefix length, and the schema's index builder
+        // applies one length to every column in a composite index rather than to a
+        // single chosen one.
+        '@@INDEXES@@': [
+            ['custom_field_id', 'path']
         ]
     },
     members_stripe_customers: {

package/core/server/lib/common/to-plain.ts

@@ -7,7 +7,7 @@
  * callers accept either shape uniformly:
  *
  *   const data = toPlain(post);
- *   urlService.facade.getUrlForResource({...data, type: 'posts'}, ...)
+ *   urlService.getUrlForResource({...data, type: 'posts'}, ...)
  */
 type JsonSerializable<T> = {
     toJSON(): T;

package/core/server/models/post.js

@@ -1006,8 +1006,8 @@ Post = ghostBookshelf.Model.extend({
      *     - `slug`: /:slug/
      *     - `published_at`: /:year/:slug
      *     - `author_id`: /:author/:slug, /:primary_author/:slug
-     *     - now, the UrlService pre-generates urls based on the resources
-     *     - you can ask `urlService.getUrlByResourceId(post.id)`
+     *     - now, the UrlService computes urls from the routing config
+     *     - you can ask `urlService.getUrlForResource(post)`
      *
      * ### events
      *   - you call `findAll` with `columns: id`