@byline/core 3.17.1 → 3.19.0

package/dist/@types/collection-types.d.ts

@@ -132,6 +132,52 @@ export interface UploadConfig {
      * @see UploadHooks
      */
     hooks?: UploadHooks | UploadHooksLoader;
+    /**
+     * Form-value paths the admin upload executor resolves at submit time and
+     * posts alongside the file, so server-side `beforeStore` / `afterStore`
+     * hooks receive document context in `ctx.fields` (always strings —
+     * multipart form values arrive untyped).
+     *
+     * Paths use filesystem-style resolution relative to the upload field's
+     * containing scope. For a field at `files[2].filesGroup.publicationFile`:
+     *
+     *   - `'language'` (bare / `./`) → sibling: `files[2].filesGroup.language`
+     *   - `'../label'` → one level up: `files[2].label`
+     *   - `'/serialNumber'` → document root: `serialNumber`
+     *
+     * Each resolved value is posted under the path's **leaf name** (`language`,
+     * `serialNumber`); when two context paths share a leaf name the later
+     * declaration wins. Serialisation: strings pass through; numbers/booleans
+     * are stringified; relation envelopes post their `targetDocumentId`
+     * (hasMany: comma-joined); `null`/`undefined` values are omitted; anything
+     * else is JSON-stringified.
+     *
+     * Independent of `context`, the executor always posts `documentId` (edit
+     * mode only — absent while the document is unsaved) and `fieldPath` (the
+     * full form path of the upload field, e.g.
+     * `files[2].filesGroup.publicationFile`).
+     *
+     * Hooks must treat all of these as **client-supplied claims** and re-verify
+     * anything security- or integrity-relevant server-side (e.g. fetch the
+     * document by `documentId` rather than trusting a posted serial).
+     */
+    context?: string[];
+    /**
+     * When `true`, the admin renders a "save this document first" notice in
+     * place of the upload widget until the document has been persisted (i.e.
+     * the form is in edit mode with a document id). Existing stored values
+     * still render normally — only the *upload* affordance is gated.
+     *
+     * Use this when server-side upload hooks depend on state that exists only
+     * after the first save — allocator-assigned `counter` fields, the document
+     * id itself — e.g. a `beforeStore` hook that derives the storage key from
+     * the document's serial number.
+     *
+     * Admin-side UX only: API callers can still upload without a document.
+     * Enforce the invariant server-side in a `beforeStore` hook (reject with
+     * `{ error }` when the required context is missing).
+     */
+    requireSavedDocument?: boolean;
 }
 /**
  * The three status names that every workflow must contain.
@@ -141,9 +187,9 @@ export interface UploadConfig {
  *
  *   `[draft, ...customStatuses, published, archived]`
  */
