@byline/core 4.1.0 → 4.2.0

package/dist/config/validate-admin-configs.js

@@ -44,6 +44,75 @@ export function validateAdminConfigs(admins, collections) {
         validateOne(admin, collectionsByPath);
     }
 }
+/**
+ * Validate every block admin config in a configuration.
+ *
+ * Enforced rules (per `ClientConfig.blockAdmin` entry):
+ *  1. Block pairing — `blockType` matches a block declared on at least one
+ *     `type: 'blocks'` field across the registered collections (blocks have
+ *     no global registry; the collections walk is the source of truth).
+ *  2. Uniqueness — no two entries share a `blockType`.
+ *  3. `fields` map sanity — every key matches a top-level field name of the
+ *     block (when the same `blockType` appears in several collections, the
+ *     union of their top-level field names is accepted).
+ *
+ * Throws a plain `Error` for the same reason `validateAdminConfigs` does —
+ * this runs at startup, before the logger is necessarily wired up.
+ */
+export function validateBlockAdminConfigs(blockAdmins, collections) {
+    if (blockAdmins == null || blockAdmins.length === 0)
+        return;
+    // Collect blockType → union of top-level field names across every
+    // declaration site (including blocks nested inside groups/arrays/blocks).
+    const blockFieldNames = new Map();
+    const walkBlock = (block) => {
+        let names = blockFieldNames.get(block.blockType);
+        if (names == null) {
+            names = new Set();
+            blockFieldNames.set(block.blockType, names);
+        }
+        for (const field of block.fields) {
+            if ('name' in field)
+                names.add(field.name);
+        }
+        walkFields(block.fields);
+    };
+    const walkFields = (fields) => {
+        for (const field of fields) {
+            if (field.type === 'blocks') {
+                for (const block of field.blocks)
+                    walkBlock(block);
+            }
+            else if ('fields' in field && Array.isArray(field.fields)) {
+                walkFields(field.fields);
+            }
+        }
+    };
+    for (const collection of collections) {
+        walkFields(collection.fields);
+    }
+    const seen = new Set();
+    for (const entry of blockAdmins) {
+        // Rule 2 — uniqueness.
+        if (seen.has(entry.blockType)) {
+            throw new Error(`Block admin config "${entry.blockType}" is registered more than once in \`blockAdmin\`.`);
+        }
+        seen.add(entry.blockType);
+        // Rule 1 — block pairing.
+        const names = blockFieldNames.get(entry.blockType);
+        if (names == null) {
+            throw new Error(`Block admin config "${entry.blockType}" has no matching block (no \`type: 'blocks'\` field of any registered collection declares a block with \`blockType: '${entry.blockType}'\`).`);
+        }
+        // Rule 3 — `fields` keys must be top-level field names of the block.
+        if (entry.fields != null) {
+            for (const key of Object.keys(entry.fields)) {
+                if (!names.has(key)) {
+                    throw new Error(`Block "${entry.blockType}": \`fields["${key}"]\` references a name that is not a top-level field of the block. Per-field overrides apply only to the block's top-level fields.`);
+                }
+            }
+        }
+    }
+}
 function validateOne(admin, collectionsByPath) {
     // Rule 1 — slug pairing.
     const collection = collectionsByPath.get(admin.slug);
@@ -62,26 +131,30 @@ function validateOne(admin, collectionsByPath) {
         if ('name' in field)
             topLevelFieldNames.add(field.name);
     }
-    // Rule 7 — defaultSort sanity. The list read applies this spec verbatim
-    // (host list server fn → parseSort), so a bad field name would silently
-    // fall back to `created_at desc` at request time — fail loudly at boot
-    // instead.
-    if (admin.defaultSort != null) {
-        const { field, direction } = admin.defaultSort;
+    // Rule 7 — defaultSort / itemViewSort sanity. The list read applies these
+    // specs verbatim (host list server fn → parseSort), so a bad field name
+    // would silently fall back to `created_at desc` at request time — fail
+    // loudly at boot instead. Both options share one rule set.
+    const validateSortSpec = (spec, optionName) => {
+        if (spec == null)
+            return;
+        const { field, direction } = spec;
         const documentColumns = new Set(['createdAt', 'updatedAt', 'path']);
         if (collection.orderable === true) {
-            fail(`defaultSort is not allowed on an orderable collection — manual ordering owns the default sort (order_key asc).`);
+            fail(`${optionName} is not allowed on an orderable collection — manual ordering owns the sort (order_key asc).`);
         }
         if (typeof field !== 'string' || field.length === 0) {
-            fail(`defaultSort.field must be a non-empty string.`);
+            fail(`${optionName}.field must be a non-empty string.`);
         }
         if (!topLevelFieldNames.has(field) && !documentColumns.has(field)) {
-            fail(`defaultSort.field "${String(field)}" is not a top-level schema field or a document column (createdAt, updatedAt, path).`);
+            fail(`${optionName}.field "${String(field)}" is not a top-level schema field or a document column (createdAt, updatedAt, path).`);
         }
         if (direction != null && direction !== 'asc' && direction !== 'desc') {
-            fail(`defaultSort.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
+            fail(`${optionName}.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
         }
-    }
+    };
+    validateSortSpec(admin.defaultSort, 'defaultSort');
+    validateSortSpec(admin.itemViewSort, 'itemViewSort');
     // Build primitive lookup tables.
     const tabSets = admin.tabSets ?? [];
     const rows = admin.rows ?? [];

package/dist/config/validate-admin-configs.test.node.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it } from 'vitest';
-import { validateAdminConfigs } from './validate-admin-configs.js';
+import { validateAdminConfigs, validateBlockAdminConfigs } from './validate-admin-configs.js';
 const collection = {
     path: 'news',
     labels: { singular: 'News', plural: 'News' },
@@ -238,6 +238,44 @@ describe('validateAdminConfigs', () => {
         };
         expect(() => validateAdminConfigs([admin], [orderableCollection])).toThrow(/not allowed on an orderable collection/);
     });
+    // Rule 7 — itemViewSort shares the defaultSort rule set.
+    it('accepts an itemViewSort on a schema field', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('accepts independent defaultSort and itemViewSort', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'updatedAt', direction: 'desc' },
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('rejects an itemViewSort field that resolves to nothing', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'nonexistent' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/itemViewSort\.field "nonexistent"/);
+    });
+    it('rejects an itemViewSort direction outside asc/desc', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title', direction: 'sideways' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/itemViewSort\.direction must be 'asc' or 'desc'/);
+    });
+    it('rejects an itemViewSort on an orderable collection', () => {
+        const orderableCollection = { ...collection, orderable: true };
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [orderableCollection])).toThrow(/not allowed on an orderable collection/);
+    });
     // Layout omitted — bookkeeping skipped, primitive declarations still checked.
     it('skips placement bookkeeping when layout is omitted', () => {
         const admin = {
@@ -258,3 +296,78 @@ describe('validateAdminConfigs', () => {
         expect(() => validateAdminConfigs([admin], [collection])).toThrow(/collides with a schema field/);
     });
 });
+describe('validateBlockAdminConfigs', () => {
+    const quoteBlock = {
+        blockType: 'quoteBlock',
+        fields: [
+            { name: 'quoteText', label: 'Quote', type: 'richText' },
+            { name: 'source', label: 'Source', type: 'text' },
+        ],
+    };
+    const heroBlock = {
+        blockType: 'heroBlock',
+        fields: [{ name: 'heading', label: 'Heading', type: 'text' }],
+    };
+    const blockCollection = {
+        path: 'pages',
+        labels: { singular: 'Page', plural: 'Pages' },
+        useAsPath: 'title',
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'content', label: 'Content', type: 'blocks', blocks: [quoteBlock] },
+            {
+                name: 'meta',
+                label: 'Meta',
+                type: 'group',
+                fields: [
+                    // Blocks fields nested inside structure fields are still collected.
+                    { name: 'panels', label: 'Panels', type: 'blocks', blocks: [heroBlock] },
+                ],
+            },
+        ],
+    };
+    it('accepts a valid block admin config (baseline)', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { quoteText: {} } }], [blockCollection])).not.toThrow();
+    });
+    it('is a no-op when blockAdmins is undefined or empty', () => {
+        expect(() => validateBlockAdminConfigs(undefined, [blockCollection])).not.toThrow();
+        expect(() => validateBlockAdminConfigs([], [blockCollection])).not.toThrow();
+    });
+    // Rule 1 — block pairing.
+    it('rejects an entry whose blockType matches no declared block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'missingBlock' }], [blockCollection])).toThrow(/no matching block/);
+    });
+    it('finds blocks declared inside nested structure fields', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'heroBlock', fields: { heading: {} } }], [blockCollection])).not.toThrow();
+    });
+    // Rule 2 — uniqueness.
+    it('rejects duplicate blockType entries', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock' }, { blockType: 'quoteBlock' }], [blockCollection])).toThrow(/registered more than once/);
+    });
+    // Rule 3 — fields map sanity.
+    it('rejects a fields key that is not a top-level field of the block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { doesNotExist: {} } }], [blockCollection])).toThrow(/not a top-level field of the block/);
+    });
+    it('accepts the union of field names when a blockType appears in several collections', () => {
+        const other = {
+            path: 'docs',
+            labels: { singular: 'Doc', plural: 'Docs' },
+            useAsPath: 'title',
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'content',
+                    label: 'Content',
+                    type: 'blocks',
+                    blocks: [
+                        {
+                            blockType: 'quoteBlock',
+                            fields: [{ name: 'attribution', label: 'Attribution', type: 'text' }],
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { quoteText: {}, attribution: {} } }], [blockCollection, other])).not.toThrow();
+    });
+});

