@byline/host-tanstack-start 6.3.0 → 6.4.0

package/dist/admin-shell/collections/edit.js

@@ -8,6 +8,7 @@ import { getAdminRoutePath } from "../../routes/admin-path.js";
 import { clearListReturnState } from "../../routes/list-return-storage.js";
 import { cancelCollectionDocumentScheduledPublish, confirmCollectionDocumentScheduledPublish, copyDocumentToLocale, deleteDocument, deleteDocumentLocale, duplicateCollectionDocument, hasCommittedDocumentHookFailure, hasDeleteSideEffectFailures, scheduleCollectionDocumentPublish, unpublishDocument, updateCollectionDocumentWithPatches, updateDocumentStatus } from "../../server-fns/collections/index.js";
 import { useNavigate } from "../chrome/loose-router.js";
+import { describeMutationFailure } from "../describe-mutation-failure.js";
 import { useDocumentMutationState } from "../document-mutation-state.js";
 import { useTanStackNavigationGuard } from "./tanstack-navigation-guard.js";
 import { ViewMenu } from "./view-menu.js";
@@ -432,7 +433,7 @@ const EditView = ({ collectionDefinition, adminConfig, initialData: loadedData,
             }
             console.error('Duplicate error:', err);
             const description = t("collections.edit.duplicateFailedDescription", {
-                message: t('documentConcurrency.failed')
+                message: describeMutationFailure(err, t)
             });
             toastManager.add({
                 title: t('collections.edit.duplicateTitle', {
@@ -533,7 +534,7 @@ const EditView = ({ collectionDefinition, adminConfig, initialData: loadedData,
             }
             console.error('Copy to locale error:', err);
             const description = t("collections.edit.copyFailedDescription", {
-                message: t('documentConcurrency.failed')
+                message: describeMutationFailure(err, t)
             });
             toastManager.add({
                 title: t('collections.edit.copyToLocaleTitle', {

package/dist/admin-shell/collections/restore-version-modal.js

@@ -17,6 +17,19 @@ function RestoreVersionModal({ disabled = false, onMutationError, versionLabel,
         setError(null);
         try {
             const result = await restoreVersion();
+            const issues = getRestoreValidationIssues(result);
+            if (issues.length > 0) toastManager.add({
+                title: t('collections.restore.validationIssuesToast'),
+                description: t("collections.restore.validationIssuesDescription", {
+                    fields: issues.join(', ')
+                }),
+                data: {
+                    intent: 'warning',
+                    iconType: 'warning',
+                    icon: true,
+                    close: true
+                }
+            });
             if (hasCommittedDocumentHookFailure(result)) toastManager.add({
                 title: t('collections.save.hookFailedToast'),
                 description: t("collections.save.hookFailedDescription"),
@@ -126,6 +139,12 @@ function RestoreVersionModal({ disabled = false, onMutationError, versionLabel,
         ]
     });
 }
+function getRestoreValidationIssues(result) {
+    if (null == result || 'object' != typeof result) return [];
+    const issues = result.validationIssues;
+    if (!Array.isArray(issues)) return [];
+    return issues.map((issue)=>null != issue && 'object' == typeof issue && 'string' == typeof issue.field ? issue.field : '').filter((field)=>field.length > 0);
+}
 function getErrorCode(err) {
     return 'string' == typeof err?.code ? err.code : null;
 }

package/dist/admin-shell/describe-mutation-failure.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { TranslationValues } from '@byline/i18n';
+/**
+ * Describe a failed document mutation for the editor.
+ *
+ * Content writes that are not restores — create, update, patch saves,
+ * duplication and locale copies — keep the field-validation gate, because each
+ * reads or authors content the editor can open and correct. Naming the
+ * offending fields is what makes that correction actionable; without it the
+ * editor sees only a generic failure.
+ */
+export declare function describeMutationFailure(err: unknown, t: (key: string, values?: TranslationValues) => string): string;

package/dist/admin-shell/describe-mutation-failure.js

@@ -0,0 +1,9 @@
+import { getDocumentFieldValidationDetails } from "@byline/core";
+function describeMutationFailure(err, t) {
+    const validation = getDocumentFieldValidationDetails(err);
+    if (null == validation) return t('documentConcurrency.failed');
+    return t('collections.edit.invalidFieldsMessage', {
+        fields: validation.issues.map((issue)=>issue.field || '?').join(', ')
+    });
+}
+export { describeMutationFailure };

package/dist/admin-shell/singletons/view.js

@@ -10,6 +10,7 @@ import { hasCommittedDocumentHookFailure } from "../../server-fns/collections/in
 import { cancelSingletonScheduledPublish, changeSingletonStatus, confirmSingletonScheduledPublish, copySingletonToLocale, scheduleSingletonPublish, unpublishSingleton, updateSingleton } from "../../server-fns/singletons/index.js";
 import { useNavigate } from "../chrome/loose-router.js";
 import { useTanStackNavigationGuard } from "../collections/tanstack-navigation-guard.js";
+import { describeMutationFailure } from "../describe-mutation-failure.js";
 import { useDocumentMutationState } from "../document-mutation-state.js";
 import { SingletonViewMenu } from "./view-menu.js";
 function SingletonView({ singletonDefinition, adminConfig, document: loadedDocument, initialData, locale, contentLocales, defaultContentLocale }) {
@@ -201,7 +202,7 @@ function SingletonView({ singletonDefinition, adminConfig, document: loadedDocum
             toast(t('collections.edit.copyToLocaleTitle', {
                 label
             }), t("collections.edit.copyFailedDescription", {
-                message: t('documentConcurrency.failed')
+                message: describeMutationFailure(err, t)
             }), 'danger');
             throw err;
         }

package/dist/server-fns/collections/create.js

@@ -2,15 +2,17 @@ import { createServerFn } from "@tanstack/react-start";
 import { getAdminRequestContext } from "@byline/client/server";
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from "@byline/core";
 import { createDocument } from "@byline/core/services";
+import { getDefaultStatus } from "@byline/core/workflow";
 import { ensureCollection } from "../../integrations/api-utils.js";
 import { adminSessionMiddleware } from "../../integrations/session-middleware.js";
 import { withDocumentMutationErrors } from "../document-mutation-errors.js";
+import { validateDocumentWriteInput } from "../document-write-input.js";
 import { toCommittedDocumentHookFailureResponse } from "./save-outcome.js";
 const createCollectionDocument = createServerFn({
     method: 'POST'
 }).middleware([
     adminSessionMiddleware
-]).validator((input)=>input).handler(withDocumentMutationErrors(async ({ data: input })=>{
+]).validator((input)=>validateDocumentWriteInput(input, 'create')).handler(withDocumentMutationErrors(async ({ data: input })=>{
     const { collection: path, data: documentData, locale, path: explicitPath, availableLocales } = input;
     const logger = getLogger();
     const config = await ensureCollection(path);
@@ -36,7 +38,7 @@ const createCollectionDocument = createServerFn({
     try {
         result = await createDocument(ctx, {
             data: structuredClone(documentData),
-            status: documentData.status,
+            status: getDefaultStatus(config.definition),
             locale: locale ?? serverConfig.i18n.content.defaultLocale,
             path: explicitPath,
             availableLocales

package/dist/server-fns/collections/restore-version.d.ts

@@ -23,4 +23,5 @@ export declare const restoreDocumentVersion: import("@tanstack/react-start").Req
     revision: number;
     documentVersionId: string;
     sourceVersionId: string;
+    validationIssues?: import("@byline/core").DocumentFieldIssue[] | undefined;
 }>>;

package/dist/server-fns/collections/restore-version.js

@@ -43,7 +43,10 @@ const restore_version_restoreDocumentVersion = createServerFn({
             documentId: result.documentId,
             revision: result.revision,
             documentVersionId: result.documentVersionId,
-            sourceVersionId: result.sourceVersionId
+            sourceVersionId: result.sourceVersionId,
+            ...result.validationIssues ? {
+                validationIssues: result.validationIssues
+            } : {}
         };
     } catch (error) {
         const committedFailure = toCommittedDocumentHookFailureResponse(error);

package/dist/server-fns/collections/update.js

@@ -5,12 +5,13 @@ import { saveDocument, updateDocumentSystemFields } from "@byline/core/services"
 import { ensureCollection } from "../../integrations/api-utils.js";
 import { adminSessionMiddleware } from "../../integrations/session-middleware.js";
 import { withDocumentMutationErrors } from "../document-mutation-errors.js";
+import { validateDocumentWriteInput } from "../document-write-input.js";
 import { toCommittedDocumentHookFailureResponse } from "./save-outcome.js";
 const updateCollectionDocumentWithPatches = createServerFn({
     method: 'POST'
 }).middleware([
     adminSessionMiddleware
-]).validator((input)=>input).handler(withDocumentMutationErrors(async ({ data: input })=>{
+]).validator((input)=>validateDocumentWriteInput(input, 'patch')).handler(withDocumentMutationErrors(async ({ data: input })=>{
     const { collection: path, id, patches, expectedRevision, locale, path: explicitPath, availableLocales } = input;
     const logger = getLogger();
     const config = await ensureCollection(path);
@@ -60,7 +61,7 @@ const updateCollectionDocumentSystemFields = createServerFn({
     method: 'POST'
 }).middleware([
     adminSessionMiddleware
-]).validator((input)=>input).handler(withDocumentMutationErrors(async ({ data: input })=>{
+]).validator((input)=>validateDocumentWriteInput(input, 'metadata')).handler(withDocumentMutationErrors(async ({ data: input })=>{
     const { collection: path, id, expectedRevision, locale, path: explicitPath, availableLocales } = input;
     const logger = getLogger();
     const config = await ensureCollection(path);

package/dist/server-fns/document-mutation-errors.js

@@ -1,4 +1,4 @@
-import { BylineError, ErrorCodes, getDocumentRevisionValidationDetails, getDocumentStaleDetails, getLockConflictDetails } from "@byline/core";
+import { BylineError, ErrorCodes, getDocumentFieldValidationDetails, getDocumentRevisionValidationDetails, getDocumentStaleDetails, getLockConflictDetails } from "@byline/core";
 import { getDocumentHookCommittedDetails } from "@byline/core/services";
 import { committedTreeReceipt } from "./structural-receipt.js";
 function documentMutationError(error) {
@@ -14,6 +14,12 @@ function documentMutationError(error) {
         message: 'Reload this document before making changes.',
         details: validation
     };
+    const fields = getDocumentFieldValidationDetails(error);
+    if (fields) return {
+        code: ErrorCodes.VALIDATION,
+        message: 'Some document fields are invalid.',
+        details: fields
+    };
     const lock = getLockConflictDetails(error);
     if (lock) return {
         code: ErrorCodes.LOCK_CONFLICT,

package/dist/server-fns/document-write-input.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ */
+/** Shape checks complement lifecycle authorization, revision and field validation. */
+export declare function validateDocumentWriteInput<T>(input: T, mode: 'create' | 'patch' | 'metadata'): T;

package/dist/server-fns/document-write-input.js

@@ -0,0 +1,44 @@
+import { ERR_VALIDATION, parseInstancePath } from "@byline/core";
+const object = (value)=>null !== value && 'object' == typeof value && !Array.isArray(value);
+const document_write_input_text = (value)=>'string' == typeof value && value.trim().length > 0;
+const index = (value)=>Number.isSafeInteger(value) && value >= 0;
+const path = (value)=>document_write_input_text(value) && parseInstancePath(value).ok;
+function patches(value) {
+    return Array.isArray(value) && value.every((patch)=>{
+        if (!object(patch) || !path(patch.path)) return false;
+        if (void 0 !== patch.opId && !document_write_input_text(patch.opId)) return false;
+        if (void 0 !== patch.timestamp && !document_write_input_text(patch.timestamp)) return false;
+        switch(patch.kind){
+            case 'field.set':
+                return 'value' in patch;
+            case 'field.clear':
+                return true;
+            case 'array.insert':
+                return 'item' in patch && (void 0 === patch.index || index(patch.index));
+            case 'array.move':
+                return document_write_input_text(patch.itemId) && index(patch.toIndex);
+            case 'array.remove':
+                return document_write_input_text(patch.itemId);
+            case 'array.updateItem':
+                return document_write_input_text(patch.itemId) && patches(patch.patches);
+            case 'block.add':
+                return document_write_input_text(patch.blockType) && (void 0 === patch.index || index(patch.index));
+            case 'block.move':
+                return document_write_input_text(patch.blockId) && index(patch.toIndex);
+            case 'block.remove':
+                return document_write_input_text(patch.blockId);
+            case 'block.updateField':
+                return document_write_input_text(patch.blockId) && path(patch.fieldPath) && 'value' in patch;
+            default:
+                return false;
+        }
+    });
+}
+function validateDocumentWriteInput(input, mode) {
+    const valid = object(input) && document_write_input_text(input.collection) && ('create' === mode ? object(input.data) : document_write_input_text(input.id)) && (void 0 === input.locale || document_write_input_text(input.locale)) && (null == input.path || 'string' == typeof input.path) && (void 0 === input.availableLocales || Array.isArray(input.availableLocales) && input.availableLocales.every(document_write_input_text)) && ('patch' !== mode || patches(input.patches));
+    if (!valid) throw ERR_VALIDATION({
+        message: 'Invalid document write request.'
+    });
+    return input;
+}
+export { validateDocumentWriteInput };

package/dist/server-fns/singletons/restore-version.d.ts

@@ -15,4 +15,4 @@ export declare const restoreSingletonVersion: import("@tanstack/react-start").Re
     expectedRevision: number;
     singleton: string;
     versionId: string;
-}, Promise<import("@byline/core").SingletonSaveResult>>;
+}, Promise<import("../collections/save-outcome.js").CollectionDocumentCommittedHookFailureResponse | import("@byline/core").RestoreSingletonVersionResult>>;

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -124,16 +124,16 @@
     "clsx": "^2.1.1",
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
-    "zod": "^4.6.2",
-    "@byline/admin": "6.3.0",
-    "@byline/analytics": "6.3.0",
-    "@byline/analytics-agent": "6.3.0",
-    "@byline/ai": "6.3.0",
-    "@byline/client": "6.3.0",
-    "@byline/auth": "6.3.0",
-    "@byline/i18n": "6.3.0",
-    "@byline/ui": "6.3.0",
-    "@byline/core": "6.3.0"
+    "zod": "^4.6.5",
+    "@byline/ai": "6.4.0",
+    "@byline/analytics": "6.4.0",
+    "@byline/analytics-agent": "6.4.0",
+    "@byline/client": "6.4.0",
+    "@byline/ui": "6.4.0",
+    "@byline/admin": "6.4.0",
+    "@byline/auth": "6.4.0",
+    "@byline/core": "6.4.0",
+    "@byline/i18n": "6.4.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",
@@ -145,10 +145,10 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.13",
     "@rsbuild/plugin-react": "^2.1.0",
-    "@rslib/core": "^1.0.0",
-    "@tanstack/react-router": "^1.170.35",
-    "@tanstack/react-start": "^1.168.52",
-    "@types/node": "^26.5.1",
+    "@rslib/core": "^1.0.1",
+    "@tanstack/react-router": "^1.170.36",
+    "@tanstack/react-start": "^1.168.54",
+    "@types/node": "^26.6.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
@@ -159,7 +159,7 @@
     "typescript": "^7.0.2",
     "typescript-plugin-css-modules": "^5.2.0",
     "vite": "^8.3.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public",

package/src/admin-shell/collections/edit.tsx

@@ -37,6 +37,7 @@ import {
   updateDocumentStatus,
 } from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
+import { describeMutationFailure } from '../describe-mutation-failure.js'
 import { useDocumentMutationState } from '../document-mutation-state.js'
 import { useTanStackNavigationGuard } from './tanstack-navigation-guard.js'
 import { ViewMenu } from './view-menu.js'
@@ -430,7 +431,7 @@ export const EditView = ({
       }
       console.error('Duplicate error:', err)
       const description = t('collections.edit.duplicateFailedDescription', {
-        message: t('documentConcurrency.failed'),
+        message: describeMutationFailure(err, t),
       })
       toastManager.add({
         title: t('collections.edit.duplicateTitle', { label: singular }),
@@ -526,7 +527,7 @@ export const EditView = ({
       }
       console.error('Copy to locale error:', err)
       const description = t('collections.edit.copyFailedDescription', {
-        message: t('documentConcurrency.failed'),
+        message: describeMutationFailure(err, t),
       })
       toastManager.add({
         title: t('collections.edit.copyToLocaleTitle', { label: singular }),

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -57,6 +57,18 @@ export function RestoreVersionModal({
     setError(null)
     try {
       const result = await restoreVersion()
+      // Restore is exempt from field validation, so this never blocks it. Name
+      // the fields so the editor understands why the next save is refused.
+      const issues = getRestoreValidationIssues(result)
+      if (issues.length > 0) {
+        toastManager.add({
+          title: t('collections.restore.validationIssuesToast'),
+          description: t('collections.restore.validationIssuesDescription', {
+            fields: issues.join(', '),
+          }),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
       if (hasCommittedDocumentHookFailure(result)) {
         toastManager.add({
           title: t('collections.save.hookFailedToast'),
@@ -146,6 +158,20 @@ export function RestoreVersionModal({
   )
 }
 
+/** Field paths of the restored content that today's validation rejects. */
+function getRestoreValidationIssues(result: unknown): string[] {
+  if (result == null || typeof result !== 'object') return []
+  const issues = (result as { validationIssues?: unknown }).validationIssues
+  if (!Array.isArray(issues)) return []
+  return issues
+    .map((issue) =>
+      issue != null && typeof issue === 'object' && typeof (issue as any).field === 'string'
+        ? (issue as { field: string }).field
+        : ''
+    )
+    .filter((field) => field.length > 0)
+}
+
 function getErrorCode(err: unknown): string | null {
   return typeof (err as { code?: unknown })?.code === 'string'
     ? (err as { code: string }).code

package/src/admin-shell/describe-mutation-failure.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { getDocumentFieldValidationDetails } from '@byline/core'
+import type { TranslationValues } from '@byline/i18n'
+
+/**
+ * Describe a failed document mutation for the editor.
+ *
+ * Content writes that are not restores — create, update, patch saves,
+ * duplication and locale copies — keep the field-validation gate, because each
+ * reads or authors content the editor can open and correct. Naming the
+ * offending fields is what makes that correction actionable; without it the
+ * editor sees only a generic failure.
+ */
+export function describeMutationFailure(
+  err: unknown,
+  t: (key: string, values?: TranslationValues) => string
+): string {
+  const validation = getDocumentFieldValidationDetails(err)
+  if (validation == null) return t('documentConcurrency.failed')
+  return t('collections.edit.invalidFieldsMessage', {
+    fields: validation.issues.map((issue) => issue.field || '?').join(', '),
+  })
+}

package/src/admin-shell/singletons/view.tsx

@@ -37,6 +37,7 @@ import {
 } from '../../server-fns/singletons/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { useTanStackNavigationGuard } from '../collections/tanstack-navigation-guard.js'
+import { describeMutationFailure } from '../describe-mutation-failure.js'
 import { useDocumentMutationState } from '../document-mutation-state.js'
 import { SingletonViewMenu } from './view-menu.js'
 import type { ContentLocaleOption } from '../collections/view-menu.js'
@@ -287,7 +288,7 @@ export function SingletonView({
       }
       toast(
         t('collections.edit.copyToLocaleTitle', { label }),
-        t('collections.edit.copyFailedDescription', { message: t('documentConcurrency.failed') }),
+        t('collections.edit.copyFailedDescription', { message: describeMutationFailure(err, t) }),
         'danger'
       )
       throw err

package/src/server-fns/collections/create.ts

@@ -12,10 +12,12 @@ import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { CreateDocumentResult, DocumentLifecycleContext } from '@byline/core/services'
 import { createDocument } from '@byline/core/services'
+import { getDefaultStatus } from '@byline/core/workflow'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { withDocumentMutationErrors } from '../document-mutation-errors.js'
+import { validateDocumentWriteInput } from '../document-write-input.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -31,7 +33,7 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       locale?: string
       path?: string
       availableLocales?: string[]
-    }) => input
+    }) => validateDocumentWriteInput(input, 'create')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {
@@ -68,7 +70,8 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       try {
         result = await createDocument(ctx, {
           data: structuredClone(documentData),
-          status: documentData.status,
+          // The admin create flow always uses the configured initial status.
+          status: getDefaultStatus(config.definition),
           locale: locale ?? serverConfig.i18n.content.defaultLocale,
           path: explicitPath,
           availableLocales,

package/src/server-fns/collections/restore-version.ts

@@ -66,6 +66,10 @@ export const restoreDocumentVersion = createServerFn({ method: 'POST' })
           revision: result.revision,
           documentVersionId: result.documentVersionId,
           sourceVersionId: result.sourceVersionId,
+          // Restore is exempt from field validation; these describe what
+          // today's rules object to, so the editor can say what must be fixed
+          // before the next ordinary save.
+          ...(result.validationIssues ? { validationIssues: result.validationIssues } : {}),
         }
       } catch (error) {
         const committedFailure = toCommittedDocumentHookFailureResponse(error)

package/src/server-fns/collections/update.ts

@@ -17,6 +17,7 @@ import { saveDocument, updateDocumentSystemFields } from '@byline/core/services'
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { withDocumentMutationErrors } from '../document-mutation-errors.js'
+import { validateDocumentWriteInput } from '../document-write-input.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -35,7 +36,7 @@ export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POS
       path?: string | null
       availableLocales?: string[]
       locale?: string
-    }) => input
+    }) => validateDocumentWriteInput(input, 'patch')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {
@@ -115,7 +116,7 @@ export const updateCollectionDocumentSystemFields = createServerFn({ method: 'PO
       path?: string | null
       /** Editorial advertised-locale set; omitted means no advertised-locale write. */
       availableLocales?: string[]
-    }) => input
+    }) => validateDocumentWriteInput(input, 'metadata')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {

package/src/server-fns/document-mutation-errors.ts

@@ -1,6 +1,7 @@
 import {
   BylineError,
   ErrorCodes,
+  getDocumentFieldValidationDetails,
   getDocumentRevisionValidationDetails,
   getDocumentStaleDetails,
   getLockConflictDetails,
@@ -27,6 +28,13 @@ export function documentMutationError(error: unknown): unknown {
       message: 'Reload this document before making changes.',
       details: validation,
     }
+  const fields = getDocumentFieldValidationDetails(error)
+  if (fields)
+    return {
+      code: ErrorCodes.VALIDATION,
+      message: 'Some document fields are invalid.',
+      details: fields,
+    }
   const lock = getLockConflictDetails(error)
   if (lock)
     return {

package/src/server-fns/document-mutation-transport.test.node.ts

@@ -9,6 +9,7 @@ import {
   ERR_NOT_FOUND,
   ERR_TREE_HOOK_COMMITTED,
   ERR_VALIDATION,
+  getDocumentFieldValidationDetails,
   getDocumentRevisionValidationDetails,
   getDocumentStaleDetails,
   getLockConflictDetails,
@@ -209,3 +210,43 @@ it('transports unavailable-document errors without provider details', async () =
   })
   expect(wire).not.toMatch(/private|internal/)
 })
+
+describe('field validation over the installed transport', () => {
+  it('retains stable field paths and messages while dropping diagnostics', async () => {
+    const issues = [
+      { field: 'items[id=item-1].title', message: 'Title is required', kind: 'required' as const },
+    ]
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_VALIDATION({
+        message: 'private detail',
+        details: { reason: 'invalid_document_fields', issues, sql: 'SELECT secret' },
+        cause: new Error('private cause'),
+      })
+    })
+    expect(getDocumentFieldValidationDetails(value.error)).toEqual({
+      reason: 'invalid_document_fields',
+      issues,
+    })
+    expect(wire).not.toMatch(/private detail|SELECT secret|private cause/)
+    expect(getDocumentRevisionValidationDetails(value.error)).toBeNull()
+  })
+
+  it('never lets a malformed payload smuggle a waivable kind across the wire', async () => {
+    const { value } = await roundTrip({}, async () => {
+      throw ERR_VALIDATION({
+        message: 'private detail',
+        details: {
+          reason: 'invalid_document_fields',
+          issues: [
+            { field: 'title', message: 'Title is required' },
+            { field: 'summary', message: 'Summary is wrong', kind: 'bogus' },
+          ],
+        },
+      })
+    })
+    expect(getDocumentFieldValidationDetails(value.error)?.issues.map((i) => i.kind)).toEqual([
+      'invalid',
+      'invalid',
+    ])
+  })
+})

package/src/server-fns/document-write-input.test.node.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 } from 'vitest'
+
+import { validateDocumentWriteInput } from './document-write-input.js'
+
+describe('document write request shapes', () => {
+  it.each([null, {}, { collection: 'pages', data: [] }, { collection: 42, data: {} }])(
+    'rejects malformed create requests: %j',
+    (input) => {
+      expect(() => validateDocumentWriteInput(input, 'create')).toThrow(
+        'Invalid document write request'
+      )
+    }
+  )
+  it.each([
+    null,
+    [null],
+    [{ kind: 'field.set', path: 'title[' }],
+    [{ kind: 'array.move', path: 'items', itemId: 'a', toIndex: -1 }],
+    [{ kind: 'unknown', path: 'title' }],
+  ])('rejects malformed patches: %j', (patches) => {
+    expect(() =>
+      validateDocumentWriteInput({ collection: 'pages', id: 'doc', patches }, 'patch')
+    ).toThrow()
+  })
+  it('accepts nested patches and leaves revision checks to their dedicated contract', () => {
+    const input = {
+      collection: 'pages',
+      id: 'doc',
+      patches: [
+        {
+          kind: 'array.updateItem',
+          path: 'items',
+          itemId: 'a',
+          patches: [{ kind: 'field.set', path: 'title', value: 'Hello' }],
+        },
+      ],
+    }
+    expect(validateDocumentWriteInput(input, 'patch')).toBe(input)
+  })
+})

package/src/server-fns/document-write-input.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 { ERR_VALIDATION, parseInstancePath } from '@byline/core'
+
+const object = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+const text = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0
+const index = (value: unknown) => Number.isSafeInteger(value) && (value as number) >= 0
+const path = (value: unknown) => text(value) && parseInstancePath(value).ok
+
+function patches(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.every((patch) => {
+      if (!object(patch) || !path(patch.path)) return false
+      if (patch.opId !== undefined && !text(patch.opId)) return false
+      if (patch.timestamp !== undefined && !text(patch.timestamp)) return false
+      switch (patch.kind) {
+        case 'field.set':
+          return 'value' in patch
+        case 'field.clear':
+          return true
+        case 'array.insert':
+          return 'item' in patch && (patch.index === undefined || index(patch.index))
+        case 'array.move':
+          return text(patch.itemId) && index(patch.toIndex)
+        case 'array.remove':
+          return text(patch.itemId)
+        case 'array.updateItem':
+          return text(patch.itemId) && patches(patch.patches)
+        case 'block.add':
+          return text(patch.blockType) && (patch.index === undefined || index(patch.index))
+        case 'block.move':
+          return text(patch.blockId) && index(patch.toIndex)
+        case 'block.remove':
+          return text(patch.blockId)
+        case 'block.updateField':
+          return text(patch.blockId) && path(patch.fieldPath) && 'value' in patch
+        default:
+          return false
+      }
+    })
+  )
+}
+
+/** Shape checks complement lifecycle authorization, revision and field validation. */
+export function validateDocumentWriteInput<T>(input: T, mode: 'create' | 'patch' | 'metadata'): T {
+  const valid =
+    object(input) &&
+    text(input.collection) &&
+    (mode === 'create' ? object(input.data) : text(input.id)) &&
+    (input.locale === undefined || text(input.locale)) &&
+    (input.path == null || typeof input.path === 'string') &&
+    (input.availableLocales === undefined ||
+      (Array.isArray(input.availableLocales) && input.availableLocales.every(text))) &&
+    (mode !== 'patch' || patches(input.patches))
+  // Revision errors keep their existing, specialized lifecycle decoder.
+  if (!valid) throw ERR_VALIDATION({ message: 'Invalid document write request.' })
+  return input
+}