-export declare const WORKFLOW_STATUS_DRAFT: "draft";
-export declare const WORKFLOW_STATUS_PUBLISHED: "published";
-export declare const WORKFLOW_STATUS_ARCHIVED: "archived";
+export declare const WORKFLOW_STATUS_DRAFT: 'draft';
+export declare const WORKFLOW_STATUS_PUBLISHED: 'published';
+export declare const WORKFLOW_STATUS_ARCHIVED: 'archived';
 export declare const REQUIRED_WORKFLOW_STATUSES: readonly ["draft", "published", "archived"];
 export type RequiredWorkflowStatusName = (typeof REQUIRED_WORKFLOW_STATUSES)[number];
 /**
@@ -520,7 +566,19 @@ export interface TreeChangeContext {
  *
  *   - Rename the file by returning a string or `{ filename }`. The
  *     override is threaded into `storage.upload(...)`, so generated
- *     image variants automatically inherit the new prefix.
+ *     image variants automatically inherit the new prefix. The storage
+ *     provider still derives the final key (e.g. local storage prefixes
+ *     `<collection>/<uuid>-` for collision avoidance).
+ *   - Take **full control of the storage key** by returning
+ *     `{ storagePath }` — a fully-qualified, POSIX-style path (no
+ *     leading slash) that is threaded into `storage.upload(...)` as
+ *     `targetStoragePath` and written **verbatim**: no UUID prefix, no
+ *     collection namespace, no provider rewriting. The hook assumes
+ *     responsibility for sanitisation and collision avoidance (see
+ *     `UploadFileOptions.targetStoragePath`). Generated image variants
+ *     derive their sibling paths from the custom original. When
+ *     `storagePath` is returned without `filename`, the stored
+ *     `filename` defaults to the path's basename.
  *   - Reject the upload by returning `{ error }`. Surfaces as
  *     `ERR_VALIDATION` with the supplied message; no file is written,
  *     no variants are generated, no document is created, no later
@@ -529,7 +587,8 @@ export interface TreeChangeContext {
  *
  * When configured as an array, hooks fold: each function receives the
  * filename returned by the previous function (or the original sanitised
- * filename if the previous returned `void`).
+ * filename if the previous returned `void`), and `ctx.storagePath`
+ * carries the most recent explicit storage-path override (if any).
  */
 export interface BeforeStoreContext {
     /** Name of the image/file field receiving this upload. */
@@ -538,6 +597,12 @@ export interface BeforeStoreContext {
     field: ImageField | FileField;
     /** Sanitised default filename. Hooks may override. */
     filename: string;
+    /**
+     * Explicit storage-path override set by an earlier hook in the chain
+     * (via `{ storagePath }`), if any. `undefined` means the storage
+     * provider will derive the key itself from `filename` + `collection`.
+     */
+    storagePath?: string;
     mimeType: string;
     fileSize: number;
     /**
@@ -550,22 +615,37 @@ export interface BeforeStoreContext {
     collectionPath: string;
     /** Authenticated request context. `actor.id`, `actor.tenantId`, etc. for prefixing. */
     requestContext: RequestContext;
+    /**
+     * The storage provider this upload will be written to (the field's
+     * `upload.storage` or the site-wide default). Lets hooks feature-detect
+     * and use the optional provider capabilities — e.g. `storage.exists?.(key)`
+     * to collision-check an explicit `{ storagePath }` before claiming it.
+     */
+    storage: IStorageProvider;
 }
 /**
  * Result returned by a `beforeStore` hook.
  *
  *   - `string`            → override filename (shorthand).
- *   - `{ filename }`      → override filename (object form).
+ *   - `{ filename }`      → override filename (object form). The storage
+ *                           provider still derives the final key.
+ *   - `{ storagePath }`   → take full control of the storage key: written
+ *                           verbatim via `UploadFileOptions.targetStoragePath`
+ *                           (no UUID prefix / provider rewriting). May be
+ *                           combined with `filename`; without it, the stored
+ *                           filename defaults to the path's basename.
  *   - `{ error }`         → reject the upload; surfaces as
  *                           `ERR_VALIDATION`. Short-circuits the chain.
  *   - `void` / undefined  → keep current defaults.
  */
 export type BeforeStoreResult = string | {
     filename?: string;
+    storagePath?: string;
     error?: undefined;
 } | {
     error: string;
     filename?: undefined;
+    storagePath?: undefined;
 } | void;
 /**
  * A `beforeStore` hook function. Async-capable.
@@ -595,6 +675,11 @@ export interface AfterStoreContext {
     fields: Record<string, string>;
     collectionPath: string;
     requestContext: RequestContext;
+    /**
+     * The storage provider the file was written to. See
+     * {@link BeforeStoreContext.storage}.
+     */
+    storage: IStorageProvider;
 }
 /** An `afterStore` hook function. Async-capable. */
 export type AfterStoreHookFn = (ctx: AfterStoreContext) => void | Promise<void>;

package/dist/@types/db-types.d.ts