package/dist/config/validate-collections.js

@@ -237,5 +237,48 @@ export function validateCollections(collections) {
             throw new Error(`Collection "${collection.path}" sets both \`tree: true\` and \`orderable: true\`. A document-tree collection owns ordering on the tree edge (per-parent), so \`byline_documents.order_key\` is inert — set only \`tree: true\`.`);
         }
         validateVirtualFields(collection);
+        validateUploadLocations(collection);
     }
 }
+/**
+ * Enforce the `upload.location` shape for every upload-capable field. The
+ * value is a declarative storage-key scope handed to storage providers
+ * (`<location>/<uuid>-<filename>`), so it must be a clean POSIX-style
+ * segment path:
+ *
+ *   - non-empty string, forward slashes only;
+ *   - no leading / trailing / duplicate slashes;
+ *   - segments of `A–Z a–z 0–9 . _ -` only (no spaces, no backslashes);
+ *   - no `.` or `..` segments (path traversal).
+ */
+function validateUploadLocations(collection) {
+    walkFieldsWithPath(collection.fields, (field, fieldPath) => {
+        if (field.type !== 'file' && field.type !== 'image')
+            return;
+        const location = field.upload?.location;
+        if (location === undefined)
+            return;
+        const fail = (reason) => {
+            throw new Error(`Collection "${collection.path}" field "${fieldPath}" has invalid \`upload.location\` ` +
+                `${JSON.stringify(location)}: ${reason}`);
+        };
+        if (typeof location !== 'string' || location.length === 0) {
+            fail('must be a non-empty string.');
+        }
+        if (location.startsWith('/') || location.endsWith('/')) {
+            fail('must not start or end with a slash.');
+        }
+        const segments = location.split('/');
+        for (const segment of segments) {
+            if (segment.length === 0) {
+                fail('must not contain duplicate slashes.');
+            }
+            if (segment === '.' || segment === '..') {
+                fail('must not contain `.` or `..` segments.');
+            }
+            if (!/^[A-Za-z0-9._-]+$/.test(segment)) {
+                fail(`segment "${segment}" contains unsupported characters (allowed: A–Z a–z 0–9 . _ -).`);
+            }
+        }
+    });
+}

