@byline/core 6.2.1 → 6.4.0

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

@@ -197,9 +197,9 @@ interface BaseField {
      * externally-assigned IDs like DOIs, fields that should only be set
      * by a workflow transition), not as a security boundary.
      *
-     * Whether a given widget honours this flag is per-widget — most ui-kit
-     * input components support a native readOnly state, and widgets are
-     * being progressively updated to forward this prop through.
+     * Built-in admin widgets honor this flag, including structural controls
+     * and descendants of groups, arrays, and blocks. Custom field components
+     * and rich-text editor replacements must implement the hint themselves.
      */
     readOnly?: boolean;
     /**
@@ -222,6 +222,25 @@ interface BaseField {
      * validation. Server-side schema validation knows nothing about
      * conditions, so pair conditionally-hidden required fields with
      * `optional: true` or a `defaultValue`.
+     *
+     * A field that is required only in particular circumstances is expressed
+     * explicitly, with `optional: true` plus a `validate` callback that decides
+     * from the document. The callback runs on both sides — the lifecycle
+     * enforces it, and the form reports it wherever the field is visible:
+     *
+     *     {
+     *       type: 'text', name: 'doi', optional: true,
+     *       condition: (data) => data.kind === 'journal',
+     *       validate: (value, data) =>
+     *         data.kind === 'journal' && !value ? 'DOI is required for journal articles' : undefined,
+     *     }
+     *
+     * Do not reach for `condition` to express requiredness. Beyond the contract
+     * above, restore and duplicate validate with `locale: 'all'`, where a
+     * localized value is a per-locale map rather than the single value the
+     * editor supplies — so a predicate reading one can disagree with itself
+     * across those paths. A `validate` callback that must run under `'all'`
+     * should account for the same shape.
      */
     condition?: FieldCondition;
     /**

package/dist/index.d.ts

@@ -25,5 +25,6 @@ export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js
 export { formatTextValue, looksLikeISODate, type SlugifierFn, type SlugifyContext, slugify, } from './utils/slugify.js';
 export { type FilenameSlugifierFn, type FilenameSlugifyContext, resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
+export { type DocumentFieldIssue, type DocumentFieldValidationDetails, getDocumentFieldValidationDetails, validateDocumentFields, } from './validation/document-fields.js';
 export * from './workflow/index.js';
 export type { ClaimedRecurringTask, ISchedulerStore, ReconcileTaskInput, RecurringTaskContext, RecurringTaskDefinition, RecurringTaskHealth, RecurringTaskResult, RecurringTaskStatus, } from './scheduler/types.js';

package/dist/index.js

@@ -37,4 +37,5 @@ export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js
 export { formatTextValue, looksLikeISODate, slugify, } from './utils/slugify.js';
 export { resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
+export { getDocumentFieldValidationDetails, validateDocumentFields, } from './validation/document-fields.js';
 export * from './workflow/index.js';

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

@@ -15,7 +15,7 @@ export declare const createBaseSchema: (collection?: CollectionDefinition) => z.
     createdBy: z.ZodOptional<z.ZodUUID>;
     eventType: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const createFieldsSchema: (fields: Field[], strict?: boolean) => z.ZodObject<{
+export declare const createFieldsSchema: (fields: readonly Field[], strict?: boolean) => z.ZodObject<{
     [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
 }, z.core.$strip>;
 export declare const createListMetaSchema: () => z.ZodObject<{

package/dist/schemas/zod/builder.js

@@ -5,10 +5,14 @@ import { getCollectionDefinition } from '../../config/config.js';
 const applyValidationRules = (schema, rules) => {
     return rules.reduce((acc, rule) => {
         switch (rule.type) {
+            case 'min':
+                return acc.min(rule.value, rule.message);
+            case 'max':
+                return acc.max(rule.value, rule.message);
             case 'email':
-                return acc.describe(rule.message || 'Invalid email address');
+                return acc.email(rule.message || 'Invalid email address');
             case 'url':
-                return acc.describe(rule.message || 'Invalid URL');
+                return acc.url(rule.message || 'Invalid URL');
             case 'pattern':
                 return acc.regex(new RegExp(rule.value), rule.message);
             case 'custom':
@@ -21,13 +25,13 @@ const applyValidationRules = (schema, rules) => {
 // Helper function to apply text field validation
 const applyTextValidation = (schema, field) => {
     let validatedSchema = schema;
-    if (field.validation?.minLength) {
+    if (field.validation?.minLength != null) {
         validatedSchema = validatedSchema.min(field.validation.minLength);
     }
-    if (field.validation?.maxLength) {
+    if (field.validation?.maxLength != null) {
         validatedSchema = validatedSchema.max(field.validation.maxLength);
     }
-    if (field.validation?.pattern) {
+    if (field.validation && 'pattern' in field.validation && field.validation.pattern) {
         validatedSchema = validatedSchema.regex(new RegExp(field.validation.pattern));
     }
     return validatedSchema;
@@ -57,8 +61,6 @@ export const fieldToZodSchema = (field, strict = true) => {
             // (assigned client-side on add, persisted via store_meta) — always
             // accepted, never required. `.passthrough()` tolerates auxiliary keys
             // (e.g. legacy seed-data `id` aliases) instead of stripping them.
-            // Group children stay `z.any()` via the `group` case below — the same
-            // depth boundary top-level groups have.
             const itemShape = {
                 _id: z.string().optional(),
             };
@@ -75,6 +77,8 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = arraySchema;
             break;
         }
+        case 'textArea':
+        case 'code':
         case 'text': {
             let textSchema = z.string();
             textSchema = applyTextValidation(textSchema, field);
@@ -97,6 +101,10 @@ export const fieldToZodSchema = (field, strict = true) => {
                 schema = z.string();
             }
             break;
+        case 'time':
+            schema = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
+            break;
+        case 'date':
         case 'datetime': {
             const dateSchema = z.preprocess((val) => (val === '' || val == null ? null : val), z.coerce.date().refine((val) => val.toString() !== 'Invalid Date', {
                 message: 'Invalid date',
@@ -106,6 +114,12 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = dateSchema;
             break;
         }
+        case 'json':
+            schema = z.json();
+            break;
+        case 'object':
+            schema = z.record(z.string(), z.json());
+            break;
         case 'richText': {
             const richTextSchema = z.any();
             // TODO: Implement rich text validation if needed
@@ -122,39 +136,21 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = richTextSchema;
             break;
         }
-        case 'textArea': {
-            let textAreaSchema = z.string();
-            if (field.validation?.minLength) {
-                textAreaSchema = textAreaSchema.min(field.validation.minLength);
-            }
-            if (field.validation?.maxLength) {
-                textAreaSchema = textAreaSchema.max(field.validation.maxLength);
-            }
-            schema = textAreaSchema;
-            break;
-        }
-        case 'code': {
-            let codeSchema = z.string();
-            if (field.validation?.minLength) {
-                codeSchema = codeSchema.min(field.validation.minLength);
-            }
-            if (field.validation?.maxLength) {
-                codeSchema = codeSchema.max(field.validation.maxLength);
-            }
-            schema = codeSchema;
-            break;
-        }
         case 'integer':
-            schema = z.number().int();
+        case 'float': {
+            let numeric = field.type === 'integer' ? z.number().int() : z.number();
+            if (field.validation?.min != null)
+                numeric = numeric.min(field.validation.min);
+            if (field.validation?.max != null)
+                numeric = numeric.max(field.validation.max);
+            schema = numeric;
             break;
+        }
         case 'counter':
             // Counter values are allocator-assigned; the wrapping below forces
             // the schema to allow undefined regardless of `field.optional`.
             schema = z.number().int();
             break;
-        case 'float':
-            schema = z.number();
-            break;
         case 'decimal':
             // Postgres numeric values are restored as strings to preserve precision.
             schema = z.string();
@@ -184,14 +180,19 @@ export const fieldToZodSchema = (field, strict = true) => {
                 .passthrough();
             break;
         }
-        case 'blocks':
-            schema = z.any().array();
+        case 'blocks': {
+            const variants = field.blocks.map((block) => z
+                .object({
+                ...createFieldsSchema(block.fields, strict).shape,
+                _id: z.string().optional(),
+                _type: z.literal(block.blockType),
+            })
+                .passthrough());
+            schema = strict ? z.array(variants.length ? z.union(variants) : z.never()) : z.any().array();
             break;
+        }
         case 'group':
-            // Group fields are complex nested structures validated at the
-            // field-renderer level. The shape depends on the group's child fields
-            // (recursive) and is not constrained here.
-            schema = z.any();
+            schema = strict ? createFieldsSchema(field.fields, true) : z.any();
             break;
         case 'relation': {
             // Relation values are `RelatedDocumentValue` objects:

package/dist/schemas/zod/builder.test.node.js

@@ -100,12 +100,12 @@ describe('array item schemas', () => {
         const result = schemas.fields.safeParse({ title: 'FAQ page', faq: [] });
         expect(result.success).toBe(false);
     });
-    it('leaves group children permissive inside items', () => {
+    it('validates required group children inside items', () => {
         const result = schemas.fields.safeParse({
             title: 'FAQ page',
             faq: [{ ...faqItem, meta: { anything: true } }],
         });
-        expect(result.success).toBe(true);
+        expect(result.success).toBe(false);
     });
     it('keeps reads lenient — items with missing children still parse in the get schema', () => {
         const parsed = schemas.get.parse({

package/dist/schemas/zod/review-comparison-probe.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schemas/zod/review-comparison-probe.test.node.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { defineCollection } from '../../@types/collection-types.js';
+import { createCollectionSchemas } from './builder.js';
+const collection = defineCollection({
+    path: 'review-probe', labels: { singular: 'Probe', plural: 'Probes' },
+    fields: [{ name: 'choice', type: 'select', options: [{ label: 'A', value: 'a' }] }],
+});
+const schemas = createCollectionSchemas(collection);
+const doc = {
+    id: '550e8400-e29b-41d4-a716-446655440000', status: 'draft',
+    createdAt: '2026-09-16T12:00:00.000Z', updatedAt: '2026-09-16T12:00:00.000Z',
+    fields: { choice: 'a' },
+};
+const response = {
+    docs: [doc], meta: { page: 1, pageSize: 10, total: 1, totalPages: 1 },
+    included: { collection: { id: 'review-probe', path: collection.path, labels: collection.labels } },
+};
+describe('review comparison: invalid values reject a read response', () => {
+    it('accepts a valid response', () => expect(schemas.list.safeParse(response).success).toBe(true));
+    it('rejects the response if one document has an invalid select', () => {
+        expect(schemas.list.safeParse({ ...response, docs: [doc, { ...doc, fields: { choice: 'bogus' } }] }).success).toBe(false);
+    });
+    it('rejects the response if one document has an invalid status', () => {
+        expect(schemas.list.safeParse({ ...response, docs: [doc, { ...doc, status: 'bogus' }] }).success).toBe(false);
+    });
+});

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

@@ -11,7 +11,7 @@ import { ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { slugify } from '../../utils/slugify.js';
-import { getDefaultStatus } from '../../workflow/workflow.js';
+import { getDefaultStatus, getWorkflowStatuses } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { requireTreeAuditCapability } from './audit.js';
@@ -19,6 +19,21 @@ import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 import { persistInitialDocumentVersion } from './persistence.js';
 import { assertLifecycleTransactionOwnership } from './revision-guard.js';
+/** Creating at the configured default is authorized by create itself. */
+function initialStatus(ctx, requested) {
+    const defaultStatus = getDefaultStatus(ctx.definition);
+    const status = requested ?? defaultStatus;
+    if (typeof status !== 'string' ||
+        !getWorkflowStatuses(ctx.definition).some((s) => s.name === status)) {
+        throw ERR_VALIDATION({ message: 'The initial status is not declared by this collection.' });
+    }
+    if (status !== defaultStatus) {
+        assertActorCanPerform(ctx.requestContext, ctx.definition, 'changeStatus');
+        if (status === 'published')
+            assertActorCanPerform(ctx.requestContext, ctx.definition, 'publish');
+    }
+    return status;
+}
 /**
  * Create a new document.
  *
@@ -45,6 +60,12 @@ export async function createDocument(ctx, params) {
         const slugifier = ctx.slugifier ?? slugify;
         const hooks = await resolveHooks(definition);
         const data = params.data;
+        if (data == null || typeof data !== 'object' || Array.isArray(data)) {
+            throw ERR_VALIDATION({ message: 'Document fields must be an object.' });
+        }
+        // Reject unauthorized overrides before hooks or counter allocation. Recheck
+        // after preparation too: hooks can change the legacy data.status value.
+        initialStatus(ctx, params.status ?? data.status);
         if (params.locale != null && params.locale !== defaultLocale) {
             throw ERR_VALIDATION({
                 message: `documents must be created in the default content locale ('${defaultLocale}'); received '${params.locale}'. Create the default-locale version first, then add localised versions via update.`,
@@ -80,7 +101,7 @@ export async function createDocument(ctx, params) {
             documentData: data,
             path: resolvedPath,
             availableLocales: params.availableLocales,
-            status: params.status ?? data.status ?? getDefaultStatus(definition),
+            status: initialStatus(ctx, params.status ?? data.status),
             locale: params.locale ?? defaultLocale,
             orderKey,
         }).catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale, 'create'));

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

@@ -5,11 +5,47 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { assertDocumentFields } from '../../validation/document-fields.js';
 import { requireAuditCapability } from './audit.js';
 import { actorId } from './internals.js';
 import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
 import { normalizeDocumentVersionParentError } from './stale-document.js';
 import { appendTreeRoot } from './tree.js';
+/**
+ * The single content gate for versioned writes.
+ *
+ * Restore is exempt, and the exemption is tied to `action: 'restore'` rather
+ * than to a caller-supplied flag: a write cannot obtain it without also
+ * declaring itself a restore in the audit trail. Only the document and
+ * singleton restore services set that action.
+ *
+ * The exemption exists because a historical version cannot be corrected
+ * through ordinary editing before it is restored. Two independent sources of
+ * failure make that fatal rather than inconvenient: the collection's schema
+ * may have tightened since the version was written, and validation rules
+ * themselves may have changed — corrected `email` and `url` rules can fail a
+ * version whose schema never moved at all. Either way the content becomes
+ * permanently unrecoverable.
+ *
+ * Its consequences are deliberate recovery semantics, not guarantees about
+ * restored content:
+ *
+ *  - `beforeUpdate` hooks on a restore run inside the exemption, so content
+ *    they produce is not validated either.
+ *  - A workflow whose `defaultStatus` is `published` republishes restored
+ *    content that fails today's validation.
+ *
+ * The restored version is still subject to authorization, revision and version
+ * ownership checks, hooks, and storage constraints, and the next ordinary
+ * content save enforces current validation in full. Schema-aware
+ * reconstruction and repair-before-commit are separate future work; skipping
+ * validation does not address them.
+ */
+function assertWritableContent(ctx, write) {
+    if (write.action === 'restore')
+        return;
+    assertDocumentFields(ctx.definition.fields, write.documentData, write.locale ?? ctx.defaultLocale, ctx.logger);
+}
 /**
  * Persist the first version of a logical document with lifecycle-owned
  * registration and actor metadata. Authentication, hooks, normalization,
@@ -17,6 +53,7 @@ import { appendTreeRoot } from './tree.js';
  * so their sequencing remains explicit.
  */
 export async function persistInitialDocumentVersion(ctx, write) {
+    assertWritableContent(ctx, write);
     return requireAuditCapability(ctx.db).withTransaction(async () => {
         await ctx.db.commands.collections.lockCollectionRegistration(ctx.collectionId, ctx.definition.tree === true || ctx.definition.singleton === true ? 'exclusive' : 'shared');
         const result = await ctx.db.commands.documents.createDocumentVersion({
@@ -37,6 +74,7 @@ export async function persistInitialDocumentVersion(ctx, write) {
  * hook sequencing remains in the caller.
  */
 export function persistExistingDocumentVersion(ctx, write) {
+    assertWritableContent(ctx, write);
     return commitContentVersionWithScheduleSuspension({
         ctx,
         documentId: write.documentId,

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

@@ -5,12 +5,20 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { DocumentFieldIssue } from '../../validation/document-fields.js';
 import type { DocumentLifecycleContext } from './context.js';
 export interface RestoreVersionResult {
     revision: number;
     documentId: string;
     documentVersionId: string;
     sourceVersionId: string;
+    /**
+     * Ways the restored content fails today's field validation. Restore is
+     * exempt from that gate, so these never block it — they are reported so the
+     * editor can say what must be fixed before the next ordinary save, which is
+     * validated in full.
+     */
+    validationIssues?: DocumentFieldIssue[];
 }
 /**
  * Restore a historical document version as the new current version.
@@ -23,9 +31,22 @@ export interface RestoreVersionResult {
  * `current_documents` view (`ROW_NUMBER() OVER PARTITION BY document_id
  * ORDER BY created_at DESC`) automatically promotes the new row to current.
  *
- * Status is hard-defaulted to the workflow's first status — restoring an
- * old `published` version must never silently re-publish content. The user
- * runs the restored draft through the normal workflow.
+ * Status is hard-defaulted to the collection's configured default status.
+ * For the standard editorial workflow that is `draft`, so restoring an old
+ * `published` version does not re-publish it and the user runs the restored
+ * draft through the normal workflow. It is NOT a guarantee: a workflow whose
+ * `defaultStatus` is `published` — `SINGLE_STATUS_WORKFLOW`, or any workflow
+ * configured that way — restores directly to published.
+ *
+ * Restore is exempt from the field-validation gate that every other versioned
+ * write passes through (see `assertWritableContent`). Historical content was
+ * persisted under earlier schema and validation rules, and cannot be corrected
+ * before it is restored; enforcing today's rules would make it permanently
+ * unrecoverable. Combined with the status default above, that means a
+ * published-default workflow can republish restored content which fails
+ * current validation, and `beforeUpdate` hooks on a restore run inside the
+ * same exemption. Both are accepted recovery semantics. The issues are
+ * computed and returned as `validationIssues` for the editor to report.
  *
  * `path` is sticky from the previous current version (not from the source),
  * matching the semantics of `updateDocument`. A path change made between

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

@@ -9,6 +9,7 @@ import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
+import { validateDocumentFields } from '../../validation/document-fields.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
@@ -25,9 +26,22 @@ import { commitGuardedDocumentMutation, readDocumentForMutation } from './revisi
  * `current_documents` view (`ROW_NUMBER() OVER PARTITION BY document_id
  * ORDER BY created_at DESC`) automatically promotes the new row to current.
  *
- * Status is hard-defaulted to the workflow's first status — restoring an
- * old `published` version must never silently re-publish content. The user
- * runs the restored draft through the normal workflow.
+ * Status is hard-defaulted to the collection's configured default status.
+ * For the standard editorial workflow that is `draft`, so restoring an old
+ * `published` version does not re-publish it and the user runs the restored
+ * draft through the normal workflow. It is NOT a guarantee: a workflow whose
+ * `defaultStatus` is `published` — `SINGLE_STATUS_WORKFLOW`, or any workflow
+ * configured that way — restores directly to published.
+ *
+ * Restore is exempt from the field-validation gate that every other versioned
+ * write passes through (see `assertWritableContent`). Historical content was
+ * persisted under earlier schema and validation rules, and cannot be corrected
+ * before it is restored; enforcing today's rules would make it permanently
+ * unrecoverable. Combined with the status default above, that means a
+ * published-default workflow can republish restored content which fails
+ * current validation, and `beforeUpdate` hooks on a restore run inside the
+ * same exemption. Both are accepted recovery semantics. The issues are
+ * computed and returned as `validationIssues` for the editor to report.
  *
  * `path` is sticky from the previous current version (not from the source),
  * matching the semantics of `updateDocument`. A path change made between
@@ -119,6 +133,15 @@ export async function restoreDocumentVersion(ctx, params) {
         //
         // No `path` is passed: restore does not change the document's path
         // (the existing byline_document_paths row stays as-is — sticky).
+        // Restore is exempt from the content-validation gate (see
+        // assertWritableContent). Validate anyway, for reporting only: the
+        // editor needs to know what today's rules object to before its next
+        // save, which is validated in full. Run it after the hook and embed
+        // pass so it describes exactly what is about to be persisted.
+        const validationIssues = validateDocumentFields(definition.fields, sourceFields, {
+            locale: 'all',
+            onCallbackError: ({ path, site, error }) => ctx.logger.error({ err: error, fieldPath: path, site }, 'restore diagnostic callback threw'),
+        });
         const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId, locale: 'all' }, async () => {
             const result = await persistExistingDocumentVersion(ctx, {
                 documentId: params.documentId,
@@ -150,6 +173,7 @@ export async function restoreDocumentVersion(ctx, params) {
             documentVersionId,
             sourceVersionId: params.sourceVersionId,
             revision,
+            ...(validationIssues.length > 0 ? { validationIssues } : {}),
         };
     });
 }