@@ -424,6 +424,32 @@ export interface ICounterCommands {
      * and deletes. The facet-URL use case does not require gapless IDs.
      */
     nextCounterValue(groupName: string): Promise<number>;
+    /**
+     * Atomically allocate the next value from a **runtime-scoped** counter
+     * group, self-registering the group on first use.
+     *
+     * The schema-declared counter mechanism above is deliberately static:
+     * groups come from `CounterField.group` strings, are discovered and
+     * registered once at boot, and `nextCounterValue` throws for anything
+     * unregistered — that honesty catches configuration bugs. But some
+     * sequences are keyed on *data* that only exists at runtime — e.g. a
+     * per-document sub-sequence like "files attached to publication X",
+     * where each value must be unique and never reused within that scope
+     * (`publications:<documentId>:files` → 1, 2, 3, …). Those scopes cannot
+     * be known at boot, so this method performs an idempotent
+     * ensure-then-allocate instead of throwing on the first use.
+     *
+     * Semantics are otherwise identical to `nextCounterValue`: values are
+     * monotonic per scope and never reused (a Postgres SEQUENCE per scope
+     * in the Postgres adapter); gaps are expected on rolled-back or
+     * abandoned work.
+     *
+     * Callers own the scope-name namespace. Use a stable, collision-proof
+     * convention — `'<collectionPath>:<documentId>:<purpose>'` is
+     * recommended — and never derive scope names from mutable data
+     * (renaming a scope starts a fresh sequence at 1).
+     */
+    nextScopedCounterValue(scopeName: string): Promise<number>;
 }
 export interface ICollectionCommands {
     /**

package/dist/@types/site-config.d.ts

@@ -144,6 +144,24 @@ export type TranslationBundleShape = Readonly<{
 export interface ClientConfig extends BaseConfig {
     /** Admin UI configuration for collections (client-side only). */
     admin?: CollectionAdminConfig[];
+    /**
+     * Installation-wide slugifier — the **client-side** copy, used by the
+     * admin path-widget to render the live `path` preview (create-mode
+     * placeholder and the "Regenerate" target) as the editor types.
+     *
+     * Must be the *same* pure, synchronous function registered on
+     * `ServerConfig.slugifier`: the server derivation is authoritative, and a
+     * divergent client copy would show a preview that disagrees with what is
+     * persisted (and could let "Regenerate" overwrite a correct path). Falls
+     * back to the default `slugify` from `@byline/core` when not set — so
+     * installations that keep the default slugifier need not set this at all.
+     *
+     * Lives on `ClientConfig` rather than `BaseConfig` because it is a function
+     * (not serialisable), and `BaseConfig` is contractually serialisable.
+     *
+     * @see ServerConfig.slugifier
+     */
+    slugifier?: SlugifierFn;
     /**
      * Site-wide field-level UI defaults. Currently surfaces the richtext
      * editor adapter slot — additional field-level defaults (custom
@@ -214,6 +232,11 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      * Falls back to the default `slugify` from `@byline/core` when not set.
      * Must be pure and synchronous — it runs server-side at write time and
      * client-side for live form preview, and the two must agree on output.
+     *
+     * This is the **server-side** copy (the authoritative one — its output is
+     * what gets persisted). For the admin path-widget's live preview to match,
+     * register the *same* function on `ClientConfig.slugifier` via
+     * `defineClientConfig`. See {@link ClientConfig.slugifier}.
      */
     slugifier?: SlugifierFn;
     /**

package/dist/@types/storage-types.d.ts

@@ -97,4 +97,25 @@ export interface IStorageProvider {
      * signing logic here.
      */
     getUrl(storagePath: string): string;
+    /**
+     * Move (re-key) a previously stored file from one `storage_path` to
+     * another, returning the new location metadata. The destination path is
+     * written verbatim — same contract as `UploadFileOptions.targetStoragePath`
+     * (POSIX-style, no leading slash; the caller owns sanitisation and
+     * collision avoidance). Throws if the source does not exist.
+     *
+     * **Optional capability** — both first-party providers (`storage-local`,
+     * `storage-s3`) implement it, but custom providers may not. Callers must
+     * feature-detect (`if (storage.move) …`) before relying on it.
+     */
+    move?(fromPath: string, toPath: string): Promise<StoredFileLocation>;
+    /**
+     * Report whether a file exists at the given `storage_path`. Useful for
+     * collision checks when callers (e.g. `beforeStore` hooks assigning
+     * explicit storage keys via `{ storagePath }`) need to guarantee a key
+     * is free before claiming it.
+     *
+     * **Optional capability** — see `move`.
+     */
+    exists?(storagePath: string): Promise<boolean>;
 }

package/dist/auth/register-collection-abilities.d.ts

@@ -36,7 +36,7 @@ import type { CollectionDefinition } from '../@types/index.js';
  */
 export declare function registerCollectionAbilities(registry: AbilityRegistry, definition: CollectionDefinition): void;
 /** The ability suffixes that every collection contributes. Exposed for contract tests. */
-export declare const COLLECTION_ABILITY_VERBS: readonly ["read", "create", "update", "delete", "publish", "changeStatus", "reindex"];
+export declare const COLLECTION_ABILITY_VERBS: readonly ['read', 'create', 'update', 'delete', 'publish', 'changeStatus', 'reindex'];
 export type CollectionAbilityVerb = (typeof COLLECTION_ABILITY_VERBS)[number];
 /** Compute the full ability key for a collection path and verb. */
 export declare function collectionAbilityKey(path: string, verb: CollectionAbilityVerb): string;

package/dist/config/config.js

@@ -90,6 +90,10 @@ export function getClientConfig() {
             routes: serverConfig.routes,
             collections: serverConfig.collections,
             admin: [],
+            // Carry the slugifier through the SSR fallback so a form rendered
+            // server-side derives the same path preview as the hydrated client
+            // (both configs are meant to register the same function).
+            slugifier: serverConfig.slugifier,
         };
     }
     throw new Error('Byline has not been configured yet. Please call defineClientConfig in byline.config.ts first.');

package/dist/config/validate-collections.d.ts

@@ -23,7 +23,8 @@ export declare const RESERVED_FIELD_NAMES: ReadonlySet<string>;
  *    into derived paths via `useAsPath`.
  *  - When `useAsPath` is set, the referenced field must exist at the
  *    top level of the collection and be of a type the slugifier can
