@byline/core 6.8.0 → 6.9.0

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

@@ -251,14 +251,14 @@ export interface FormAdminConfig {
  * Admin UI configuration for a collection.
  * This is the presentation/UI layer — separate from the data schema.
  *
- * Linked to a `CollectionDefinition` by `slug` matching the collection's
+ * Linked to a `CollectionDefinition` by `path` matching the collection's
  * `path`.
  */
 export interface CollectionAdminConfig<T = any> extends FormAdminConfig {
     /** Explicit resource discriminator. Stamped by `defineAdmin`. */
     singleton?: false;
     /** Must match the `path` of the corresponding `CollectionDefinition`. */
-    slug: string;
+    path: string;
     /**
      * Dashboard group this collection belongs to. Must name an entry in
      * `AdminConfig.collectionGroups`; an unknown name throws at startup.
@@ -447,7 +447,7 @@ export interface SingletonAdminConfig<T = any> extends FormAdminConfig {
     /** Explicit resource discriminator. Stamped by `defineSingletonAdmin`. */
     singleton: true;
     /** Must match the `path` of the corresponding `SingletonDefinition`. */
-    slug: string;
+    path: string;
     /**
      * Dashboard group this resource belongs to. The registry remains named
      * `AdminConfig.collectionGroups` for backwards compatibility.
@@ -487,14 +487,14 @@ export interface ListActionComponentProps {
 }
 /**
  * Type-safe factory for creating a `CollectionAdminConfig` linked to a schema.
- * Sets `slug` from the schema's `path`.
+ * Sets `path` from the schema's `path`.
  */
-export declare function defineAdmin<T = any>(schema: MultiCollectionDefinition, config: Omit<CollectionAdminConfig<T>, 'slug' | 'singleton'>): CollectionAdminConfig<T>;
+export declare function defineAdmin<T = any>(schema: MultiCollectionDefinition, config: Omit<CollectionAdminConfig<T>, 'path' | 'singleton'>): CollectionAdminConfig<T>;
 /**
  * Type-safe factory for a `SingletonAdminConfig` linked to a singleton schema.
  * Sets both the schema path and resource discriminator for authors.
  */
-export declare function defineSingletonAdmin<T = any>(schema: SingletonDefinition, config: Omit<SingletonAdminConfig<T>, 'slug' | 'singleton'>): SingletonAdminConfig<T>;
+export declare function defineSingletonAdmin<T = any>(schema: SingletonDefinition, config: Omit<SingletonAdminConfig<T>, 'path' | 'singleton'>): SingletonAdminConfig<T>;
 /**
  * Admin UI configuration for a block — the block-scoped analogue of
  * `CollectionAdminConfig`, carrying **rendering overrides only**.

package/dist/@types/admin-types.js

@@ -7,13 +7,13 @@
  */
 /**
  * Type-safe factory for creating a `CollectionAdminConfig` linked to a schema.
- * Sets `slug` from the schema's `path`.
+ * Sets `path` from the schema's `path`.
  */
 export function defineAdmin(schema, config) {
     return {
         ...config,
         singleton: false,
-        slug: schema.path,
+        path: schema.path,
     };
 }
 /**
@@ -24,7 +24,7 @@ export function defineSingletonAdmin(schema, config) {
     return {
         ...config,
         singleton: true,
-        slug: schema.path,
+        path: schema.path,
     };
 }
 /**

package/dist/@types/form-admin-config.test.node.js

@@ -17,7 +17,7 @@ describe('FormAdminConfig', () => {
     });
     it('is satisfied by a full CollectionAdminConfig', () => {
         const collection = {
-            slug: 'pages',
+            path: 'pages',
             layout: { main: [] },
         };
         const asForm = collection;

package/dist/@types/singleton-admin-config.test.node.js

@@ -24,19 +24,22 @@ describe('singleton admin config', () => {
         const singletonAdmin = defineSingletonAdmin(settings, {});
         expect(collectionAdmin.singleton).toBe(false);
         expect(singletonAdmin.singleton).toBe(true);
-        expect(singletonAdmin.slug).toBe(settings.path);
+        expect(collectionAdmin.path).toBe(pages.path);
+        expect(singletonAdmin.path).toBe(settings.path);
+        expect(collectionAdmin).not.toHaveProperty('slug');
+        expect(singletonAdmin).not.toHaveProperty('slug');
     });
     it('does not let untyped config input override factory-owned identity', () => {
         const collectionAdmin = defineAdmin(pages, {
             singleton: true,
-            slug: 'wrong-collection',
+            path: 'wrong-collection',
         });
         const singletonAdmin = defineSingletonAdmin(settings, {
             singleton: false,
-            slug: 'wrong-singleton',
+            path: 'wrong-singleton',
         });
-        expect(collectionAdmin).toMatchObject({ singleton: false, slug: pages.path });
-        expect(singletonAdmin).toMatchObject({ singleton: true, slug: settings.path });
+        expect(collectionAdmin).toMatchObject({ singleton: false, path: pages.path });
+        expect(singletonAdmin).toMatchObject({ singleton: true, path: settings.path });
     });
     it('shares the reusable form composition contract', () => {
         const singletonAdmin = defineSingletonAdmin(settings, {

package/dist/config/config.d.ts

@@ -11,8 +11,8 @@ import type { AdminConfig, CollectionAdminConfig, CollectionDefinition, Resolved
  * still throw the loud "Byline has not been configured" error.
  */
 export declare const getCollectionDefinition: (path: string) => CollectionDefinition | null;
-export declare const getCollectionAdminConfig: (slug: string) => CollectionAdminConfig | null;
-export declare const getSingletonAdminConfig: (slug: string) => SingletonAdminConfig | null;
+export declare const getCollectionAdminConfig: (path: string) => CollectionAdminConfig | null;
+export declare const getSingletonAdminConfig: (path: string) => SingletonAdminConfig | null;
 export declare function defineAdminConfig(config: AdminConfig): ResolvedAdminConfig;
 export declare function defineServerConfig<TAdminStore = unknown>(config: ServerConfig<TAdminStore>): ResolvedServerConfig<TAdminStore>;
 /** Resolve and validate server config without replacing the registered singleton. */

package/dist/config/config.js

@@ -52,18 +52,18 @@ export const getCollectionDefinition = (path) => {
         return null;
     return config.collections.find((collection) => collection.path === path) ?? null;
 };
-const getAdminResourceConfig = (slug) => {
+const getAdminResourceConfig = (path) => {
     const adminConfig = getAdminConfigInstance();
     if (adminConfig == null)
         return null;
-    return adminConfig.admin?.find((admin) => admin.slug === slug) ?? null;
+    return adminConfig.admin?.find((admin) => admin.path === path) ?? null;
 };
-export const getCollectionAdminConfig = (slug) => {
-    const admin = getAdminResourceConfig(slug);
+export const getCollectionAdminConfig = (path) => {
+    const admin = getAdminResourceConfig(path);
     return admin?.singleton === true ? null : admin;
 };
-export const getSingletonAdminConfig = (slug) => {
-    const admin = getAdminResourceConfig(slug);
+export const getSingletonAdminConfig = (path) => {
+    const admin = getAdminResourceConfig(path);
     return admin?.singleton === true ? admin : null;
 };
 export function defineAdminConfig(config) {

package/dist/config/group-collections.js

@@ -33,7 +33,7 @@ export function groupCollectionsForAdmin(collections, admin, collectionGroups) {
     const groupByCollectionPath = new Map();
     for (const entry of admin ?? []) {
         if (entry.group != null)
-            groupByCollectionPath.set(entry.slug, entry.group);
+            groupByCollectionPath.set(entry.path, entry.group);
     }
     const membersByGroup = new Map();
     for (const group of collectionGroups ?? []) {

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

@@ -29,9 +29,9 @@ const groups = [
     { name: 'taxonomy', label: 'Taxonomies' },
 ];
 const admin = [
-    { slug: 'images', group: 'media' },
-    { slug: 'authors', group: 'authorities' },
-    { slug: 'categories', group: 'taxonomy' },
+    { path: 'images', group: 'media' },
+    { path: 'authors', group: 'authorities' },
+    { path: 'categories', group: 'taxonomy' },
 ];
 describe('groupCollectionsForAdmin', () => {
     it('returns one ungrouped bucket when no registry is declared', () => {
@@ -67,13 +67,13 @@ describe('groupCollectionsForAdmin', () => {
     });
     it('preserves collection declaration order within a bucket', () => {
         const more = define('videos');
-        const result = groupCollectionsForAdmin([more, images], [...admin, { slug: 'videos', group: 'media' }], groups);
+        const result = groupCollectionsForAdmin([more, images], [...admin, { path: 'videos', group: 'media' }], groups);
         expect(result[0]?.collections).toEqual([more, images]);
     });
     it('groups singleton and multi-collection resources together in declaration order', () => {
         const resourceAdmin = [
             ...admin,
-            { singleton: true, slug: settings.path, group: 'media' },
+            { singleton: true, path: settings.path, group: 'media' },
         ];
         const result = groupCollectionsForAdmin([images, settings], resourceAdmin, groups);
         expect(result[0]?.collections).toEqual([images, settings]);
@@ -85,7 +85,7 @@ describe('groupCollectionsForAdmin', () => {
     it('treats an undeclared group name as ungrouped rather than throwing', () => {
         // Boot validation rejects this configuration, but the function stays total
         // so a renderer can never crash on a stale or hand-built config object.
-        const result = groupCollectionsForAdmin([pages], [{ slug: 'pages', group: 'ghost' }], groups);
+        const result = groupCollectionsForAdmin([pages], [{ path: 'pages', group: 'ghost' }], groups);
         expect(result).toEqual([{ name: null, label: null, collections: [pages] }]);
     });
     it('ignores admin configs whose collection is not registered', () => {

package/dist/config/validate-admin-configs.d.ts

@@ -25,7 +25,7 @@ export declare function validateCollectionGroups(collectionGroups: readonly Coll
  * Validate every admin config in a configuration.
  *
  * Enforced rules (per admin config):
- *  1. Slug pairing — `admin.slug` matches exactly one `collection.path`.
+ *  1. Path pairing — `admin.path` matches exactly one `collection.path`.
  *  2. Placement — when `layout` is present, every top-level schema field
  *     name appears exactly once across the union of all `tabSet.tabs[].fields`,
  *     all `row.fields`, all `group.fields`, `layout.main`, and `layout.sidebar`.

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

@@ -91,14 +91,14 @@ export function validateCollectionGroups(collectionGroups, admins) {
         const known = declared.size === 0
             ? '`collectionGroups` was not declared, or is empty'
             : `declared groups: ${[...declared].map((name) => `"${name}"`).join(', ')}`;
-        throw new Error(`Admin resource "${admin.slug}": \`group: '${admin.group}'\` does not name a declared collection group (${known}). Add it to \`AdminConfig.collectionGroups\`, or remove the \`group\` property.`);
+        throw new Error(`Admin config for path "${admin.path}": \`group: '${admin.group}'\` does not name a declared collection group (${known}). Add it to \`AdminConfig.collectionGroups\`, or remove the \`group\` property.`);
     }
 }
 /**
  * Validate every admin config in a configuration.
  *
  * Enforced rules (per admin config):
- *  1. Slug pairing — `admin.slug` matches exactly one `collection.path`.
+ *  1. Path pairing — `admin.path` matches exactly one `collection.path`.
  *  2. Placement — when `layout` is present, every top-level schema field
  *     name appears exactly once across the union of all `tabSet.tabs[].fields`,
  *     all `row.fields`, all `group.fields`, `layout.main`, and `layout.sidebar`.
@@ -210,24 +210,24 @@ export function validateBlockAdminConfigs(blockAdmins, collections) {
     }
 }
 function validateOne(admin, collectionsByPath) {
-    // Rule 1 — slug pairing.
-    const collection = collectionsByPath.get(admin.slug);
+    // Rule 1 — path pairing.
+    const collection = collectionsByPath.get(admin.path);
     if (collection == null) {
         if (admin.singleton === true) {
-            throw new Error(`Singleton admin config "${admin.slug}" has no matching singleton definition (no singleton with \`path: '${admin.slug}'\` was registered).`);
+            throw new Error(`Singleton admin config "${admin.path}" has no matching singleton definition (no singleton with \`path: '${admin.path}'\` was registered).`);
         }
-        throw new Error(`Admin config "${admin.slug}" has no matching collection (no collection with \`path: '${admin.slug}'\` was registered).`);
+        throw new Error(`Admin config "${admin.path}" has no matching collection (no collection with \`path: '${admin.path}'\` was registered).`);
     }
     if (admin.singleton === true && !isSingleton(collection)) {
-        throw new Error(`Singleton admin config "${admin.slug}" targets a collection definition. Register it with \`defineAdmin\`, or point it at a singleton definition.`);
+        throw new Error(`Singleton admin config "${admin.path}" targets a collection definition. Register it with \`defineAdmin\`, or point it at a singleton definition.`);
     }
     if (admin.singleton !== true && isSingleton(collection)) {
-        throw new Error(`Collection admin config "${admin.slug}" targets a singleton definition. Register it with \`defineSingletonAdmin\`, or point it at a multi-collection definition.`);
+        throw new Error(`Collection admin config "${admin.path}" targets a singleton definition. Register it with \`defineSingletonAdmin\`, or point it at a multi-collection definition.`);
     }
-    const slug = admin.slug;
+    const path = admin.path;
     const fail = (msg) => {
         const resource = admin.singleton === true ? 'Singleton' : 'Collection';
-        throw new Error(`${resource} "${slug}": ${msg}`);
+        throw new Error(`${resource} "${path}": ${msg}`);
     };
     if (admin.singleton === true) {
         for (const key of COLLECTION_ONLY_ADMIN_KEYS) {

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

@@ -21,7 +21,7 @@ const collection = {
     ],
 };
 const baseAdmin = {
-    slug: 'news',
+    path: 'news',
     tabSets: [
         {
             name: 'main',
@@ -80,20 +80,20 @@ describe('validateAdminConfigs', () => {
         expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/lockPath.*not allowed on a singleton admin config/);
     });
     it('rejects a singleton admin config targeting a multi-collection', () => {
-        const admin = { ...defineSingletonAdmin(singleton, {}), slug: collection.path };
+        const admin = { ...defineSingletonAdmin(singleton, {}), path: collection.path };
         expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/targets a collection definition/);
     });
     it('rejects a singleton admin config with no matching definition', () => {
-        const admin = { ...defineSingletonAdmin(singleton, {}), slug: 'missing-settings' };
+        const admin = { ...defineSingletonAdmin(singleton, {}), path: 'missing-settings' };
         expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/no matching singleton definition/);
     });
     it('rejects a multi-collection admin config targeting a singleton', () => {
-        const admin = { slug: singleton.path };
+        const admin = { path: singleton.path };
         expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/targets a singleton definition/);
     });
-    // Rule 1 — slug pairing.
-    it('rejects an admin config whose slug has no matching collection', () => {
-        const orphan = { slug: 'nonexistent', layout: { main: [] } };
+    // Rule 1 — path pairing.
+    it('rejects an admin config whose path has no matching collection', () => {
+        const orphan = { path: 'nonexistent', layout: { main: [] } };
         expect(() => validateAdminConfigs([orphan], [collection])).toThrow(/no matching collection/);
     });
     // Rule 2 — placement bookkeeping.
@@ -177,7 +177,7 @@ describe('validateAdminConfigs', () => {
     // Rule 5 — nesting.
     it('rejects a row whose fields include a non-field primitive', () => {
         const admin = {
-            slug: 'news',
+            path: 'news',
             tabSets: [
                 {
                     name: 'main',
@@ -198,7 +198,7 @@ describe('validateAdminConfigs', () => {
     });
     it('rejects a tab set referenced from inside a tab', () => {
         const admin = {
-            slug: 'news',
+            path: 'news',
             tabSets: [
                 {
                     name: 'inner',
@@ -226,7 +226,7 @@ describe('validateAdminConfigs', () => {
     });
     it('rejects a group nested inside another group', () => {
         const admin = {
-            slug: 'news',
+            path: 'news',
             tabSets: [
                 {
                     name: 'main',
@@ -290,7 +290,7 @@ describe('validateAdminConfigs', () => {
         ],
     };
     const nestedAdmin = (fields) => ({
-        slug: 'library',
+        path: 'library',
         fields: fields,
     });
     it('accepts a dotted fields key through array and group declarations', () => {
@@ -386,14 +386,14 @@ describe('validateAdminConfigs', () => {
     // Layout omitted — bookkeeping skipped, primitive declarations still checked.
     it('skips placement bookkeeping when layout is omitted', () => {
         const admin = {
-            slug: 'news',
+            path: 'news',
             // No layout — renderer will synthesise a default.
         };
         expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
     });
     it('still rejects a primitive collision when layout is omitted', () => {
         const admin = {
-            slug: 'news',
+            path: 'news',
             rows: [
                 { name: 'titles', fields: ['text1', 'text2'] },
                 // 'title' is also a schema field — collision still caught.
@@ -518,34 +518,34 @@ describe('validateAdminConfigs — collection groups', () => {
         { name: 'taxonomy', label: 'Taxonomies' },
     ];
     it('accepts a valid registry and a valid reference', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news', group: 'media' }], [collection], groups)).not.toThrow();
+        expect(() => validateAdminConfigs([{ path: 'news', group: 'media' }], [collection], groups)).not.toThrow();
     });
     it('accepts a collection with no group when a registry is declared', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], groups)).not.toThrow();
+        expect(() => validateAdminConfigs([{ path: 'news' }], [collection], groups)).not.toThrow();
     });
     it('is a no-op when no registry and no group references are present', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection])).not.toThrow();
+        expect(() => validateAdminConfigs([{ path: 'news' }], [collection])).not.toThrow();
     });
     it('rejects a duplicate group name', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [
+        expect(() => validateAdminConfigs([{ path: 'news' }], [collection], [
             { name: 'media', label: 'Media' },
             { name: 'media', label: 'Media Library' },
         ])).toThrow(/declared more than once/);
     });
     it('rejects a blank group name', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [{ name: '  ', label: 'Media' }])).toThrow(/blank `name`/);
+        expect(() => validateAdminConfigs([{ path: 'news' }], [collection], [{ name: '  ', label: 'Media' }])).toThrow(/blank `name`/);
     });
     it('rejects a blank group label', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news' }], [collection], [{ name: 'media', label: '' }])).toThrow(/blank `label`/);
+        expect(() => validateAdminConfigs([{ path: 'news' }], [collection], [{ name: 'media', label: '' }])).toThrow(/blank `label`/);
     });
     it('rejects a group reference that names no declared group', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news', group: 'medai' }], [collection], groups)).toThrow(/does not name a declared collection group/);
+        expect(() => validateAdminConfigs([{ path: 'news', group: 'medai' }], [collection], groups)).toThrow(/does not name a declared collection group/);
     });
     it('names the declared groups in the unresolved-reference error', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news', group: 'medai' }], [collection], groups)).toThrow(/"media", "taxonomy"/);
+        expect(() => validateAdminConfigs([{ path: 'news', group: 'medai' }], [collection], groups)).toThrow(/"media", "taxonomy"/);
     });
     it('rejects a group reference when no registry was declared at all', () => {
-        expect(() => validateAdminConfigs([{ slug: 'news', group: 'media' }], [collection])).toThrow(/was not declared/);
+        expect(() => validateAdminConfigs([{ path: 'news', group: 'media' }], [collection])).toThrow(/was not declared/);
     });
     // Registry sanity must not be skipped by the `admins` early return.
     it('validates the registry even when there are no admin configs', () => {

package/dist/paths/path-dialects.test.node.js

@@ -139,7 +139,7 @@ describe('path dialect — upload hook registry keys', () => {
 // one registration applies wherever the block renders.
 // ---------------------------------------------------------------------------
 describe('path dialect — admin fields{} override keys', () => {
-    const admin = (key) => ({ slug: 'pages', fields: { [key]: {} } });
+    const admin = (key) => ({ path: 'pages', fields: { [key]: {} } });
     const validate = (key) => () => validateAdminConfigs([admin(key)], [fixture()]);
     it('accepts a top-level field name', () => {
         expect(validate('title')).not.toThrow();
@@ -262,6 +262,6 @@ describe('path dialects — cross-dialect relationships', () => {
             collections: [fixture()],
             hooks: { uploads: { [registryKey]: async () => ({}) } },
         })).not.toThrow();
-        expect(() => validateAdminConfigs([{ slug: 'pages', fields: { [adminKey]: {} } }], [fixture()])).not.toThrow();
+        expect(() => validateAdminConfigs([{ path: 'pages', fields: { [adminKey]: {} } }], [fixture()])).not.toThrow();
     });
 });

package/dist/paths/paths.test.node.js

@@ -309,7 +309,7 @@ describe('resolveDeclarationPath — agreement with the admin fields{} validator
     };
     const validatorAccepts = (key) => {
         try {
-            validateAdminConfigs([{ slug: 'pages', fields: { [key]: {} } }], [collection]);
+            validateAdminConfigs([{ path: 'pages', fields: { [key]: {} } }], [collection]);
             return true;
         }
         catch {

package/dist/services/document-lifecycle/copy-to-locale.js

@@ -104,6 +104,7 @@ export async function copyToLocale(ctx, params) {
         const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId, locale: params.targetLocale }, async () => {
             if ((targetRecord._availableVersionLocales?.includes(params.targetLocale) ||
                 targetRecord._localeAgnostic === true) &&
+                !targetRecord.unavailableBlocks?.length &&
                 sameDocumentData(merged.data, baseline))
                 return { value: previousVersionId, changed: false };
             const writeResult = await persistExistingDocumentVersion(ctx, {
@@ -113,7 +114,7 @@ export async function copyToLocale(ctx, params) {
                 status: getDefaultStatus(definition),
                 locale: params.targetLocale,
                 previousVersionId,
-            });
+            }, targetRecord);
             return { value: extractVersionId(writeResult.document), changed: true };
         });
         const documentVersionId = committed.value;

package/dist/services/document-lifecycle/delete-locale.js

@@ -9,6 +9,8 @@ import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
+import { flattenFieldSetData } from '../../storage/storage-flatten.js';
+import { restoreFieldSetData } from '../../storage/storage-restore.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { runCommittedDocumentHook } from './committed-hook.js';
 import { actorId, invokeHook } from './internals.js';
@@ -84,6 +86,31 @@ export async function deleteLocale(ctx, params) {
                 ctx,
                 documentId: params.documentId,
                 write: async () => {
+                    // The ordinary delete-locale primitive copies raw stored rows.
+                    // Reconstruct affected versions so unavailable blocks are omitted too.
+                    if (targetRecord.unavailableBlocks?.length) {
+                        const previous = await db.queries.documents.getDocumentByVersion({
+                            document_version_id: previousVersionId,
+                            document_id: params.documentId,
+                            collection_id: collectionId,
+                            locale: 'all',
+                        });
+                        const rows = flattenFieldSetData(definition.fields, previous.fields, 'all').filter((row) => row.locale !== params.locale);
+                        const { data } = restoreFieldSetData(definition.fields, rows);
+                        const saved = await db.commands.documents.createDocumentVersion({
+                            documentId: params.documentId,
+                            collectionId,
+                            collectionVersion: ctx.collectionVersion,
+                            collectionConfig: definition,
+                            action: 'delete_locale',
+                            documentData: data,
+                            locale: 'all',
+                            previousVersionId,
+                            status: getDefaultStatus(definition),
+                            createdBy: actorId(ctx),
+                        });
+                        return { newVersionId: saved.document.id, previousVersionId };
+                    }
                     const deleted = await db.commands.documents.deleteDocumentLocale({
                         documentId: params.documentId,
                         locale: params.locale,

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

@@ -112,8 +112,9 @@ export declare function resolvePathForUpdate(args: {
  */
 export declare function derivePath(definition: CollectionDefinition, data: Record<string, any>, defaultLocale: string, slugifier: SlugifierFn): string;
 /**
- * Strip the synthetic `_id` / `_type` meta keys from every block and
- * array-item node in a reconstructed document tree.
+ * Strip the synthetic `_id` identity from every block and
+ * array-item node in a reconstructed document tree. Preserve `_type`, which
+ * selects the schema used to flatten each surviving block.
  *
  * Reconstructed `locale: 'all'` trees carry stable `_id` values for
  * blocks and array items (see CLAUDE.md → "Block/array items carry a

package/dist/services/document-lifecycle/internals.js

@@ -232,8 +232,9 @@ export function derivePath(definition, data, defaultLocale, slugifier) {
     return crypto.randomUUID();
 }
 /**
- * Strip the synthetic `_id` / `_type` meta keys from every block and
- * array-item node in a reconstructed document tree.
+ * Strip the synthetic `_id` identity from every block and
+ * array-item node in a reconstructed document tree. Preserve `_type`, which
+ * selects the schema used to flatten each surviving block.
  *
  * Reconstructed `locale: 'all'` trees carry stable `_id` values for
  * blocks and array items (see CLAUDE.md → "Block/array items carry a
@@ -254,7 +255,6 @@ export function stripMetaIdsInPlace(value) {
     if (value != null && typeof value === 'object' && !(value instanceof Date)) {
         const obj = value;
         delete obj._id;
-        delete obj._type;
         for (const key of Object.keys(obj)) {
             stripMetaIdsInPlace(obj[key]);
         }

package/dist/services/document-lifecycle/merge-write-locale.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { FieldSet } from '../../@types/index.js';
+/** Preserve other locales by item identity after unavailable blocks were compacted.
+ * Incoming structure is authoritative; never carry old positional store rows forward.
+ */
+export declare function mergeWriteLocale(fields: FieldSet, previous: Record<string, any>, incoming: Record<string, any>, locale: string): Record<string, any>;

package/dist/services/document-lifecycle/merge-write-locale.js

@@ -0,0 +1,53 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/** Preserve other locales by item identity after unavailable blocks were compacted.
+ * Incoming structure is authoritative; never carry old positional store rows forward.
+ */
+export function mergeWriteLocale(fields, previous, incoming, locale) {
+    const result = {};
+    for (const field of fields) {
+        const value = incoming[field.name];
+        const old = previous?.[field.name];
+        if (field.type === 'group') {
+            if (value != null)
+                result[field.name] = mergeWriteLocale(field.fields, old ?? {}, value, locale);
+        }
+        else if (field.type === 'array' || field.type === 'blocks') {
+            if (!Array.isArray(value))
+                continue;
+            result[field.name] = value.map((item, index) => {
+                // Hand-built payloads may omit identity metadata. Match their compacted
+                // position, as ordinary locale writes do; an explicit ID stays authoritative.
+                const prior = Array.isArray(old)
+                    ? item._id != null
+                        ? old.find((candidate) => candidate._id === item._id)
+                        : old[index]
+                    : undefined;
+                const childFields = field.type === 'array'
+                    ? field.fields
+                    : field.blocks.find((block) => block.blockType === item._type)?.fields;
+                return {
+                    ...(item._id != null ? { _id: item._id } : {}),
+                    ...(field.type === 'blocks' ? { _type: item._type } : {}),
+                    ...mergeWriteLocale(childFields ?? [], prior ?? {}, item, locale),
+                };
+            });
+        }
+        else if (field.localized) {
+            const localized = { ...old };
+            delete localized[locale];
+            if (value !== undefined)
+                localized[locale] = value;
+            if (Object.keys(localized).length > 0)
+                result[field.name] = localized;
+        }
+        else if (value !== undefined)
+            result[field.name] = value;
+    }
+    return result;
+}

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

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { IDocumentCommands } from '../../@types/index.js';
+import type { UnavailableBlock } from '../../storage/storage-restore.js';
 import type { DocumentLifecycleContext } from './context.js';
 type AdapterVersionWrite = Parameters<IDocumentCommands['createDocumentVersion']>[0];
 type LifecycleOwnedWriteKeys = 'collectionId' | 'collectionVersion' | 'collectionConfig' | 'createdBy';
@@ -25,5 +26,7 @@ export declare function persistInitialDocumentVersion(ctx: DocumentLifecycleCont
  * publication schedule atomically. All operation-specific preparation and
  * hook sequencing remains in the caller.
  */
-export declare function persistExistingDocumentVersion(ctx: DocumentLifecycleContext, write: ExistingDocumentVersionWrite): ReturnType<IDocumentCommands['createDocumentVersion']>;
+export declare function persistExistingDocumentVersion(ctx: DocumentLifecycleContext, write: ExistingDocumentVersionWrite, previousRead?: {
+    unavailableBlocks?: readonly UnavailableBlock[];
+} | null): ReturnType<IDocumentCommands['createDocumentVersion']>;
 export {};

package/dist/services/document-lifecycle/persistence.js

@@ -8,6 +8,7 @@
 import { assertDocumentFields } from '../../validation/document-fields.js';
 import { requireAuditCapability } from './audit.js';
 import { actorId } from './internals.js';
+import { mergeWriteLocale } from './merge-write-locale.js';
 import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
 import { normalizeDocumentVersionParentError } from './stale-document.js';
 import { appendTreeRoot } from './tree.js';
@@ -73,8 +74,29 @@ export async function persistInitialDocumentVersion(ctx, write) {
  * publication schedule atomically. All operation-specific preparation and
  * hook sequencing remains in the caller.
  */
-export function persistExistingDocumentVersion(ctx, write) {
+export async function persistExistingDocumentVersion(ctx, write, previousRead) {
     assertWritableContent(ctx, write);
+    // Single-locale storage writes copy other locales' positional rows forward.
+    // After compaction those rows can resurrect unavailable blocks or attach a
+    // translation to the wrong survivor. Rebuild all locales by item identity.
+    if (previousRead?.unavailableBlocks?.length &&
+        write.previousVersionId &&
+        write.locale &&
+        write.locale !== 'all') {
+        const previous = await ctx.db.queries.documents.getDocumentByVersion({
+            document_version_id: write.previousVersionId,
+            document_id: write.documentId,
+            collection_id: ctx.collectionId,
+            locale: 'all',
+        });
+        if (previous?.unavailableBlocks?.length) {
+            write = {
+                ...write,
+                documentData: mergeWriteLocale(ctx.definition.fields, previous.fields, write.documentData, write.locale),
+                locale: 'all',
+            };
+        }
+    }
     return commitContentVersionWithScheduleSuspension({
         ctx,
         documentId: write.documentId,

package/dist/services/document-lifecycle/update.js

@@ -102,7 +102,7 @@ async function replaceFields(ctx, params, policy) {
                 status: policy === 'preserve' ? preservedStatus(ctx, locked.status) : defaultStatus,
                 locale: requestLocale,
                 previousVersionId,
-            });
+            }, latest);
             if (policy === 'preserve' && locked.status === 'published') {
                 await db.commands.documents.archivePublishedVersions({
                     document_id: params.documentId,
@@ -212,7 +212,7 @@ export async function updateDocumentWithPatches(ctx, params) {
                 status: defaultStatus,
                 locale: requestLocale,
                 previousVersionId,
-            });
+            }, latest);
             await selfHealTreePlacement(ctx, params.documentId);
             return { value: { result, systemFields }, changed: true };
         }).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));

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

@@ -2857,7 +2857,7 @@ describe('Document lifecycle service', () => {
             expect(call.path).toBe('hello-world-copy');
             expect(result.newPath).toBe('hello-world-copy');
         });
-        it('strips _id and _type metadata from blocks and array items so the new doc gets fresh identities', async () => {
+        it('strips _id identities but preserves block types when duplicating', async () => {
             const mocks = createMockDb();
             setupSource(mocks, {
                 sourceFields: {
@@ -2881,7 +2881,9 @@ describe('Document lifecycle service', () => {
             const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
             const sections = call.documentData.sections;
             expect(sections[0]._id).toBeUndefined();
-            expect(sections[0]._type).toBeUndefined();
+            expect(sections[0]._type).toBe('section');
+            expect(sections[0].blocks[0]._type).toBe('photoBlock');
+            expect(sections[0].blocks[1]._type).toBe('textBlock');
             expect(sections[0].blocks[0]._id).toBeUndefined();
             expect(sections[0].blocks[1]._id).toBeUndefined();
             // Content survives — only meta is stripped.

package/dist/services/singleton-lifecycle/copy-to-locale.js

@@ -98,7 +98,7 @@ export async function copySingletonToLocale(ctx, params) {
                             status: getDefaultStatus(definition),
                             locale: params.targetLocale,
                             previousVersionId: slot.currentVersion?.document_version_id,
-                        });
+                        }, existingTarget ?? source);
                     },
                 };
             },

package/dist/services/singleton-lifecycle/update.js

@@ -139,7 +139,7 @@ export async function updateSingleton(ctx, params) {
                 action: 'update',
                 documentId: mappedDocumentId,
                 previousVersionId,
-            });
+            }, observed.current);
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
         if (!documentId || !documentVersionId)

package/dist/storage/index.d.ts

@@ -10,7 +10,7 @@ export { assertDocumentVersionParent, type DocumentVersionParentAssertion, type
 export { ALL_STORE_TYPES, type FieldStoreKind, type FieldStoreMapping, fieldTypeToStore, fieldTypeToStoreType, type StoreType, } from './field-store-map.js';
 export { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, type VersionLocaleLedger, } from './locale-resolution.js';
 export { flattenFieldSetData } from './storage-flatten.js';
-export { extractFlattenedFieldValue, type RestoreResult, restoreFieldSetData, } from './storage-restore.js';
+export { extractFlattenedFieldValue, type RestoreResult, restoreFieldSetData, type UnavailableBlock, } from './storage-restore.js';
 export { resolveStoreTypes } from './storage-utils.js';
 export { type ColumnDef, storeColumnManifest, storeTableNames } from './store-manifest.js';
 export type { FlattenedFieldValue, UnifiedFieldValue } from './storage-row-types.js';

package/dist/storage/storage-flatten.js

@@ -101,8 +101,14 @@ function* flattenFieldDataGen(field, data, locale, field_path) {
     else if (field.type === 'blocks') {
         const items = data;
         for (let i = 0; i < items.length; i++) {
-            // biome-ignore lint/style/noNonNullAssertion: i is always in-bounds
-            const { _id, _type, ...item_data } = items[i];
+            const item = items[i];
+            if (item == null || typeof item !== 'object' || Array.isArray(item)) {
+                throw ERR_DATABASE({
+                    message: `${field_path.join('.')}[${i}]: Block item is missing or must be an object`,
+                    details: { fieldPath: field_path, index: i },
+                });
+            }
+            const { _id, _type, ...item_data } = item;
             const item_path = [...field_path, `${i}`, _type];
             const block = field.blocks.find((f) => f.blockType === _type);
             if (!block) {

package/dist/storage/storage-restore.d.ts

@@ -7,15 +7,24 @@
  */
 import type { FieldSet } from '../@types/index.js';
 import type { FlattenedFieldValue, UnifiedFieldValue } from './storage-row-types.js';
+export interface UnavailableBlock {
+    /** Instance path in the compacted document, e.g. sections[0].body. */
+    fieldPath: string;
+    /** Position in the stored blocks array before compaction. */
+    storedIndex: number;
+    blockType: string;
+    id?: string;
+}
 export interface RestoreResult {
     data: any;
     warnings: string[];
+    unavailableBlocks: UnavailableBlock[];
 }
 /**
  * Main entrypoint for restoring a document's field data from flattened form
  * back into the original nested structure.
  *
- * Always returns `{ data, warnings }`. Warnings carry per-row reasons (e.g.
+ * Always returns `{ data, warnings, unavailableBlocks }`. Warnings carry per-row reasons (e.g.
  * "Invalid block index 'undefined'") that are typically the result of a
  * collection schema change leaving orphan rows behind. Callers decide what
  * to do with them — strict reads reject any non-empty `warnings`, lenient
@@ -24,5 +33,9 @@ export interface RestoreResult {
  * @param fields - The field definitions for the collection.
  * @param flattenedData - The flattened field data to restore.
  */
-export declare const restoreFieldSetData: (fields: FieldSet, flattenedData: FlattenedFieldValue[], resolveLocale?: string) => RestoreResult;
+export declare const restoreFieldSetData: (fields: FieldSet, flattenedData: FlattenedFieldValue[], resolveLocale?: string, identity?: {
+    collectionPath: string;
+    documentId: string;
+    versionId: string;
+}) => RestoreResult;
 export declare const extractFlattenedFieldValue: (unifiedValue: UnifiedFieldValue) => FlattenedFieldValue;

package/dist/storage/storage-restore.js

@@ -8,11 +8,16 @@
 import { RESERVED_FIELD_NAMES } from '../config/validate-collections.js';
 import { ERR_DATABASE } from '../lib/errors.js';
 import { getLogger } from '../lib/logger.js';
+// Shared across duplicate server module graphs, just like the logger registry.
+const loggedVersionsKey = Symbol.for('byline.unavailable-block-versions');
+const processState = globalThis;
+processState[loggedVersionsKey] ??= new Set();
+const loggedVersions = processState[loggedVersionsKey];
 /**
  * Main entrypoint for restoring a document's field data from flattened form
  * back into the original nested structure.
  *
- * Always returns `{ data, warnings }`. Warnings carry per-row reasons (e.g.
+ * Always returns `{ data, warnings, unavailableBlocks }`. Warnings carry per-row reasons (e.g.
  * "Invalid block index 'undefined'") that are typically the result of a
  * collection schema change leaving orphan rows behind. Callers decide what
  * to do with them — strict reads reject any non-empty `warnings`, lenient
@@ -21,9 +26,10 @@ import { getLogger } from '../lib/logger.js';
  * @param fields - The field definitions for the collection.
  * @param flattenedData - The flattened field data to restore.
  */
-export const restoreFieldSetData = (fields, flattenedData, resolveLocale) => {
+export const restoreFieldSetData = (fields, flattenedData, resolveLocale, identity) => {
     const result = {};
     const warnings = [];
+    const unavailableByArray = new Map();
     for (const item of flattenedData) {
         // biome-ignore lint/style/noNonNullAssertion: TODO: put in a proper check here?
         const fieldName = item.field_path[0];
@@ -38,7 +44,7 @@ export const restoreFieldSetData = (fields, flattenedData, resolveLocale) => {
         if (!field) {
         }
         else {
-            result[fieldName] = restoreFieldData(field, result[fieldName], item, 1, warnings, resolveLocale);
+            result[fieldName] = restoreFieldData(field, result[fieldName], item, 1, warnings, unavailableByArray, resolveLocale);
         }
     }
     // Array/blocks/group/hasMany-relation fixup — a required list-shaped field
@@ -54,17 +60,52 @@ export const restoreFieldSetData = (fields, flattenedData, resolveLocale) => {
             result[field.name] = result[field.name] || {};
         }
     }
-    return { data: result, warnings };
+    const unavailableBlocks = [];
+    // Finish only after all rows (including identity metadata) have been read.
+    // Walk parents before children so nested report paths use compacted indices.
+    const finish = (fields, value, prefix = '') => {
+        for (const field of fields) {
+            const path = prefix ? `${prefix}.${field.name}` : field.name;
+            const child = value?.[field.name];
+            if (field.type === 'group' && child)
+                finish(field.fields, child, path);
+            if ((field.type === 'blocks' || field.type === 'array') && Array.isArray(child)) {
+                for (const issue of [...(unavailableByArray.get(child)?.values() ?? [])].sort((a, b) => a.storedIndex - b.storedIndex))
+                    unavailableBlocks.push({ fieldPath: path, ...issue });
+                const compacted = child.filter((item) => item != null);
+                value[field.name] = compacted;
+                compacted.forEach((item, index) => {
+                    const itemFields = field.type === 'array'
+                        ? field.fields
+                        : field.blocks.find((block) => block.blockType === item._type)?.fields;
+                    if (itemFields)
+                        finish(itemFields, item, `${path}[${index}]`);
+                });
+            }
+        }
+    };
+    finish(fields, result);
+    if (identity && unavailableBlocks.length > 0) {
+        const key = JSON.stringify([identity.collectionPath, identity.documentId, identity.versionId]);
+        if (!loggedVersions.has(key)) {
+            loggedVersions.add(key);
+            getLogger().warn({
+                ...identity,
+                blockTypes: [...new Set(unavailableBlocks.map((issue) => issue.blockType))],
+            }, 'Document contains unavailable blocks; saving content will remove them');
+        }
+    }
+    return { data: result, warnings, unavailableBlocks };
 };
-const restoreFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+const restoreFieldData = (field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale) => {
     if (field.type === 'group') {
-        return restoreGroupFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+        return restoreGroupFieldData(field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale);
     }
     else if (field.type === 'array') {
-        return restoreArrayFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+        return restoreArrayFieldData(field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale);
     }
     else if (field.type === 'blocks') {
-        return restoreBlocksFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+        return restoreBlocksFieldData(field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale);
     }
     else if (field.type === 'relation' && field.hasMany) {
         return restoreMultiRelationFieldData(target, data, pathIndex, warnings);
@@ -95,7 +136,7 @@ const restoreFieldData = (field, target, data, pathIndex, warnings, resolveLocal
     }
     return target;
 };
-const restoreGroupFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+const restoreGroupFieldData = (field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale) => {
     if (pathIndex >= data.field_path.length) {
         warnings.push(`Path ended unexpectedly while restoring group: ${data.field_path.join('.')}`);
         return target;
@@ -108,10 +149,10 @@ const restoreGroupFieldData = (field, target, data, pathIndex, warnings, resolve
         return target;
     }
     target = target || {};
-    target[fieldName] = restoreFieldData(subField, target[fieldName], data, pathIndex + 1, warnings, resolveLocale);
+    target[fieldName] = restoreFieldData(subField, target[fieldName], data, pathIndex + 1, warnings, unavailableByArray, resolveLocale);
     return target;
 };
-const restoreArrayFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+const restoreArrayFieldData = (field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale) => {
     if (pathIndex >= data.field_path.length) {
         warnings.push(`Path ended unexpectedly while restoring array: ${data.field_path.join('.')}`);
         return target;
@@ -140,10 +181,10 @@ const restoreArrayFieldData = (field, target, data, pathIndex, warnings, resolve
         // Sub-field was removed from the schema; silently skip orphaned rows.
         return target;
     }
-    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 2, warnings, resolveLocale);
+    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 2, warnings, unavailableByArray, resolveLocale);
     return target;
 };
-const restoreBlocksFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+const restoreBlocksFieldData = (field, target, data, pathIndex, warnings, unavailableByArray, resolveLocale) => {
     const arrayIndex = Number.parseInt(data.field_path[pathIndex] ?? '', 10);
     if (Number.isNaN(arrayIndex) || arrayIndex < 0) {
         warnings.push(`Invalid block index '${data.field_path[pathIndex]}' in path ${data.field_path.join('.')}`);
@@ -156,7 +197,17 @@ const restoreBlocksFieldData = (field, target, data, pathIndex, warnings, resolv
     }
     const block = field.blocks.find((f) => f.blockType === blockType);
     if (block == null) {
-        // Block type was removed from the schema; silently skip orphaned rows.
+        target = target || [];
+        let issues = unavailableByArray.get(target);
+        if (!issues) {
+            issues = new Map();
+            unavailableByArray.set(target, issues);
+        }
+        const issue = issues.get(arrayIndex) ?? { storedIndex: arrayIndex, blockType };
+        if (data.field_type === 'meta' && pathIndex + 2 === data.field_path.length) {
+            issue.id = data.item_id;
+        }
+        issues.set(arrayIndex, issue);
         return target;
     }
     target = target || [];
@@ -178,7 +229,7 @@ const restoreBlocksFieldData = (field, target, data, pathIndex, warnings, resolv
         // Sub-field was removed from the schema; silently skip orphaned rows.
         return target;
     }
-    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 3, warnings, resolveLocale);
+    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 3, warnings, unavailableByArray, resolveLocale);
     return target;
 };
 const restoreMultiRelationFieldData = (target, data, pathIndex, warnings) => {

package/dist/storage/unavailable-blocks.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/storage/unavailable-blocks.test.node.js

@@ -0,0 +1,132 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { getLogger } from '../lib/logger.js';
+import { applyPatches } from '../patches/apply-patches.js';
+import { validateDocumentFields } from '../validation/document-fields.js';
+import { flattenFieldSetData } from './storage-flatten.js';
+import { restoreFieldSetData } from './storage-restore.js';
+const logger = vi.hoisted(() => ({ warn: vi.fn() }));
+vi.mock('../lib/logger.js', () => ({ getLogger: () => logger }));
+const live = { blockType: 'live', fields: [{ name: 'text', type: 'text' }] };
+const retired = { ...live, blockType: 'retired' };
+const blocks = (optional = false) => ({
+    name: 'content',
+    type: 'blocks',
+    optional,
+    blocks: [live, retired],
+});
+const item = (_type, i) => ({ _id: `item-${i}`, _type, text: `${_type}-${i}` });
+describe('unavailable blocks', () => {
+    for (const optional of [false, true]) {
+        for (const types of [
+            ['retired', 'live'],
+            ['live', 'retired', 'live'],
+            ['live', 'retired'],
+            ['retired'],
+            ['retired', 'retired', 'live'],
+        ]) {
+            it(`compacts ${types.join(',')} (optional=${optional}) with an independent report`, () => {
+                const before = [blocks(optional)];
+                const after = [{ ...blocks(optional), blocks: [live] }];
+                const original = { content: types.map(item) };
+                const rows = flattenFieldSetData(before, original, 'en');
+                const restored = restoreFieldSetData(after, rows, 'en');
+                expect(restored.warnings).toEqual([]);
+                expect(restored.unavailableBlocks).toEqual(types.flatMap((type, storedIndex) => type === 'retired'
+                    ? [{ fieldPath: 'content', storedIndex, blockType: type, id: `item-${storedIndex}` }]
+                    : []));
+                expect(restored.data.content).toEqual(original.content.filter((item) => item._type === 'live'));
+                for (const data of [restored.data, JSON.parse(JSON.stringify(restored.data))]) {
+                    expect(validateDocumentFields(after, data)).toEqual([]);
+                    const saved = restoreFieldSetData(after, flattenFieldSetData(after, data, 'en'), 'en');
+                    expect(saved.unavailableBlocks).toEqual([]);
+                    expect(saved.data.content ?? []).toEqual(restored.data.content);
+                }
+            });
+        }
+    }
+    it('reports groups, arrays and nested blocks using compacted parent indices', () => {
+        const before = [
+            { name: 'group', type: 'group', fields: [blocks()] },
+            { name: 'sections', type: 'array', fields: [blocks()] },
+            {
+                name: 'outer',
+                type: 'blocks',
+                blocks: [retired, { blockType: 'container', fields: [blocks()] }],
+            },
+        ];
+        const after = [
+            { name: 'group', type: 'group', fields: [{ ...blocks(), blocks: [live] }] },
+            { name: 'sections', type: 'array', fields: [{ ...blocks(), blocks: [live] }] },
+            {
+                name: 'outer',
+                type: 'blocks',
+                blocks: [{ blockType: 'container', fields: [{ ...blocks(), blocks: [live] }] }],
+            },
+        ];
+        const content = [item('retired', 0), item('live', 1)];
+        const rows = flattenFieldSetData(before, {
+            group: { content },
+            sections: [{ content }],
+            outer: [item('retired', 0), { _type: 'container', content }],
+        }, 'en');
+        const result = restoreFieldSetData(after, rows.reverse(), 'en');
+        expect(result.unavailableBlocks.map((issue) => issue.fieldPath)).toEqual([
+            'group.content',
+            'sections[0].content',
+            'outer',
+            'outer[0].content',
+        ]);
+        expect(result.warnings).toEqual([]);
+        expect(result.data.outer[0].content).toEqual([item('live', 1)]);
+    });
+    it('applies a positional patch to a surviving block after the missing card', () => {
+        const before = [blocks()];
+        const after = [{ ...blocks(), blocks: [live] }];
+        const source = { content: ['retired', 'live', 'live'].map(item) };
+        const { data } = restoreFieldSetData(after, flattenFieldSetData(before, source, 'en'));
+        const definition = {
+            path: 'pages',
+            labels: { singular: 'Page', plural: 'Pages' },
+            fields: after,
+        };
+        const patched = applyPatches(definition, data, [
+            { kind: 'field.set', path: 'content[1].text', value: 'edited' },
+        ]);
+        expect(patched.errors).toEqual([]);
+        const saved = restoreFieldSetData(after, flattenFieldSetData(after, patched.doc, 'en'));
+        expect(saved.data.content.map((item) => [item._id, item.text])).toEqual([
+            ['item-1', 'live-1'],
+            ['item-2', 'edited'],
+        ]);
+    });
+    it.each([new Array(1), [null], [undefined], [42], [[]]].map((content) => ({ content })))('rejects malformed items without a destructure crash: $content', ({ content }) => {
+        expect(validateDocumentFields([blocks()], { content })).not.toEqual([]);
+        expect(() => flattenFieldSetData([blocks()], { content }, 'en')).toThrow(/Block item is missing or must be an object/);
+    });
+    it('logs once per document version without adding a strict-read warning', () => {
+        const spy = vi.spyOn(getLogger(), 'warn').mockImplementation(() => { });
+        try {
+            const rows = flattenFieldSetData([blocks()], { content: [item('retired', 0)] }, 'en');
+            const identity = { collectionPath: 'pages', documentId: crypto.randomUUID(), versionId: 'v1' };
+            for (let i = 0; i < 2; i++)
+                expect(restoreFieldSetData([{ ...blocks(), blocks: [live] }], rows, 'en', identity).warnings).toEqual([]);
+            expect(spy).toHaveBeenCalledTimes(1);
+            expect(spy).toHaveBeenCalledWith({ ...identity, blockTypes: ['retired'] }, expect.any(String));
+            restoreFieldSetData([{ ...blocks(), blocks: [live] }], rows, 'en', {
+                ...identity,
+                versionId: 'v2',
+            });
+            expect(spy).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            spy.mockRestore();
+        }
+    });
+});

package/dist/validation/document-fields.js

@@ -119,13 +119,16 @@ export function validateDocumentFields(fields, data, options = {}) {
                     if (field.validation?.maxLength != null && value.length > field.validation.maxLength)
                         add(path, `${label} allows at most ${field.validation.maxLength} items`);
                 }
-                value.forEach((item, index) => {
+                for (let index = 0; index < value.length; index++) {
+                    const item = value[index];
                     const itemPath = record(item) && typeof item._id === 'string' && /^[\w-]+$/.test(item._id)
                         ? `${path}[id=${item._id}]`
                         : `${path}[${index}]`;
                     if (!record(item)) {
-                        add(itemPath, 'Item must be an object');
-                        return;
+                        add(itemPath, field.type === 'blocks'
+                            ? 'Block item is missing or must be an object'
+                            : 'Item must be an object');
+                        continue;
                     }
                     if (field.type === 'array')
                         visit(field.fields, item, itemPath);
@@ -136,7 +139,7 @@ export function validateDocumentFields(fields, data, options = {}) {
                         else
                             visit(block.fields, item, itemPath);
                     }
-                });
+                }
             }
         }
         else {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "engines": {
     "node": ">=22.22.2"
   },
@@ -82,7 +82,7 @@
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "6.8.0",
+    "@byline/auth": "6.9.0",
     "dotenv": "^18.0.8",
     "pino": "^10.4.0",
     "sharp": "^0.35.5",