package/dist/config/validate-collections.test.node.js

@@ -452,4 +452,64 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).toThrow(/listSearch.*virtual/s);
     });
+    // upload.location — declarative storage-key scope shape.
+    const withLocation = (location) => ({
+        ...baseCollection,
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'cover', label: 'Cover', type: 'image', optional: true, upload: { location } },
+        ],
+    });
+    it('accepts a single-segment upload.location', () => {
+        expect(() => validateCollections([withLocation('covers')])).not.toThrow();
+    });
+    it('accepts a nested upload.location', () => {
+        expect(() => validateCollections([withLocation('publications/covers')])).not.toThrow();
+    });
+    it('rejects an empty upload.location', () => {
+        expect(() => validateCollections([withLocation('')])).toThrow(/non-empty string/);
+    });
+    it('rejects a leading slash in upload.location', () => {
+        expect(() => validateCollections([withLocation('/covers')])).toThrow(/must not start or end with a slash/);
+    });
+    it('rejects a trailing slash in upload.location', () => {
+        expect(() => validateCollections([withLocation('covers/')])).toThrow(/must not start or end with a slash/);
+    });
+    it('rejects duplicate slashes in upload.location', () => {
+        expect(() => validateCollections([withLocation('a//b')])).toThrow(/must not contain duplicate slashes/);
+    });
+    it('rejects dot segments in upload.location', () => {
+        expect(() => validateCollections([withLocation('a/../b')])).toThrow(/must not contain `\.` or `\.\.` segments/);
+    });
+    it('rejects unsupported characters in upload.location', () => {
+        expect(() => validateCollections([withLocation('news attachments')])).toThrow(/unsupported characters/);
+    });
+    it('validates upload.location on fields nested inside blocks', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'content',
+                    label: 'Content',
+                    type: 'blocks',
+                    blocks: [
+                        {
+                            blockType: 'attachmentsBlock',
+                            fields: [
+                                {
+                                    name: 'file',
+                                    label: 'File',
+                                    type: 'file',
+                                    optional: true,
+                                    upload: { location: 'bad//path' },
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/content\.file.*must not contain duplicate slashes/s);
+    });
 });

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
@@ -18,5 +18,6 @@ export * from './services/index.js';
 export * from './storage/index.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, type SlugifierFn, type SlugifyContext, slugify, } from './utils/slugify.js';