- *    sensibly consume (text-like or date-like).
+ *    sensibly consume (text-like, date-like, or a numeric identity
+ *    field — `integer` / `counter`).
  *  - No field may be named `availableLocales`; collections opt into the
  *    editorial available-locales control via `advertiseLocales: true`.
  *  - When `advertiseLocales` is `true`, the collection must have at least

package/dist/config/validate-collections.js

@@ -28,6 +28,14 @@ const USE_AS_PATH_SOURCE_TYPES = new Set([
     'date',
     'datetime',
     'time',
+    // Numeric identity fields. `derivePath` stringifies the value before
+    // slugifying, so an integer or an allocator-assigned `counter` becomes a
+    // clean numeric slug (e.g. `1`, `42`). A replacement slugifier can branch
+    // on `collectionPath` to reshape it further — e.g. zero-padding a serial
+    // number to a fixed width. `float` / `decimal` are deliberately excluded:
+    // their string form carries a `.` which does not belong in a path segment.
+    'integer',
+    'counter',
 ]);
 /**
  * True when any field in the tree (at any nesting depth) is `localized`.
@@ -65,7 +73,8 @@ function walkFields(fields, visit) {
  *    into derived paths via `useAsPath`.
  *  - When `useAsPath` is set, the referenced field must exist at the
  *    top level of the collection and be of a type the slugifier can
- *    sensibly consume (text-like or date-like).
+ *    sensibly consume (text-like, date-like, or a numeric identity
+ *    field — `integer` / `counter`).
  *  - No field may be named `availableLocales`; collections opt into the
  *    editorial available-locales control via `advertiseLocales: true`.
  *  - When `advertiseLocales` is `true`, the collection must have at least

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

@@ -87,6 +87,28 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).not.toThrow();
     });
+    it('accepts useAsPath pointing at a counter field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'serialNumber', label: 'Serial Number', type: 'counter', group: 'serials' },
+            ],
+            useAsPath: 'serialNumber',
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('accepts useAsPath pointing at an integer field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'issue', label: 'Issue', type: 'integer' },
+            ],
+            useAsPath: 'issue',
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
     // useAsPath deliberately resolves against top-level fields only. A
     // nested source (inside a group, array, or block) isn't addressable
     // in the derivation cascade — path is a singular identity anchor, not

package/dist/lib/errors.d.ts

@@ -76,17 +76,17 @@ export declare class BylineError extends Error {
  */
 export declare const createErrorType: (code: string, logLevel?: LogLevel) => (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ErrorCodes: {
-    readonly UNHANDLED: "ERR_UNHANDLED";
-    readonly NOT_FOUND: "ERR_NOT_FOUND";
-    readonly CONFLICT: "ERR_CONFLICT";
-    readonly VALIDATION: "ERR_VALIDATION";
-    readonly INVALID_TRANSITION: "ERR_INVALID_TRANSITION";
-    readonly PATCH_FAILED: "ERR_PATCH_FAILED";
-    readonly DATABASE: "ERR_DATABASE";
-    readonly STORAGE: "ERR_STORAGE";
-    readonly READ_BUDGET_EXCEEDED: "ERR_READ_BUDGET_EXCEEDED";
-    readonly PATH_CONFLICT: "ERR_PATH_CONFLICT";
-    readonly AUDIT_UNSUPPORTED: "ERR_AUDIT_UNSUPPORTED";
+    readonly UNHANDLED: 'ERR_UNHANDLED';
+    readonly NOT_FOUND: 'ERR_NOT_FOUND';
+    readonly CONFLICT: 'ERR_CONFLICT';
+    readonly VALIDATION: 'ERR_VALIDATION';
+    readonly INVALID_TRANSITION: 'ERR_INVALID_TRANSITION';
+    readonly PATCH_FAILED: 'ERR_PATCH_FAILED';
+    readonly DATABASE: 'ERR_DATABASE';
+    readonly STORAGE: 'ERR_STORAGE';
+    readonly READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED';
+    readonly PATH_CONFLICT: 'ERR_PATH_CONFLICT';
+    readonly AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED';
 };
 export declare const ERR_UNHANDLED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_NOT_FOUND: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;

package/dist/patches/apply-patches.js

@@ -46,7 +46,7 @@ export function resolveFieldForPath(definition, path) {
     if (segments.length === 0)
         return null;
     const [first, ...rest] = segments;
-    if (!first || first.kind !== 'field')
+    if (first?.kind !== 'field')
         return null;
     let current = definition.fields.find((f) => f.name === first.key);
     if (!current)

package/dist/schemas/zod/builder.d.ts

@@ -53,9 +53,6 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
     }, z.core.$strip>;
     full: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
@@ -68,12 +65,12 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         updatedAt: z.ZodISODateTime;
         createdBy: z.ZodOptional<z.ZodUUID>;
         eventType: z.ZodOptional<z.ZodString>;
+        fields: z.ZodObject<{
+            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+        }, z.core.$strip>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
@@ -86,6 +83,9 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             updatedAt: z.ZodISODateTime;
             createdBy: z.ZodOptional<z.ZodUUID>;
             eventType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodObject<{
+                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+            }, z.core.$strip>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -108,9 +108,6 @@ export declare const createCollectionSchemasForPath: (path: string) => {
     }, z.core.$strip>;
     history: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
@@ -123,6 +120,9 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             updatedAt: z.ZodISODateTime;
             createdBy: z.ZodOptional<z.ZodUUID>;
             eventType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodObject<{
+                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+            }, z.core.$strip>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -137,9 +137,6 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
     }, z.core.$strip>;
     get: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
