@byline/core 4.3.0 → 4.4.1

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

@@ -1152,9 +1152,15 @@ export interface CollectionDefinition {
      *
      * Receives the same minimal document shape as
      * `CollectionAdminConfig.preview.url` (`PreviewDocument`-style envelope:
-     * top-level columns plus `fields`) so the two hooks can share an
-     * implementation today and `preview.url` can default to
-     * `buildDocumentPath` in a later pass.
+     * top-level columns plus `fields`), so the two hooks can share an
+     * implementation. `preview.url` already defaults to this hook when
+     * omitted — see `resolvePreviewUrl` in `@byline/host-tanstack-start` —
+     * so the admin Preview button and the public path agree by construction.
+     *
+     * Note the `null` return is read differently by the two surfaces:
+     * `resolvePreviewUrl` hides the Preview affordance, while the richtext
+     * walker treats it as "no path could be built" and falls through to the
+     * generic `/${collectionPath}/${path}` compose.
      */
     buildDocumentPath?: (doc: {
         id: string;

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

@@ -58,7 +58,8 @@ export interface FieldHookContext {
      */
     data: Record<string, any>;
     /**
-     * Dot-path of the field inside the document, e.g. `"content.0.richText"`.
+     * Instance path of the field inside the document, e.g.
+     * `"content[id=block-id].richText"`.
      */
     path: string;
     /**
@@ -85,7 +86,7 @@ export interface FieldHookContext {
      * items (a checkbox that unchecks its siblings) or clearing a dependent
      * field when its driver changes. Paths use the same dot + bracket
      * notation as `FieldHookContext.path`, e.g.
-     * `files[1].filesGroup.generateThumbnail`.
+     * `files[id=file-id].filesGroup.generateThumbnail`.
      */
     setFieldValue: (path: string, value: any) => void;
 }

package/dist/config/attach-hooks.js

@@ -1,3 +1,4 @@
+import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 const registryCollectionHooks = new WeakMap();
 const registryUploadHooks = new WeakMap();
 /**
@@ -9,7 +10,7 @@ export function prepareHookAttachment(config) {
     const collections = new Map();
     const uploadFields = new Map();
     for (const collection of config.collections) {
-        assertDotFreeSegment(collection.path, `collection path "${collection.path}"`);
+        assertPathSafeSegment(collection.path, `collection path "${collection.path}"`);
         collections.set(collection.path, collection);
         indexUploadFields(collection, uploadFields);
     }
@@ -97,34 +98,43 @@ function assertOwnershipIntact(label, current, owned) {
 }
 function indexUploadFields(collection, uploadFields) {
     const leafPaths = new Map();
-    const walk = (fields, prefix) => {
-        for (const field of fields) {
-            assertDotFreeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
-            const path = [...prefix, field.name];
-            if ((field.type === 'file' || field.type === 'image') && field.upload !== undefined) {
-                const canonical = [collection.path, ...path].join('.');
-                const previous = leafPaths.get(field.name);
-                if (previous !== undefined) {
-                    throw new Error(`Collection "${collection.path}" has duplicate upload-capable leaf name "${field.name}" at "${previous}" and "${canonical}". Upload leaf names must be unique within a collection.`);
-                }
-                leafPaths.set(field.name, canonical);
-                uploadFields.set(canonical, field);
-            }
-            if (field.type === 'group' || field.type === 'array') {
-                walk(field.fields, path);
-            }
-            else if (field.type === 'blocks') {
-                for (const block of field.blocks) {
-                    assertDotFreeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
-                    walk(block.fields, [...path, block.blockType]);
-                }
-            }
+    walkFieldDeclarations(collection.fields, (field, segments) => {
+        assertPathSafeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
+        if ((field.type !== 'file' && field.type !== 'image') || field.upload === undefined)
+            return;
+        const canonical = `${collection.path}.${formatDeclarationPath(segments)}`;
+        const previous = leafPaths.get(field.name);
+        if (previous !== undefined) {
+            throw new Error(`Collection "${collection.path}" has duplicate upload-capable leaf name "${field.name}" at "${previous}" and "${canonical}". Upload leaf names must be unique within a collection.`);
         }
-    };
-    walk(collection.fields, []);
+        leafPaths.set(field.name, canonical);
+        uploadFields.set(canonical, field);
+    }, {
+        // Every block is checked, including one declaring no fields — such a
+        // block never reaches the field visitor, so inferring block types from
+        // field segments alone would silently stop validating them.
+        onBlock: (block) => {
+            assertPathSafeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
+        },
+    });
 }
-function assertDotFreeSegment(segment, label) {
-    if (segment.length === 0 || segment.includes('.')) {
-        throw new Error(`${label} must be a non-empty, dot-free hook registry path segment.`);
+/**
+ * A name that appears as a path segment must not contain the grammar's own
+ * punctuation.
+ *
+ * `.` separates segments in every notation. `[` and `]` delimit item selectors
+ * in instance paths, which field names already reach — a field named `a[0]`
+ * would not survive the round trip through `parseInstancePath`. Both are
+ * rejected where the name is declared rather than left to corrupt a path
+ * later.
+ */
+function assertPathSafeSegment(segment, label) {
+    if (segment.length === 0) {
+        throw new Error(`${label} must be a non-empty path segment.`);
+    }
+    for (const character of ['.', '[', ']']) {
+        if (segment.includes(character)) {
+            throw new Error(`${label} must not contain "${character}" — it is field path grammar punctuation.`);
+        }
     }
 }

package/dist/config/attach-hooks.test.node.js

@@ -149,11 +149,11 @@ describe('server hook attachment', () => {
         await expect(initBylineCore(invalid, {})).rejects.toThrow(/translations bundle/i);
         expect(definition.hooks).toBe(stable);
     });
-    it('rejects dotted registry segments and duplicate upload leaf names at boot', () => {
-        expect(() => prepareHookAttachment({ collections: [collection('docs.archive')] })).toThrow(/dot-free/);
+    it('rejects path-punctuation in registry segments and duplicate upload leaf names at boot', () => {
+        expect(() => prepareHookAttachment({ collections: [collection('docs.archive')] })).toThrow(/grammar punctuation/);
         const dottedField = collection();
         dottedField.fields = [{ name: 'meta.asset', type: 'file', upload: {} }];
-        expect(() => prepareHookAttachment({ collections: [dottedField] })).toThrow(/dot-free/);
+        expect(() => prepareHookAttachment({ collections: [dottedField] })).toThrow(/grammar punctuation/);
         const dottedBlock = collection();
         dottedBlock.fields = [
             {
@@ -162,7 +162,21 @@ describe('server hook attachment', () => {
                 blocks: [{ blockType: 'hero.large', fields: [] }],
             },
         ];
-        expect(() => prepareHookAttachment({ collections: [dottedBlock] })).toThrow(/dot-free/);
+        expect(() => prepareHookAttachment({ collections: [dottedBlock] })).toThrow(/grammar punctuation/);
+        // Brackets delimit item selectors in instance paths, which field names
+        // reach — so they are rejected for the same reason dots are.
+        const bracketField = collection();
+        bracketField.fields = [{ name: 'asset[0]', type: 'file', upload: {} }];
+        expect(() => prepareHookAttachment({ collections: [bracketField] })).toThrow(/grammar punctuation/);
+        const bracketBlock = collection();
+        bracketBlock.fields = [
+            {
+                name: 'content',
+                type: 'blocks',
+                blocks: [{ blockType: 'hero[large]', fields: [] }],
+            },
+        ];
+        expect(() => prepareHookAttachment({ collections: [bracketBlock] })).toThrow(/grammar punctuation/);
         const duplicate = collection();
         duplicate.fields = [
             { name: 'primary', type: 'group', fields: [{ name: 'asset', type: 'file', upload: {} }] },

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

@@ -5,40 +5,18 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveDeclarationPath, walkFieldDeclarations, } from '../paths/index.js';
 /**
- * Resolve a dotted schema path (`faq.answer`, `files.filesGroup.publicationFile`)
- * against a field set. Schema paths address field *declarations*: every
- * segment names a field, intermediate segments must be `group` / `array`
- * structure fields, and no segment carries an item index. Returns:
+ * Resolve a `fields{}` override key against a field set.
  *
- *  - `'ok'`         — the path resolves to a field declaration;
- *  - `'blocks'`     — the path tries to traverse a `type: 'blocks'` field
- *                     (blocks resolve their own admin config from the
- *                     blockType-keyed registry, so this is always an error);
- *  - `'unresolved'` — a segment doesn't name a field, or a value field
- *                     appears mid-path.
+ * Admin override keys are declaration paths with one deliberate narrowing:
+ * they may not traverse a `blocks` field at all, even correctly qualified by
+ * block type. Fields inside a block take their overrides from the
+ * blockType-keyed `blockAdmin` registry, so that one registration applies
+ * wherever the block renders.
  */
 function resolveSchemaPath(fields, path) {
-    const segments = path.split('.');
-    let current = fields;
-    for (let i = 0; i < segments.length; i++) {
-        const name = segments[i];
-        const field = current.find((f) => 'name' in f && f.name === name);
-        if (field == null)
-            return 'unresolved';
-        if (i === segments.length - 1)
-            return 'ok';
-        if (field.type === 'group' || field.type === 'array') {
-            current = field.fields;
-        }
-        else if (field.type === 'blocks') {
-            return 'blocks';
-        }
-        else {
-            return 'unresolved';
-        }
-    }
-    return 'unresolved';
+    return resolveDeclarationPath(fields, path, { blocks: 'forbidden' }).status;
 }
 /**
  * Shared validation for a `fields{}` override map (collection- or block-level):
@@ -125,28 +103,16 @@ export function validateBlockAdminConfigs(blockAdmins, collections) {
     // between same-blockType declarations is possible, so keys validate against
     // the union of sites.
     const blocksByType = new Map();
-    const walkBlock = (block) => {
-        let sites = blocksByType.get(block.blockType);
-        if (sites == null) {
-            sites = [];
-            blocksByType.set(block.blockType, sites);
-        }
-        sites.push(block);
-        walkFields(block.fields);
-    };
-    const walkFields = (fields) => {
-        for (const field of fields) {
-            if (field.type === 'blocks') {
-                for (const block of field.blocks)
-                    walkBlock(block);
-            }
-            else if ('fields' in field && Array.isArray(field.fields)) {
-                walkFields(field.fields);
-            }
-        }
-    };
     for (const collection of collections) {
-        walkFields(collection.fields);
+        walkFieldDeclarations(collection.fields, () => { }, {
+            onBlock: (block) => {
+                const sites = blocksByType.get(block.blockType);
+                if (sites == null)
+                    blocksByType.set(block.blockType, [block]);
+                else
+                    sites.push(block);
+            },
+        });
     }
     const seen = new Set();
     for (const entry of blockAdmins) {

package/dist/config/validate-collections.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 import { fieldTypeToStore } from '../storage/field-store-map.js';
 /**
  * Field names that cannot be declared in a collection schema because they
@@ -61,37 +62,27 @@ function hasLocalizedField(fields) {
     });
     return found;
 }
+/** Every field declaration, for checks that don't care where it sits. */
 function walkFields(fields, visit) {
-    for (const field of fields) {
+    walkFieldDeclarations(fields, (field) => {
         visit(field);
-        if (field.type === 'group' || field.type === 'array') {
-            walkFields(field.fields, visit);
-        }
-        else if (field.type === 'blocks') {
-            for (const block of field.blocks) {
-                walkFields(block.fields, visit);
-            }
-        }
-    }
+    });
 }
 /**
- * Path-aware variant of `walkFields` — visits every field with its dotted
- * schema path (e.g. `files.filesGroup.generateThumbnail`) so validation
+ * Path-aware variant of `walkFields` — visits every field with its
+ * declaration path (e.g. `files.filesGroup.generateThumbnail`) so validation
  * errors can point at the exact declaration site.
+ *
+ * Delegates to the shared grammar's canonical walk. It previously descended
+ * into blocks without recording the block type, which made the emitted path
+ * ambiguous whenever two blocks in one field declared the same field name —
+ * both rendered as `content.alt`, and the message could not say which was at
+ * fault. `walkFieldDeclarations` carries the block type through.
  */
-function walkFieldsWithPath(fields, visit, prefix = '') {
-    for (const field of fields) {
-        const fieldPath = prefix === '' ? field.name : `${prefix}.${field.name}`;
-        visit(field, fieldPath);
-        if (field.type === 'group' || field.type === 'array') {
-            walkFieldsWithPath(field.fields, visit, fieldPath);
-        }
-        else if (field.type === 'blocks') {
-            for (const block of field.blocks) {
-                walkFieldsWithPath(block.fields, visit, fieldPath);
-            }
-        }
-    }
+function walkFieldsWithPath(fields, visit) {
+    walkFieldDeclarations(fields, (field, segments) => {
+        visit(field, formatDeclarationPath(segments));
+    });
 }
 /**
  * Top-level field names a collection's `search` config references (body +
@@ -114,6 +105,52 @@ function searchReferencedFieldNames(collection) {
     }
     return names;
 }
+/**
+ * Enforce that every field named by a collection's `search` config resolves.
+ *
+ * `buildSearchDocument` looks each name up among the collection's **top-level**
+ * fields and silently skips anything it cannot resolve, so an unrecognised or
+ * dotted name produced a collection that indexed less than its author thought
+ * — with no error at boot and no signal at index time.
+ *
+ * Nested content is reachable, but by naming its top-level *container*: a
+ * `group` / `array` / `blocks` field named in `search.body` is walked
+ * recursively and every nested text leaf is flattened into the body. What is
+ * not supported is addressing one specific nested declaration, which is why a
+ * dotted path is rejected outright rather than accepted and ignored.
+ */
+function validateSearchFields(collection) {
+    const search = collection.search;
+    if (search == null)
+        return;
+    const topLevel = (name) => collection.fields.find((f) => 'name' in f && f.name === name);
+    const check = (name, option) => {
+        if (name.includes('.')) {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.${option}\` but search config addresses top-level fields only. To index content nested inside a \`group\` / \`array\` / \`blocks\` field, name the top-level container — it is walked recursively and every nested text leaf is flattened into the body.`);
+        }
+        const field = topLevel(name);
+        if (field == null) {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.${option}\` but no top-level field with that name exists.`);
+        }
+        return field;
+    };
+    for (const decl of search.body ?? []) {
+        check(typeof decl === 'string' ? decl : decl.field, 'body');
+    }
+    for (const decl of search.facets ?? []) {
+        const name = typeof decl === 'string' ? decl : decl.field;
+        const field = check(name, 'facets');
+        if (field.type !== 'relation') {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.facets\` but field "${name}" has type "${field.type}". Facets are controlled-vocabulary references — name a \`relation\` field.`);
+        }
+    }
+    for (const name of search.filters ?? []) {
+        const field = check(name, 'filters');
+        if (field.type === 'group' || field.type === 'array' || field.type === 'blocks') {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.filters\` but field "${name}" has type "${field.type}". Filters project a single scalar value — name a value field.`);
+        }
+    }
+}
 /**
  * Enforce the `virtual` field constraints for one collection. See
  * `BaseField.virtual` in field-types.ts for the contract these rules back:
@@ -236,6 +273,7 @@ export function validateCollections(collections) {
         if (collection.tree === true && collection.orderable === true) {
             throw new Error(`Collection "${collection.path}" sets both \`tree: true\` and \`orderable: true\`. A document-tree collection owns ordering on the tree edge (per-parent), so \`byline_documents.order_key\` is inert — set only \`tree: true\`.`);
         }
+        validateSearchFields(collection);
         validateVirtualFields(collection);
         validateUploadLocations(collection);
     }

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

@@ -510,6 +510,68 @@ describe('validateCollections', () => {
                 },
             ],
         };
-        expect(() => validateCollections([collection])).toThrow(/content\.file.*must not contain duplicate slashes/s);
+        // The path names the block type, so the message identifies which block's
+        // `file` declaration is at fault rather than just `content.file`.
+        expect(() => validateCollections([collection])).toThrow(/content\.attachmentsBlock\.file.*must not contain duplicate slashes/s);
+    });
+});
+// ---------------------------------------------------------------------------
+// search config field resolution
+//
+// `buildSearchDocument` resolves each name among the collection's top-level
+// fields and silently skips what it cannot resolve, so an unrecognised name
+// used to produce a collection that indexed less than its author intended,
+// with no signal at boot or at index time.
+// ---------------------------------------------------------------------------
+describe('validateCollections — search config fields', () => {
+    const searchable = (search) => ({
+        ...baseCollection,
+        search,
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'summary', label: 'Summary', type: 'text' },
+            { name: 'featured', label: 'Featured', type: 'checkbox' },
+            { name: 'topics', label: 'Topics', type: 'relation', targetCollection: 'topics' },
+            { name: 'format', label: 'Format', type: 'select', options: [] },
+            {
+                name: 'files',
+                label: 'Files',
+                type: 'array',
+                fields: [
+                    {
+                        name: 'filesGroup',
+                        type: 'group',
+                        fields: [{ name: 'caption', label: 'Caption', type: 'text' }],
+                    },
+                ],
+            },
+        ],
+    });
+    it('accepts top-level names, including a container in body', () => {
+        expect(() => validateCollections([
+            searchable({
+                body: [{ field: 'title', boost: 2 }, 'summary', 'files'],
+                facets: ['topics'],
+                filters: ['featured'],
+            }),
+        ])).not.toThrow();
+    });
+    it('rejects a body name that does not exist', () => {
+        expect(() => validateCollections([searchable({ body: ['titel'] })])).toThrow(/no top-level field with that name exists/);
+    });
+    it('rejects a dotted path and explains what to name instead', () => {
+        // Accepting it would be worse than rejecting: the indexer would resolve
+        // nothing and silently index an empty body.
+        expect(() => validateCollections([searchable({ body: ['files.filesGroup.caption'] })])).toThrow(/top-level fields only.*name the top-level container/s);
+    });
+    it('rejects a facet that is not a relation', () => {
+        expect(() => validateCollections([searchable({ facets: ['format'] })])).toThrow(/Facets are controlled-vocabulary references/);
+    });
+    it('rejects a filter naming a container field', () => {
+        expect(() => validateCollections([searchable({ filters: ['files'] })])).toThrow(/Filters project a single scalar value/);
+    });
+    it('checks facets and filters too, not only body', () => {
+        expect(() => validateCollections([searchable({ facets: ['nope'] })])).toThrow(/no top-level field with that name exists/);
+        expect(() => validateCollections([searchable({ filters: ['nope'] })])).toThrow(/no top-level field with that name exists/);
     });
 });

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './l
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';
 export * from './patches/index.js';
+export * from './paths/index.js';
 export { mergePredicates, type ParseContext, type ParsedSort, type ParsedWhere, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';

package/dist/index.js

@@ -28,6 +28,7 @@ export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './l
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';
 export * from './patches/index.js';
+export * from './paths/index.js';
 export { mergePredicates, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';

package/dist/patches/apply-patches.js

@@ -1,6 +1,10 @@
 // Core implementation of the patch engine
 import { isBlocksField, isStructureField } from '../@types/field-types.js';
-// Very small path grammar:
+import { parseInstancePath } from '../paths/parse-path.js';
+// Instance-path grammar — see `@byline/core` `paths/`. Patch paths address
+// items, so they carry selectors and no block type (the item holds `_type`).
+//
+// Historical shapes, unchanged:
 // - "foo.bar" -> [{field: 'foo'}, {field: 'bar'}]
 // - "reviews[0].rating" -> [{field: 'reviews'}, {index: 0}, {field: 'rating'}]
 // - "reviews[id=abc].rating" -> [{field: 'reviews'}, {id: 'abc'}, {field: 'rating'}]
@@ -8,33 +12,19 @@ import { isBlocksField, isStructureField } from '../@types/field-types.js';
 export function parsePatchPath(path) {
     if (!path)
         return [];
-    const segments = [];
-    const parts = String(path).split('.');
-    for (const part of parts) {
-        const fieldMatch = part.match(/^([^[]+)/);
-        if (!fieldMatch) {
-            continue;
-        }
-        const field = fieldMatch[1];
-        segments.push({ kind: 'field', key: field });
-        const bracketRegex = /\[([^\]]+)\]/g;
-        let match;
-        // Biome: avoid assignment in the while condition
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            match = bracketRegex.exec(part);
-            if (match === null)
-                break;
-            const token = match[1];
-            if (/^\d+$/.test(token)) {
-                segments.push({ kind: 'index', index: Number.parseInt(token, 10) });
-            }
-            else if (token.startsWith('id=')) {
-                segments.push({ kind: 'id', id: token.slice(3) });
-            }
-        }
-    }
-    return segments;
+    const parsed = parseInstancePath(String(path));
+    // An unparseable path yields no segments, so callers reject the patch
+    // rather than applying it somewhere else. The previous hand-rolled parser
+    // was lenient — `"a["` produced `[field: 'a']`, and the patch was then
+    // applied at `a`, a path the client never addressed. Silent misapplication
+    // is a worse failure than a rejected patch.
+    if (!parsed.ok)
+        return [];
+    return parsed.segments.map((segment) => segment.kind === 'field'
+        ? // The grammar names this `name`; the patch resolver has always called
+            // it `key`. Renamed at the boundary rather than churning consumers.
+            { kind: 'field', key: segment.name }
+        : segment);
 }
 // Very small, best-effort resolver that walks the CollectionDefinition to find
 // the field targeted by a patch path. This is intentionally conservative and
@@ -187,7 +177,8 @@ function ensurePath(root, segments) {
 function applyFieldPatch(doc, patch) {
     const segments = parsePatchPath(patch.path);
     if (segments.length === 0) {
-        throw new Error('Empty path for field patch');
+        // Covers both an empty path and one that did not parse.
+        throw new Error(`Empty or unparseable path for field patch: ${JSON.stringify(patch.path ?? '')}`);
     }
     if (patch.kind === 'field.set') {
         const { parent, key } = ensurePath(doc, segments);

package/dist/patches/patch.test.node.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { applyPatches } from './apply-patches.js';
+import { applyPatches, parsePatchPath } from './apply-patches.js';
 const DocsDefinition = {
     path: 'docs',
     labels: {
@@ -156,6 +156,32 @@ describe('applyPatches', () => {
         const moved = afterMove;
         expect(moved.reviews.map((r) => r._id)).toEqual(['c', 'a', 'b']);
     });
+    it('applies field patches against the array order at that point in the patch stream', () => {
+        const original = {
+            links: [
+                { _id: 'a', link: 'A' },
+                { _id: 'b', link: 'B' },
+            ],
+        };
+        const positional = applyPatches(DocsDefinition, original, [
+            { kind: 'array.move', path: 'links', itemId: 'b', toIndex: 0 },
+            { kind: 'field.set', path: 'links[0].link', value: 'moved B' },
+        ]);
+        expect(positional.errors).toHaveLength(0);
+        expect(positional.doc.links).toEqual([
+            { _id: 'b', link: 'moved B' },
+            { _id: 'a', link: 'A' },
+        ]);
+        const stable = applyPatches(DocsDefinition, original, [
+            { kind: 'array.move', path: 'links', itemId: 'b', toIndex: 0 },
+            { kind: 'field.set', path: 'links[id=b].link', value: 'same B' },
+        ]);
+        expect(stable.errors).toHaveLength(0);
+        expect(stable.doc.links).toEqual([
+            { _id: 'b', link: 'same B' },
+            { _id: 'a', link: 'A' },
+        ]);
+    });
     it('array.remove removes an item by stable _id', () => {
         const original = {
             reviews: [
@@ -270,3 +296,51 @@ describe('applyPatches', () => {
         expect(updated.content[0]?.constrainedWidth).toBe(true);
     });
 });
+// ---------------------------------------------------------------------------
+// Patch paths are instance paths
+//
+// `parsePatchPath` delegates to the shared grammar's `parseInstancePath`
+// (`@byline/core` `paths/`). The two agree on every well-formed path; they
+// differ only in that a malformed one is now rejected rather than partially
+// parsed.
+// ---------------------------------------------------------------------------
+describe('parsePatchPath — shared instance-path grammar', () => {
+    it('parses positional and id selectors', () => {
+        expect(parsePatchPath('content[0].gallery[1].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'index', index: 0 },
+            { kind: 'field', key: 'gallery' },
+            { kind: 'index', index: 1 },
+            { kind: 'field', key: 'alt' },
+        ]);
+        expect(parsePatchPath('content[id=abc].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'id', id: 'abc' },
+            { kind: 'field', key: 'alt' },
+        ]);
+    });
+    it('carries no block-type segment — the addressed item holds its own `_type`', () => {
+        expect(parsePatchPath('content[0].alt')).not.toContainEqual({
+            kind: 'field',
+            key: 'photoBlock',
+        });
+    });
+    it('rejects a malformed path instead of parsing it partially', () => {
+        // Previously `'a['` yielded `[{ kind: 'field', key: 'a' }]`, so a patch
+        // was applied at `a` — a path the client never addressed. Returning no
+        // segments makes callers reject the patch instead.
+        for (const malformed of ['a[', 'a[]', 'a[x]', 'a]b', 'a..b']) {
+            expect(parsePatchPath(malformed)).toEqual([]);
+        }
+    });
+    it('surfaces a malformed path as a patch error rather than a silent write', () => {
+        const original = { title: 'original' };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'field.set', path: 'title[', value: 'injected' },
+        ]);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]?.message).toMatch(/unparseable path/i);
+        // The truncated path `title` is never written.
+        expect(doc.title).toBe('original');
+    });
+});

package/dist/paths/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+/**
+ * Field path grammar — one AST, two serialisations.
+ *
+ * See `path-types.ts` for the instance/declaration model, and
+ * `docs/04-collections/01-fields.md` for the author-facing account.
+ */
+export { formatDeclarationPath, formatInstancePath, parseDeclarationPath, parseInstancePath, toDeclarationSegments, } from './parse-path.js';
+export { resolveDeclarationPath, walkFieldDeclarations } from './resolve-path.js';
+export type { PathParseFailure, PathParseResult, PathResolution, PathSegment, ResolveOptions, } from './path-types.js';