+export { type FilenameSlugifierFn, type FilenameSlugifyContext, resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
@@ -34,5 +34,6 @@ export * from './services/index.js';
 export * from './storage/index.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, slugify, } from './utils/slugify.js';
+export { resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/schemas/zod/builder.js

@@ -109,6 +109,17 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = textAreaSchema;
             break;
         }
+        case 'code': {
+            let codeSchema = z.string();
+            if (field.validation?.minLength) {
+                codeSchema = codeSchema.min(field.validation.minLength);
+            }
+            if (field.validation?.maxLength) {
+                codeSchema = codeSchema.max(field.validation.maxLength);
+            }
+            schema = codeSchema;
+            break;
+        }
         case 'integer':
             schema = z.number().int();
             break;

package/dist/services/build-search-document.js

@@ -122,7 +122,11 @@ function withBoost(field, decl) {
     const boost = typeof decl === 'string' ? undefined : decl.boost;
     return boost != null ? { ...field, boost } : field;
 }
-/** Text-bearing scalar leaves collected when walking into a container field. */
+/**
+ * Text-bearing scalar leaves collected when walking into a container field.
+ * `code` is deliberately excluded — source snippets are full-text noise
+ * (identifiers, punctuation) that would pollute the index.
+ */
 const TEXT_LEAF_TYPES = new Set(['text', 'textArea']);
 /**
  * Resolve a single `search.body` field to its searchable text. A scalar /

package/dist/services/document-to-markdown.js

@@ -154,6 +154,16 @@ function serializeField(field, value, ctx, level) {
             // toggles (constrainedWidth, featured) and json/object is
             // machine-shaped — the export renders content, not configuration.
             return null;
+        case 'code': {
+            // Fenced code block. The info string uses the schema's static
+            // `language` hint when present; a sibling `languageField` selection is
+            // not resolvable here (this serializer sees one field at a time), so
+            // those fences render bare — still valid markdown.
+            const text = stringValue(value);
+            if (text == null)
+                return null;
+            return `\`\`\`${field.language ?? ''}\n${text}\n\`\`\``;
+        }
         default: {
             const text = stringValue(value);
             return text ? labelled(field, text) : null;

package/dist/services/field-upload.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
+import { type FilenameSlugifierFn } from '../utils/slugify-filename.js';
 import type { CollectionDefinition, IDbAdapter, IStorageProvider, StoredFileLocation, StoredFileValue, UploadConfig } from '../@types/index.js';
 import type { BylineLogger } from '../lib/logger.js';
 import type { SlugifierFn } from '../utils/slugify.js';
@@ -67,6 +68,12 @@ export interface FieldUploadContext {
     defaultLocale: string;
     /** Optional installation slugifier, forwarded to the lifecycle context. */
     slugifier?: SlugifierFn;
+    /**
+     * Optional installation filename slugifier
+     * (`ServerConfig.uploads.filenameSlugifier`), applied to the uploaded base
+     * name before the `beforeStore` chain. Defaults to `slugifyFilename`.
+     */
+    filenameSlugifier?: FilenameSlugifierFn;
     /**
      * Request-scoped auth context. Forwarded to the internal
      * `DocumentLifecycleContext` when an upload creates a document, and

package/dist/services/field-upload.js

@@ -9,6 +9,7 @@ import { resolveUploadHooks } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
+import { resolveUploadFilename } from '../utils/slugify-filename.js';
 import { createDocument } from './document-lifecycle/index.js';
 function isMimeTypeAllowed(mimeType, allowedTypes) {
     return allowedTypes.some((allowed) => {
@@ -21,17 +22,6 @@ function isMimeTypeAllowed(mimeType, allowedTypes) {
         return allowed === mimeType;
     });
 }
-function sanitiseFilename(filename) {
-    const lastDot = filename.lastIndexOf('.');
-    const ext = lastDot !== -1 ? filename.slice(lastDot).toLowerCase() : '';
-    const base = lastDot !== -1 ? filename.slice(0, lastDot) : filename;
-    const safe = base
-        .toLowerCase()
-        .replace(/[^a-z0-9._-]/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '');
-    return `${safe || 'file'}${ext}`;
-}
 /**
  * Walk a field set (recursing into `group` / `array` / `blocks`) and
  * locate the `image | file` field with the given name. Returns the
@@ -73,7 +63,7 @@ function normalizeUploadHook(hook) {
  *
  *   - return a string or `{ filename }` to substitute a new filename;
  *   - return `{ storagePath }` to take full control of the storage key
- *     (bypasses provider key derivation — no UUID prefix). When set
+ *     (bypasses provider key derivation — no entropy suffix). When set
  *     without `filename`, the filename defaults to the path's basename;
  *   - return `{ error }` to short-circuit with `ERR_VALIDATION`;
  *   - return `void` / `undefined` to leave current values unchanged.
@@ -182,7 +172,14 @@ export async function uploadField(ctx, params) {
         //    was supplied at the upload entry we hand them an empty one
         //    rather than throw — `assertActorCanPerform` is the auth gate
         //    for whether the upload should run at all, not the hook layer.
-        const sanitised = sanitiseFilename(originalFilename || 'upload');
+        //    The filename is slugified first (installation
+        //    `uploads.filenameSlugifier`, else the default) so hooks observe
+        //    the storage-ready base name.
+        const sanitised = resolveUploadFilename(originalFilename || 'upload', ctx.filenameSlugifier, {
+            collectionPath,
+            fieldName,
+            mimeType,
+        });
         // Resolve the field's upload hooks once. The loader form
         // (`hooks: () => import('./media.hooks.js')`) keeps server-only hook
         // graphs out of the client bundle; the inline form returns as-is.
@@ -216,6 +213,11 @@ export async function uploadField(ctx, params) {
                 mimeType,
                 size: fileSize,
                 collection: collectionPath,
+                // Declarative storage-key scope (`upload.location`). Providers use
+                // it in place of the collection default while keeping their own
+                // entropy + sanitisation. An explicit hook `storagePath` still wins
+                // (targetStoragePath is written verbatim, below).
+                ...(upload.location !== undefined && { location: upload.location }),
                 ...(effectiveStoragePath !== undefined && { targetStoragePath: effectiveStoragePath }),
             });
         }

package/dist/services/field-upload.test.node.js

@@ -333,7 +333,7 @@ describe('uploadField service', () => {
             fileSize: 3,
             shouldCreateDocument: false,
         });
-        // Explicit key is handed to the provider verbatim — no UUID prefix,
+        // Explicit key is handed to the provider verbatim — no entropy suffix,
         // no collection-derived key.
         expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
             targetStoragePath: 'publications/forru-0000447-0001-en.png',

package/dist/services/populate.d.ts

@@ -25,7 +25,7 @@
  * documents. The guard is in place from day one so that the hook work
  * in Phase 4+ cannot reintroduce the problem.
  *
- * See docs/04-collections/02-relationships.md for the full design rationale.
+ * See docs/04-collections/03-relationships.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

package/dist/services/populate.js

@@ -25,7 +25,7 @@
  * documents. The guard is in place from day one so that the hook work
  * in Phase 4+ cannot reintroduce the problem.
  *
- * See docs/04-collections/02-relationships.md for the full design rationale.
+ * See docs/04-collections/03-relationships.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

package/dist/storage/collection-fingerprint.js

@@ -62,6 +62,10 @@ function canonicalField(field) {
             return base;
         case 'text':
         case 'textArea':
+        // `code` folds in `validation` only — `language` / `languageField` are
+        // presentation hints for the admin editor and never affect the stored
+        // value's shape, so (like labels) they stay out of the fingerprint.
+        case 'code':
         case 'richText':
         case 'float':
         case 'integer':
@@ -86,6 +90,11 @@ function canonicalUpload(u) {
         out.mimeTypes = [...u.mimeTypes].sort();
     if (u.maxFileSize !== undefined)
         out.maxFileSize = u.maxFileSize;
+    // Storage-key scope: where new uploads land is part of the field's
+    // storage contract (existing objects never move on change, but the
+    // declaration itself is schema-shape).
+    if (u.location !== undefined)
+        out.location = u.location;
     if (u.sizes !== undefined) {
         out.sizes = u.sizes
             .map((s) => ({

package/dist/storage/field-store-map.js

@@ -28,6 +28,7 @@ export const fieldTypeToStore = {
     // Text store
     text: { storeType: 'text', valueColumn: 'value' },
     textArea: { storeType: 'text', valueColumn: 'value' },
+    code: { storeType: 'text', valueColumn: 'value' },
     select: { storeType: 'text', valueColumn: 'value' },
     // Numeric store
     integer: { storeType: 'numeric', valueColumn: 'value_integer' },

package/dist/storage/field-store-map.test.node.js

@@ -18,6 +18,7 @@ import { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './fiel
 const VALUE_FIELD_TYPES = [
     'text',
     'textArea',
+    'code',
     'select',
     'integer',
     'float',