@@ -152,6 +149,9 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         updatedAt: z.ZodISODateTime;
         createdBy: z.ZodOptional<z.ZodUUID>;
         eventType: z.ZodOptional<z.ZodString>;
+        fields: z.ZodObject<{
+            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+        }, z.core.$strip>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -176,93 +176,6 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
     }, z.core.$strip>;
     full: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    list: z.ZodObject<{
-        docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
-            id: z.ZodUUID;
-            versionId: z.ZodOptional<z.ZodUUID>;
-            path: z.ZodOptional<z.ZodString>;
-            sourceLocale: z.ZodOptional<z.ZodString>;
-            status: z.ZodEnum<{
-                [x: string]: string;
-            }>;
-            hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-            createdAt: z.ZodISODateTime;
-            updatedAt: z.ZodISODateTime;
-            createdBy: z.ZodOptional<z.ZodUUID>;
-            eventType: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-        meta: z.ZodObject<{
-            page: z.ZodNumber;
-            pageSize: z.ZodNumber;
-            total: z.ZodNumber;
-            totalPages: z.ZodNumber;
-            order: z.ZodOptional<z.ZodString>;
-            desc: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>;
-        included: z.ZodObject<{
-            collection: z.ZodObject<{
-                id: z.ZodString;
-                labels: z.ZodObject<{
-                    singular: z.ZodString;
-                    plural: z.ZodString;
-                }, z.core.$strip>;
-                path: z.ZodLiteral<string>;
-            }, z.core.$strip>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    history: z.ZodObject<{
-        docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
-            id: z.ZodUUID;
-            versionId: z.ZodOptional<z.ZodUUID>;
-            path: z.ZodOptional<z.ZodString>;
-            sourceLocale: z.ZodOptional<z.ZodString>;
-            status: z.ZodEnum<{
-                [x: string]: string;
-            }>;
-            hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-            createdAt: z.ZodISODateTime;
-            updatedAt: z.ZodISODateTime;
-            createdBy: z.ZodOptional<z.ZodUUID>;
-            eventType: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-        meta: z.ZodObject<{
-            page: z.ZodNumber;
-            pageSize: z.ZodNumber;
-            total: z.ZodNumber;
-            totalPages: z.ZodNumber;
-            order: z.ZodOptional<z.ZodString>;
-            desc: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    create: z.ZodObject<{
-        [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-    }, z.core.$strip>;
-    get: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
@@ -275,88 +188,12 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         updatedAt: z.ZodISODateTime;
         createdBy: z.ZodOptional<z.ZodUUID>;
         eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    update: z.ZodObject<{
-        [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
-    }, z.core.$strip>;
-};
-export declare const createTypedCollectionSchemas: (collection: CollectionDefinition) => {
-    base: z.ZodObject<{
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    fields: z.ZodObject<{
-        [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-    }, z.core.$strip>;
-    full: z.ZodObject<{
         fields: z.ZodObject<{
             [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
         }, z.core.$strip>;
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
-            id: z.ZodUUID;
-            versionId: z.ZodOptional<z.ZodUUID>;
-            path: z.ZodOptional<z.ZodString>;
-            sourceLocale: z.ZodOptional<z.ZodString>;
-            status: z.ZodEnum<{
-                [x: string]: string;
-            }>;
-            hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-            createdAt: z.ZodISODateTime;
-            updatedAt: z.ZodISODateTime;
-            createdBy: z.ZodOptional<z.ZodUUID>;
-            eventType: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-        meta: z.ZodObject<{
-            page: z.ZodNumber;
-            pageSize: z.ZodNumber;
-            total: z.ZodNumber;
-            totalPages: z.ZodNumber;
-            order: z.ZodOptional<z.ZodString>;
-            desc: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>;
-        included: z.ZodObject<{
-            collection: z.ZodObject<{
-                id: z.ZodString;
-                labels: z.ZodObject<{
-                    singular: z.ZodString;
-                    plural: z.ZodString;
-                }, z.core.$strip>;
-                path: z.ZodLiteral<string>;
-            }, z.core.$strip>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    history: z.ZodObject<{
-        docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
@@ -369,92 +206,9 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             updatedAt: z.ZodISODateTime;
             createdBy: z.ZodOptional<z.ZodUUID>;
             eventType: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-        meta: z.ZodObject<{
-            page: z.ZodNumber;
-            pageSize: z.ZodNumber;
-            total: z.ZodNumber;
-            totalPages: z.ZodNumber;
-            order: z.ZodOptional<z.ZodString>;
-            desc: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    create: z.ZodObject<{
-        [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-    }, z.core.$strip>;
-    get: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    update: z.ZodObject<{
-        [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
-    }, z.core.$strip>;
-};
-export declare const createTypedCollectionSchemasForPath: (path: string) => {
-    base: z.ZodObject<{
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    fields: z.ZodObject<{
-        [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-    }, z.core.$strip>;
-    full: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
-        id: z.ZodUUID;
-        versionId: z.ZodOptional<z.ZodUUID>;
-        path: z.ZodOptional<z.ZodString>;
-        sourceLocale: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            [x: string]: string;
-        }>;
-        hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-        createdBy: z.ZodOptional<z.ZodUUID>;
-        eventType: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    list: z.ZodObject<{
-        docs: z.ZodArray<z.ZodObject<{
             fields: z.ZodObject<{
                 [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
             }, z.core.$strip>;
-            id: z.ZodUUID;
-            versionId: z.ZodOptional<z.ZodUUID>;
-            path: z.ZodOptional<z.ZodString>;
-            sourceLocale: z.ZodOptional<z.ZodString>;
-            status: z.ZodEnum<{
-                [x: string]: string;
-            }>;
-            hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
-            createdAt: z.ZodISODateTime;
-            updatedAt: z.ZodISODateTime;
-            createdBy: z.ZodOptional<z.ZodUUID>;
-            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -477,9 +231,6 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
     }, z.core.$strip>;
     history: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
-            fields: z.ZodObject<{
-                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-            }, z.core.$strip>;
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
@@ -492,6 +243,9 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             updatedAt: z.ZodISODateTime;
             createdBy: z.ZodOptional<z.ZodUUID>;
             eventType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodObject<{
+                [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+            }, z.core.$strip>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -506,9 +260,6 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
     }, z.core.$strip>;
     get: z.ZodObject<{
-        fields: z.ZodObject<{
-            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
-        }, z.core.$strip>;
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
@@ -521,8 +272,13 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         updatedAt: z.ZodISODateTime;
         createdBy: z.ZodOptional<z.ZodUUID>;
         eventType: z.ZodOptional<z.ZodString>;
+        fields: z.ZodObject<{
+            [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+        }, z.core.$strip>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
     }, z.core.$strip>;
 };
+export declare const createTypedCollectionSchemas: typeof createCollectionSchemas;
+export declare const createTypedCollectionSchemasForPath: typeof createCollectionSchemasForPath;

package/dist/schemas/zod/cache.d.ts

@@ -3,8 +3,8 @@ import type { CollectionDefinition } from '../../@types/index.js';
 type TypedSchemaSet = ReturnType<typeof createTypedCollectionSchemas>;
 export declare const getCollectionSchemasForPath: (path: string) => TypedSchemaSet;
 export declare const getCollectionSchemas: (collection: CollectionDefinition) => TypedSchemaSet;
-export declare const getTypedCollectionSchemasForPath: (path: string) => TypedSchemaSet;
-export declare const getTypedCollectionSchemas: (collection: CollectionDefinition) => TypedSchemaSet;
+export declare const getTypedCollectionSchemasForPath: typeof getCollectionSchemasForPath;
+export declare const getTypedCollectionSchemas: typeof getCollectionSchemas;
 export declare const clearSchemaCache: (collectionPath?: string) => void;
 export declare const getCacheStats: () => {
     size: number;

package/dist/services/assign-counter-values.test.node.js

@@ -20,6 +20,7 @@ function makeCounters(start = 1) {
                 calls.push(group);
                 return next++;
             }),
+            nextScopedCounterValue: vi.fn(),
         },
         calls,
     };

package/dist/services/collection-bootstrap.test.node.js

@@ -52,6 +52,7 @@ function createMockDb(options) {
             counters: {
                 ensureCounterGroup: vi.fn(fail),
                 nextCounterValue: vi.fn(fail),
+                nextScopedCounterValue: vi.fn(fail),
             },
         },
         queries: {
@@ -203,6 +204,7 @@ describe('ensureCollections', () => {
                 counters: {
                     ensureCounterGroup: vi.fn(),
                     nextCounterValue: vi.fn(),
+                    nextScopedCounterValue: vi.fn(),
                 },
             },
             queries: {

package/dist/services/discover-counter-groups.test.node.js

@@ -37,6 +37,7 @@ function makeAdapter(options) {
             counters: {
                 ensureCounterGroup,
                 nextCounterValue: vi.fn(fail),
+                nextScopedCounterValue: vi.fn(fail),
             },
         },
         queries: {

package/dist/services/document-lifecycle/audit.d.ts

@@ -9,10 +9,10 @@ import type { AuditActorRealm, AuditLogAppendInput, IDbAdapter } from '../../@ty
 import type { DocumentLifecycleContext } from './context.js';
 /** Namespaced audit actions for document-grain changes. */
 export declare const AUDIT_ACTIONS: {
-    readonly pathChanged: "document.path.changed";
-    readonly localesChanged: "document.locales.changed";
-    readonly statusChanged: "document.status.changed";
-    readonly deleted: "document.deleted";
+    readonly pathChanged: 'document.path.changed';
+    readonly localesChanged: 'document.locales.changed';
+    readonly statusChanged: 'document.status.changed';
+    readonly deleted: 'document.deleted';
 };
 /**
  * The actor id + realm for an audit-log row. Mirrors `actorId()`: a real

package/dist/services/document-lifecycle.test.node.js

@@ -63,6 +63,7 @@ function createMockDb() {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
             audit: { append: auditAppend },
         },

package/dist/services/field-upload.js

@@ -69,18 +69,22 @@ function normalizeUploadHook(hook) {
 }
 /**
  * Run the `beforeStore` chain. Each function receives the previous
- * function's filename override (fold). A function may:
+ * function's filename / storage-path overrides (fold). A function may:
  *
  *   - 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
+ *     without `filename`, the filename defaults to the path's basename;
  *   - return `{ error }` to short-circuit with `ERR_VALIDATION`;
- *   - return `void` / `undefined` to leave the filename unchanged.
+ *   - return `void` / `undefined` to leave current values unchanged.
  *
- * Returns the resolved filename.
+ * Returns the resolved filename and optional storage path.
  */
 async function runBeforeStoreChain(hooks, ctx, logger) {
     let effective = ctx.filename;
+    let effectiveStoragePath;
     for (const fn of hooks) {
-        const result = await fn({ ...ctx, filename: effective });
+        const result = await fn({ ...ctx, filename: effective, storagePath: effectiveStoragePath });
         if (result == null)
             continue;
         if (typeof result === 'string') {
@@ -96,14 +100,35 @@ async function runBeforeStoreChain(hooks, ctx, logger) {
                     details: { collectionPath: ctx.collectionPath, fieldName: ctx.fieldName },
                 }, runBeforeStoreChain).log(logger);
             }
+            let filenameOverridden = false;
             if ('filename' in result && typeof result.filename === 'string') {
                 const trimmed = result.filename.trim();
-                if (trimmed)
+                if (trimmed) {
                     effective = trimmed;
+                    filenameOverridden = true;
+                }
+            }
+            if ('storagePath' in result && typeof result.storagePath === 'string') {
+                // Normalise: POSIX-style, no leading slash (matches the
+                // UploadFileOptions.targetStoragePath contract).
+                const trimmed = result.storagePath.trim().replace(/^\/+/, '');
+                if (trimmed) {
+                    effectiveStoragePath = trimmed;
+                    // Keep the stored filename in sync with the explicit key
+                    // unless the hook also set filename itself.
+                    if (!filenameOverridden) {
+                        effective = posixBasename(trimmed);
+                    }
+                }
             }
         }
     }
-    return effective;
+    return { filename: effective, storagePath: effectiveStoragePath };
+}
+/** Last path segment of a POSIX-style storage path. */
+function posixBasename(storagePath) {
+    const idx = storagePath.lastIndexOf('/');
+    return idx === -1 ? storagePath : storagePath.slice(idx + 1);
 }
 export async function uploadField(ctx, params) {
     return withLogContext({ domain: 'services', module: 'upload', function: 'uploadField' }, async () => {
@@ -163,7 +188,7 @@ export async function uploadField(ctx, params) {
         // graphs out of the client bundle; the inline form returns as-is.
         const uploadHooks = await resolveUploadHooks(upload.hooks);
         const beforeStoreHooks = normalizeUploadHook(uploadHooks?.beforeStore);
-        const effectiveFilename = await runBeforeStoreChain(beforeStoreHooks, {
+        const { filename: effectiveFilename, storagePath: effectiveStoragePath } = await runBeforeStoreChain(beforeStoreHooks, {
             fieldName,
             field,
             filename: sanitised,
@@ -176,9 +201,14 @@ export async function uploadField(ctx, params) {
                 requestId: '',
                 readMode: 'any',
             },
+            storage,
         }, logger);
         // -- Storage write. Filename is the post-hook value, so generated
-        //    variants automatically inherit the new prefix.
+        //    variants automatically inherit the new prefix. An explicit
+        //    `storagePath` from the chain is threaded through as
+        //    `targetStoragePath`, which providers write verbatim (no UUID
+        //    prefix / key derivation) — variants still derive sibling paths
+        //    from the resulting `storedFile.storagePath`.
         let storedFile;
         try {
             storedFile = await storage.upload(buffer, {
@@ -186,6 +216,7 @@ export async function uploadField(ctx, params) {
                 mimeType,
                 size: fileSize,
                 collection: collectionPath,
+                ...(effectiveStoragePath !== undefined && { targetStoragePath: effectiveStoragePath }),
             });
         }
         catch (err) {
@@ -261,6 +292,7 @@ export async function uploadField(ctx, params) {
                         requestId: '',
                         readMode: 'any',
                     },
+                    storage,
                 };
                 await fn(afterCtx);
             }

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

@@ -66,6 +66,7 @@ function createMockDb() {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
         },
         queries: {
@@ -248,6 +249,84 @@ describe('uploadField service', () => {
         });
         expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ filename: 'PUB-42-tenant-hero.png' }));
     });
+    it('beforeStore { storagePath } threads targetStoragePath verbatim and derives the filename from its basename', async () => {
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: () => ({ storagePath: 'publications/forru-0000447-0001-en.png' }),
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        // Explicit key is handed to the provider verbatim — no UUID prefix,
+        // no collection-derived key.
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
+            targetStoragePath: 'publications/forru-0000447-0001-en.png',
+            filename: 'forru-0000447-0001-en.png',
+        }));
+        // Stored filename follows the explicit key's basename.
+        expect(result.storedFile.filename).toBe('forru-0000447-0001-en.png');
+    });
+    it('beforeStore { storagePath, filename } honours both; a leading slash is stripped from the key', async () => {
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: () => ({
+                    storagePath: '/publications/forru-0000447-0002-en.png',
+                    filename: 'display-name.png',
+                }),
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
+            targetStoragePath: 'publications/forru-0000447-0002-en.png',
+            filename: 'display-name.png',
+        }));
+        expect(result.storedFile.filename).toBe('display-name.png');
+    });
+    it('folds storagePath through a chain — later hooks see ctx.storagePath and may override it', async () => {
+        const secondHook = vi.fn(({ storagePath }) => ({
+            storagePath: storagePath.replace('-draft', ''),
+        }));
+        const definition = withFieldUpload(uploadCollection, 'image', (f) => {
+            f.upload.hooks = {
+                beforeStore: [() => ({ storagePath: 'publications/report-draft.png' }), secondHook],
+            };
+        });
+        const { ctx, upload } = buildCtx({ definition });
+        await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(secondHook).toHaveBeenCalledWith(expect.objectContaining({ storagePath: 'publications/report-draft.png' }));
+        expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ targetStoragePath: 'publications/report.png' }));
+    });
+    it('no storagePath override → storage.upload receives no targetStoragePath', async () => {
+        const { ctx, upload } = buildCtx();
+        await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        const options = upload.mock.calls[0]?.[1];
+        expect(options).not.toHaveProperty('targetStoragePath');
+    });
     it('beforeStore { error } short-circuits — no storage write, no variants, no afterStore', async () => {
         const afterStore = vi.fn();
         const definition = withFieldUpload(uploadCollection, 'image', (f) => {

package/dist/services/populate.test.node.js

@@ -154,6 +154,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
             },
         },
         queries: {

package/dist/validation/shared.d.ts

@@ -33,9 +33,9 @@ import { z } from 'zod';
  * this file — emit codes here, translate in `@byline/admin`.
  */
 export declare const PASSWORD_ERROR_CODES: {
-    readonly TOO_SHORT: "password.tooShort";
-    readonly TOO_LONG: "password.tooLong";
-    readonly COMPLEXITY: "password.complexity";
+    readonly TOO_SHORT: 'password.tooShort';
+    readonly TOO_LONG: 'password.tooLong';
+    readonly COMPLEXITY: 'password.complexity';
 };
 /**
  * Standard password policy — 8 to 128 characters, must contain at least

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.17.1",
+  "version": "3.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -74,20 +74,20 @@
   "dependencies": {
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",
-    "sharp": "^0.34.5",
+    "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "3.17.1"
+    "@byline/auth": "3.19.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.15",
-    "@types/node": "^25.9.1",
+    "@biomejs/biome": "2.5.2",
+    "@types/node": "^26.1.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.8.17",
-    "tsx": "^4.22.3",
-    "typescript": "6.0.3",
-    "vitest": "^4.1.7"
+    "tsc-alias": "^1.9.0",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "publishConfig": {
     "access": "public",