@byline/core 1.3.0 → 1.5.0

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

@@ -7,7 +7,6 @@
  */
 import type { CollectionDefinition, WorkflowStatus } from './collection-types.js';
 import type { FieldComponentSlots } from './field-types.js';
-import type { PopulateSpec } from './populate-types.js';
 /**
  * Props passed to a custom list-view component registered via
  * `CollectionAdminConfig.listView`.
@@ -205,35 +204,43 @@ export interface CollectionAdminConfig<T = any> {
      * the preview link defaults to `/${collectionPath}/${doc.path}` — fine
      * for collections whose public URL mirrors the collection path.
      *
-     * Two parts:
+     * `url(doc, ctx)` — pure function returning the preview URL. Receives
+     * the loaded document and a small request-scoped context object
+     * carrying `locale`. Return `null` to indicate "no preview URL is
+     * meaningful for this document yet" — `<PreviewLink>` hides itself
+     * in that case (e.g. missing path, missing required relation, draft
+     * awaiting first save).
      *
-     *   - `populate` (optional) — populate hint applied when the admin loads
-     *     the document for the preview link. Lets `url(doc, ctx)` see resolved
-     *     relation values (e.g. `doc.fields.area?.document?.path`) instead
-     *     of the bare `RelatedDocumentValue` envelope. Selective by design —
-     *     full populate per-row would be expensive for list views if/when
-     *     preview links land there too.
+     * What's available on `doc`:
      *
-     *   - `url(doc, ctx)` — pure function returning the preview URL. Receives
-     *     the (optionally populated) document and a small request-scoped
-     *     context object carrying `locale`. Return `null` to indicate "no
-     *     preview URL is meaningful for this document yet" — `<PreviewLink>`
-     *     hides itself in that case (e.g. missing slug, missing required
-     *     relation, draft awaiting first save).
+     *   - **Top-level columns** — `id`, `path`, `status`. `path` is the
+     *     slug derived server-side from the collection's `useAsPath`
+     *     field; it is a reserved column on every document, not a
+     *     user-defined field. Address as `doc.path`, not `doc.fields.path`.
      *
-     * Example for a `pages` collection routed by `area` relation:
+     *   - **Field values** under `doc.fields` — every scalar / array /
+     *     block field of the source collection.
+     *
+     *   - **Direct relation targets** under `doc.fields.<name>?.document`
+     *     — the edit-view loader applies a blanket depth-1 populate so
+     *     relation tiles render with target data on first paint, and
+     *     `url(...)` inherits the same populated tree. The projection
+     *     follows the target's `picker` columns (plus top-level columns
+     *     like `path`, which are always present). Deeper hops, or fields
+     *     outside the target's picker projection, are NOT populated.
+     *
+     * Example for a `news` collection routed by its `category` relation:
      *
      * ```ts
      * preview: {
-     *   populate: { area: '*' },
      *   url: (doc, { locale }) => {
-     *     const area = doc.fields.area?.document?.path
-     *     const slug = doc.fields.slug
-     *     if (!slug) return null
+     *     if (!doc.path) return null
+     *     // `category` is a direct relation — auto-populated to depth 1.
+     *     const category = doc.fields.category?.document?.path
      *     const prefix = locale && locale !== 'en' ? `/${locale}` : ''
-     *     return area && area !== 'root'
-     *       ? `${prefix}/${area}/${slug}`
-     *       : `${prefix}/${slug}`
+     *     return category
+     *       ? `${prefix}/news/${category}/${doc.path}`
+     *       : `${prefix}/news/${doc.path}`
      *   },
      * }
      * ```
@@ -241,9 +248,17 @@ export interface CollectionAdminConfig<T = any> {
      * Returned URLs may be relative (`/news/foo`) for same-origin hosts
      * or absolute (`https://example.com/news/foo`) for hosts deployed
      * separately from the admin.
+     *
+     * Future consideration — a per-collection `preview.populate` hint
+     * (`PopulateSpec`) was prototyped and removed. The edit-view loader
+     * already issues a depth-1 populate to render relation tiles, so any
+     * selective override would have to coexist with the picker projection
+     * (additive? overriding? both?) — extra surface area for a case no
+     * current collection needs. Revisit if a real use case emerges
+     * (deeper relation traversal, or a field outside the picker
+     * projection that the URL builder needs).
      */
     preview?: {
-        populate?: PopulateSpec;
         url: (doc: PreviewDocument<T>, ctx: {
             locale?: string;
         }) => string | null;

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

@@ -756,6 +756,37 @@ export type BlockData<B extends Block> = Prettify<{
  * ```
  */
 export type BlocksUnion<Bs extends readonly Block[]> = Bs[number] extends infer B ? B extends Block ? BlockData<B> : never : never;
+/**
+ * Type-safe factory for creating a single `Field`. Returns the definition
+ * as-is, but locks in literal types for `name`, `type`, select option
+ * `value`s, etc. — so `FieldData<typeof MyField>` resolves precisely.
+ *
+ * Useful for fields that are shared across multiple collections (e.g. a
+ * `publishedOnField` factory) or for surfacing definition-site type errors
+ * on hand-authored fields without waiting for them to be placed inside a
+ * `fields: [...]` array. Replaces the `as const satisfies Field` pattern.
+ *
+ * For factories that *generate* a field shape from input (e.g. mapped-type
+ * driven fields like `availableLanguagesField`), a custom return type is
+ * still the right tool — `defineField` is for identity / passthrough cases.
+ *
+ * The companion data-shape extractor `FieldData<F>` lives in
+ * `field-data-types.ts` and is re-exported from the package root.
+ *
+ * @example
+ * ```ts
+ * // A shared "publishedOn" field used across many collections.
+ * export const publishedOnField = defineField({
+ *   name: 'publishedOn',
+ *   label: 'Published On',
+ *   type: 'datetime',
+ *   mode: 'datetime',
+ * })
+ *
+ * // FieldData<typeof publishedOnField> resolves to `Date`.
+ * ```
+ */
+export declare function defineField<const F extends Field>(definition: F & Field): F;
 export type CollectionData<C extends CollectionDefinition> = Prettify<{
     document_id: string;
     document_version_id: string;

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

@@ -169,6 +169,42 @@ export function defineCollection(definition) {
 export function defineBlock(definition) {
     return definition;
 }
+// ---------------------------------------------------------------------------
+// Field helpers — mirror of defineCollection / defineBlock for single fields.
+// ---------------------------------------------------------------------------
+/**
+ * Type-safe factory for creating a single `Field`. Returns the definition
+ * as-is, but locks in literal types for `name`, `type`, select option
+ * `value`s, etc. — so `FieldData<typeof MyField>` resolves precisely.
+ *
+ * Useful for fields that are shared across multiple collections (e.g. a
+ * `publishedOnField` factory) or for surfacing definition-site type errors
+ * on hand-authored fields without waiting for them to be placed inside a
+ * `fields: [...]` array. Replaces the `as const satisfies Field` pattern.
+ *
+ * For factories that *generate* a field shape from input (e.g. mapped-type
+ * driven fields like `availableLanguagesField`), a custom return type is
+ * still the right tool — `defineField` is for identity / passthrough cases.
+ *
+ * The companion data-shape extractor `FieldData<F>` lives in
+ * `field-data-types.ts` and is re-exported from the package root.
+ *
+ * @example
+ * ```ts
+ * // A shared "publishedOn" field used across many collections.
+ * export const publishedOnField = defineField({
+ *   name: 'publishedOn',
+ *   label: 'Published On',
+ *   type: 'datetime',
+ *   mode: 'datetime',
+ * })
+ *
+ * // FieldData<typeof publishedOnField> resolves to `Date`.
+ * ```
+ */
+export function defineField(definition) {
+    return definition;
+}
 /**
  * Strips all function-valued properties from a `CollectionDefinition`,
  * producing a version safe for JSON serialization.

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

@@ -9,9 +9,9 @@
  * Pure type aliases for the populate DSL. The runtime orchestrator
  * (`populateDocuments`) lives in `services/populate.ts` and re-exports
  * these for backward compatibility, but they live here so other type
- * surfaces — notably `CollectionAdminConfig.preview.populate` — can
- * reference them without importing the services layer (which would
- * create a cycle, since `populate.ts` imports from this folder).
+ * surfaces (e.g. `@byline/client`'s `FindOptions.populate`) can reference
+ * them without importing the services layer — which would create a cycle,
+ * since `populate.ts` imports from this folder.
  */
 /**
  * Per-field populate options. `select` names the target's fields to

package/dist/query/parse-where.d.ts

@@ -75,6 +75,13 @@ declare const DOCUMENT_SORT_COLUMNS: Record<string, string>;
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export declare function parseWhere(where: WhereClause | undefined, definition: CollectionDefinition, ctx?: ParseContext): Promise<ParsedWhere>;
 /**

package/dist/query/parse-where.js

@@ -31,6 +31,13 @@ const DOCUMENT_SORT_COLUMNS = {
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export async function parseWhere(where, definition, ctx) {
     return parseWhereInternal(where, definition, ctx, { isNested: false, inCombinator: false });
@@ -57,10 +64,15 @@ export function mergePredicates(hookPredicate, userWhere) {
     return { $and: [hookPredicate, userWhere] };
 }
 /**
- * Recursion entry point. `isNested: true` disables the top-level reserved
- * keys (`status`, `query`, `path`) so that on a nested sub-where, those
- * names resolve as ordinary fields on the target collection (where `path`
- * and `status` are typically real text fields).
+ * Recursion entry point. `isNested: true` rewires the document-level
+ * reserved keys: `status` / `path` downshift to `DocumentColumnFilter`
+ * entries against the target version's columns (the adapter resolves
+ * those via the inner relation scope, e.g. `td${depth}.status`); `query`
+ * is dropped with a debug log because text search has no sensible
+ * composition through a relation hop. Reserved keys still take precedence
+ * over field lookups — a target collection that happens to declare a
+ * `path` or `status` field will not see those clauses resolve as field
+ * filters; rename the offending field if that conflict matters.
  */
 async function parseWhereInternal(where, definition, ctx, { isNested, inCombinator }) {
     const result = { filters: [] };
@@ -134,65 +146,82 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
             continue;
         }
         // --- Document-level reserved keys --------------------------------------
-        // At the top level (not nested in a relation, not inside a combinator)
-        // these keys map to direct adapter scalar parameters
-        // (`ParsedWhere.status` / `query` / `pathFilter`) which compile to the
-        // outermost WHERE clause. Inside a combinator that mapping no longer
-        // composes — the predicate needs to OR with siblings, which the scalar
-        // parameter form cannot express — so `status` / `path` downshift to a
-        // `DocumentColumnFilter` and `query` is dropped (text search has no
-        // sensible OR-composing form here).
-        if (!isNested) {
-            if (key === 'status') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'status',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.status = rawValue;
+        // `status` / `path` / `query` are reserved on every collection — they
+        // never resolve to a field of the same name (no field-shadow exception),
+        // mirroring the consumer-intuitive rule that these names refer to the
+        // document version's metadata columns.
+        //
+        // Where they compile depends on scope:
+        //
+        //   • Top level (not nested in a relation, not inside a combinator):
+        //     map to direct adapter scalar parameters
+        //     (`ParsedWhere.status` / `query` / `pathFilter`) which compile to
+        //     the outermost WHERE clause.
+        //
+        //   • Inside a combinator, OR inside a relation sub-clause: the scalar-
+        //     parameter mapping no longer composes (the predicate needs to OR
+        //     with siblings, or anchor against the *target's* doc version), so
+        //     `status` / `path` downshift to a `DocumentColumnFilter`. The SQL
+        //     compiler reads `outerScope.status` / `outerScope.path`, which the
+        //     adapter rewires per-scope (`d.path` at the top level,
+        //     `td${depth}.path` inside a relation hop).
+        //
+        //   • `query` is dropped with a debug log in both downshift cases —
+        //     text search has no sensible OR-composing form, and a per-target
+        //     EXISTS over `store_text` is intentionally deferred.
+        if (key === 'status') {
+            if (isNested || inCombinator) {
+                const parsed = normaliseToOperator(rawValue);
+                if (parsed) {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'status',
+                        operator: parsed.operator,
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
-            if (key === 'query') {
-                if (inCombinator) {
-                    ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.query = rawValue;
-                }
+            if (typeof rawValue === 'string') {
+                result.status = rawValue;
+            }
+            continue;
+        }
+        if (key === 'query') {
+            if (isNested) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a relation sub-clause — text search does not compose through a relation hop');
                 continue;
             }
-            if (key === 'path') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'path',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
+            if (inCombinator) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
+                continue;
+            }
+            if (typeof rawValue === 'string') {
+                result.query = rawValue;
+            }
+            continue;
+        }
+        if (key === 'path') {
+            if (isNested || inCombinator) {
                 const parsed = normaliseToOperator(rawValue);
                 if (parsed) {
-                    result.pathFilter = {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'path',
                         operator: parsed.operator,
-                        value: String(parsed.value),
-                    };
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
+            const parsed = normaliseToOperator(rawValue);
+            if (parsed) {
+                result.pathFilter = {
+                    operator: parsed.operator,
+                    value: String(parsed.value),
+                };
+            }
+            continue;
         }
         // --- Field-level keys --------------------------------------------------
         const field = definition.fields.find((f) => f.name === key);
@@ -226,11 +255,11 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 isNested: true,
                 inCombinator: false,
             });
-            // Flatten nested: only field-level / relation-level conditions make
-            // sense inside a relation subclause. Document-level keys (status,
-            // path, query) on the target are deliberately out of scope for this
-            // first phase — they can be added later by promoting them into
-            // the nested filter list here.
+            // Splice nested filters straight in. The nested parse runs with
+            // `isNested: true`, which promotes `status` / `path` into
+            // `DocumentColumnFilter` entries the adapter resolves against the
+            // target version's columns (`td${depth}.status` / `td${depth}.path`)
+            // via the inner relation scope. `query` is dropped one level up.
             result.filters.push({
                 kind: 'relation',
                 fieldName: key,

package/dist/query/parse-where.test.node.js

@@ -40,7 +40,11 @@ const categoriesCollection = defineCollection({
     }),
     fields: [
         { name: 'name', type: 'text', label: 'Name', localized: true },
-        { name: 'path', type: 'text', label: 'Path' },
+        // `slug`, not `path` — `path` is a reserved key that resolves to the
+        // target version's `document_versions.path` column inside a nested
+        // sub-clause (same precedence as the top level), so a real `path`
+        // field would be unreachable through the where clause.
+        { name: 'slug', type: 'text', label: 'Slug' },
         {
             name: 'parent',
             type: 'relation',
@@ -220,8 +224,8 @@ describe('parseWhere', () => {
             value: ['cat-a', 'cat-b'],
         });
     });
-    it('should emit a RelationFilter for a nested plain-object sub-where', async () => {
-        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+    it('should emit a RelationFilter for a nested plain-object sub-where (field key)', async () => {
+        const result = await parseWhere({ category: { slug: 'news' } }, testCollection, ctx);
         expect(result.filters).toHaveLength(1);
         expect(result.filters[0]).toEqual({
             kind: 'relation',
@@ -230,7 +234,7 @@ describe('parseWhere', () => {
             nested: [
                 {
                     kind: 'field',
-                    fieldName: 'path',
+                    fieldName: 'slug',
                     storeType: 'text',
                     valueColumn: 'value',
                     operator: '$eq',
@@ -239,6 +243,55 @@ describe('parseWhere', () => {
             ],
         });
     });
+    it('promotes `path` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        // Reserved-key precedence: `path` inside a relation sub-clause maps to
+        // the target version's `document_versions.path` column, never to a
+        // field of the same name. The adapter wires it to `td${depth}.path`
+        // via the inner relation scope.
+        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'path',
+                    operator: '$eq',
+                    value: 'news',
+                },
+            ],
+        });
+    });
+    it('promotes `status` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        const result = await parseWhere({ category: { status: 'draft' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'status',
+                    operator: '$eq',
+                    value: 'draft',
+                },
+            ],
+        });
+    });
+    it('drops `query` inside a nested sub-where (no nested filter emitted)', async () => {
+        // Same rationale as `query` inside a combinator: text search has no
+        // sensible composition through a relation hop.
+        const result = await parseWhere({ category: { query: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        const relation = result.filters[0];
+        expect(relation?.kind).toBe('relation');
+        if (relation?.kind !== 'relation')
+            return;
+        expect(relation.nested).toEqual([]);
+    });
     it('should support operator objects inside a nested sub-where', async () => {
         const result = await parseWhere({ category: { name: { $contains: 'news' } } }, testCollection, ctx);
         const relation = result.filters[0];
@@ -257,7 +310,7 @@ describe('parseWhere', () => {
         ]);
     });
     it('should recurse into multi-hop relation sub-wheres', async () => {
-        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const result = await parseWhere({ category: { parent: { slug: 'news' } } }, testCollection, ctx);
         const top = result.filters[0];
         expect(top?.kind).toBe('relation');
         if (top?.kind !== 'relation')
@@ -274,7 +327,7 @@ describe('parseWhere', () => {
         expect(inner.nested).toEqual([
             {
                 kind: 'field',
-                fieldName: 'path',
+                fieldName: 'slug',
                 storeType: 'text',
                 valueColumn: 'value',
                 operator: '$eq',
@@ -282,6 +335,26 @@ describe('parseWhere', () => {
             },
         ]);
     });
+    it('recurses multi-hop with the doc-column form (target.path at depth 2)', async () => {
+        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const top = result.filters[0];
+        expect(top?.kind).toBe('relation');
+        if (top?.kind !== 'relation')
+            return;
+        expect(top.nested).toHaveLength(1);
+        const inner = top.nested[0];
+        expect(inner?.kind).toBe('relation');
+        if (inner?.kind !== 'relation')
+            return;
+        expect(inner.nested).toEqual([
+            {
+                kind: 'docColumn',
+                column: 'path',
+                operator: '$eq',
+                value: 'news',
+            },
+        ]);
+    });
     it('should skip nested sub-where when ctx is not provided', async () => {
         const result = await parseWhere({ category: { path: 'news' } }, testCollection);
         expect(result.filters).toEqual([]);
@@ -526,6 +599,11 @@ describe('parseWhere — combinators', () => {
         expect(result.filters).toEqual([]);
     });
     it('parses combinators inside a nested relation sub-where', async () => {
+        // Inside the nested sub-where: `name` is a real field on the target
+        // (resolves to a FieldFilter) and `path` is a reserved key that
+        // downshifts to a `DocumentColumnFilter` against the target version's
+        // path column. Inside an `$or` either side composes — the OR is
+        // emitted as a CombinatorFilter wrapping both children.
         const result = await parseWhere({
             category: {
                 $or: [{ name: 'News' }, { path: 'announcements' }],
@@ -541,7 +619,7 @@ describe('parseWhere — combinators', () => {
             kind: 'or',
             children: [
                 { kind: 'field', fieldName: 'name' },
-                { kind: 'field', fieldName: 'path' },
+                { kind: 'docColumn', column: 'path', operator: '$eq', value: 'announcements' },
             ],
         });
     });

package/dist/services/index.d.ts

@@ -7,3 +7,4 @@ export * from './field-upload.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';

package/dist/services/index.js

@@ -8,3 +8,4 @@ export * from './field-upload.js';
 export { createReadContext, populateDocuments, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { collectRichTextLeaves, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { walkFieldTree } from './walk-field-tree.js';

package/dist/services/populate.d.ts

@@ -249,11 +249,14 @@ interface RelationLeafRef {
     sub: PopulateFieldSpec;
 }
 /**
- * Walk `fields` against `fieldDefs` and collect every relation leaf whose
- * name matches `populate`. Recurses through `group` / `array` / `blocks`
- * using the same populate spec (structure field names do not scope the
- * match — if `populate: { author: true }` is given, every `author`
- * relation found in the tree matches).
+ * Collect every relation leaf whose name matches `populate`. Structure
+ * field names do not scope the match — if `populate: { author: true }`
+ * is given, every `author` relation found anywhere in the tree matches.
+ *
+ * Tree traversal is delegated to the shared `walkFieldTree` walker; this
+ * function applies the relation-specific filters: populate-spec match,
+ * envelope shape, and "skip already-populated" (via the `_resolved`
+ * discriminator left behind by a previous populate pass).
  */
 declare function collectRelationLeaves(fields: Record<string, any>, fieldDefs: FieldSet, populate: PopulateSpec, acc: RelationLeafRef[]): void;
 declare function matchesPopulate(fieldName: string, populate: PopulateSpec): PopulateFieldSpec | undefined;

package/dist/services/populate.js

@@ -10,6 +10,7 @@ import { ERR_READ_BUDGET_EXCEEDED } from '../lib/errors.js';
 import { parseWhere } from '../query/parse-where.js';
 import { applyAfterRead } from './document-read.js';
 import { populateRichTextFields } from './richtext-populate.js';
+import { walkFieldTree } from './walk-field-tree.js';
 // ---------------------------------------------------------------------------
 // ReadContext — recursion guard
 // ---------------------------------------------------------------------------
@@ -300,69 +301,36 @@ async function resolveBeforeReadFiltersForTarget(params) {
     return parsed.filters.length > 0 ? parsed.filters : undefined;
 }
 /**
- * Walk `fields` against `fieldDefs` and collect every relation leaf whose
- * name matches `populate`. Recurses through `group` / `array` / `blocks`
- * using the same populate spec (structure field names do not scope the
- * match — if `populate: { author: true }` is given, every `author`
- * relation found in the tree matches).
+ * Collect every relation leaf whose name matches `populate`. Structure
+ * field names do not scope the match — if `populate: { author: true }`
+ * is given, every `author` relation found anywhere in the tree matches.
+ *
+ * Tree traversal is delegated to the shared `walkFieldTree` walker; this
+ * function applies the relation-specific filters: populate-spec match,
+ * envelope shape, and "skip already-populated" (via the `_resolved`
+ * discriminator left behind by a previous populate pass).
  */
 function collectRelationLeaves(fields, fieldDefs, populate, acc) {
-    for (const def of fieldDefs) {
-        const rawValue = fields[def.name];
-        if (rawValue == null)
+    for (const leaf of walkFieldTree(fieldDefs, fields)) {
+        if (leaf.field.type !== 'relation')
             continue;
-        if (def.type === 'relation') {
-            const sub = matchesPopulate(def.name, populate);
-            if (sub === undefined)
-                continue;
-            if (!isRelatedDocumentValue(rawValue))
-                continue;
-            // Skip leaves that have already been replaced (e.g. via shared-ref
-            // duplication at the previous level); only raw RelatedDocumentValues
-            // are candidates for population.
-            if ('_resolved' in rawValue)
-                continue;
-            acc.push({
-                parent: fields,
-                key: def.name,
-                field: def,
-                value: rawValue,
-                sub,
-            });
+        const sub = matchesPopulate(leaf.field.name, populate);
+        if (sub === undefined)
             continue;
-        }
-        if (def.type === 'group') {
-            if (typeof rawValue === 'object' && !Array.isArray(rawValue)) {
-                collectRelationLeaves(rawValue, def.fields, populate, acc);
-            }
+        if (!isRelatedDocumentValue(leaf.value))
             continue;
-        }
-        if (def.type === 'array') {
-            if (Array.isArray(rawValue)) {
-                for (const item of rawValue) {
-                    if (item && typeof item === 'object' && !Array.isArray(item)) {
-                        collectRelationLeaves(item, def.fields, populate, acc);
-                    }
-                }
-            }
+        // Skip leaves that have already been replaced (e.g. via shared-ref
+        // duplication at the previous level); only raw RelatedDocumentValues
+        // are candidates for population.
+        if ('_resolved' in leaf.value)
             continue;
-        }
-        if (def.type === 'blocks') {
-            if (Array.isArray(rawValue)) {
-                for (const item of rawValue) {
-                    if (item && typeof item === 'object' && !Array.isArray(item)) {
-                        // Reconstructed block items carry `_type` set to the variant's `blockType`.
-                        const blockType = item._type;
-                        if (typeof blockType !== 'string')
-                            continue;
-                        const block = def.blocks.find((b) => b.blockType === blockType);
-                        if (!block)
-                            continue;
-                        collectRelationLeaves(item, block.fields, populate, acc);
-                    }
-                }
-            }
-        }
+        acc.push({
+            parent: leaf.parent,
+            key: leaf.key,
+            field: leaf.field,
+            value: leaf.value,
+            sub,
+        });
     }
 }
 function matchesPopulate(fieldName, populate) {

package/dist/services/richtext-populate.d.ts

@@ -40,13 +40,17 @@ export interface RichTextLeaf {
 /**
  * Walk a field set and a matching reconstructed data tree in lockstep,
  * yielding every rich-text leaf the schema declares regardless of nesting
- * depth. Recurses through `group` (nested object), `array` (array of
- * sub-objects), and `blocks` (array of `_type`-discriminated sub-objects).
+ * depth.
+ *
+ * Tree traversal is delegated to the shared `walkFieldTree` walker; this
+ * function is the rich-text-specific filter — it surfaces only leaves
+ * whose declared `type === 'richText'` and re-shapes the leaf as a
+ * `RichTextLeaf` for downstream callers.
  *
  * Tolerates missing data — a `group` whose data is absent simply yields
- * nothing under that subtree, rather than throwing. The schema is the
- * source of truth for *where* a richText might be; the data is the source
- * of truth for *whether one is currently set*.
+ * nothing under that subtree. The schema is the source of truth for
+ * *where* a richText might be; the data is the source of truth for
+ * *whether one is currently set*.
  */
 export declare function collectRichTextLeaves(fields: FieldSet, data: Record<string, any> | null | undefined, pathPrefix?: string): Generator<RichTextLeaf, void, void>;
 export interface PopulateRichTextFieldsOptions {

package/dist/services/richtext-populate.js

@@ -24,67 +24,28 @@
  * adapters can implement per-leaf caching if needed.
  */
 import { isArrayField, isBlocksField, isGroupField, } from '../@types/field-types.js';
+import { walkFieldTree } from './walk-field-tree.js';
 /**
  * Walk a field set and a matching reconstructed data tree in lockstep,
  * yielding every rich-text leaf the schema declares regardless of nesting
- * depth. Recurses through `group` (nested object), `array` (array of
- * sub-objects), and `blocks` (array of `_type`-discriminated sub-objects).
+ * depth.
+ *
+ * Tree traversal is delegated to the shared `walkFieldTree` walker; this
+ * function is the rich-text-specific filter — it surfaces only leaves
+ * whose declared `type === 'richText'` and re-shapes the leaf as a
+ * `RichTextLeaf` for downstream callers.
  *
  * Tolerates missing data — a `group` whose data is absent simply yields
- * nothing under that subtree, rather than throwing. The schema is the
- * source of truth for *where* a richText might be; the data is the source
- * of truth for *whether one is currently set*.
+ * nothing under that subtree. The schema is the source of truth for
+ * *where* a richText might be; the data is the source of truth for
+ * *whether one is currently set*.
  */
 export function* collectRichTextLeaves(fields, data, pathPrefix = '') {
-    if (data == null)
-        return;
-    for (const field of fields) {
-        const here = pathPrefix === '' ? field.name : `${pathPrefix}.${field.name}`;
-        yield* walkField(field, data[field.name], here);
-    }
-}
-function* walkField(field, value, fieldPath) {
-    if (field.type === 'richText') {
-        if (value === undefined || value === null)
-            return;
-        yield { field, value, fieldPath };
-        return;
-    }
-    if (isGroupField(field)) {
-        if (value == null || typeof value !== 'object')
-            return;
-        yield* collectRichTextLeaves(field.fields, value, fieldPath);
-        return;
-    }
-    if (isArrayField(field)) {
-        if (!Array.isArray(value))
-            return;
-        for (let i = 0; i < value.length; i++) {
-            const item = value[i];
-            if (item == null || typeof item !== 'object')
-                continue;
-            yield* collectRichTextLeaves(field.fields, item, `${fieldPath}.${i}`);
-        }
-        return;
-    }
-    if (isBlocksField(field)) {
-        if (!Array.isArray(value))
-            return;
-        for (let i = 0; i < value.length; i++) {
-            const item = value[i];
-            if (item == null || typeof item !== 'object')
-                continue;
-            const blockType = item._type;
-            if (!blockType)
-                continue;
-            const block = field.blocks.find((b) => b.blockType === blockType);
-            if (!block)
-                continue;
-            yield* collectRichTextLeaves(block.fields, item, `${fieldPath}.${i}`);
-        }
-        return;
+    for (const leaf of walkFieldTree(fields, data, pathPrefix)) {
+        if (leaf.field.type !== 'richText')
+            continue;
+        yield { field: leaf.field, value: leaf.value, fieldPath: leaf.fieldPath };
     }
-    // Any other field type — value-only leaves with no nested richText.
 }
 /**
  * Resolve the effective `populateRelationsOnRead` for a richText field.

package/dist/services/walk-field-tree.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+/**
+ * Shared field-tree walker.
+ *
+ * `walkFieldTree(fields, data)` traverses a `(FieldSet, data)` pair in
+ * lockstep, descending through `group` / `array` / `blocks` structure
+ * fields and yielding every value-leaf it finds. Consumers filter by
+ * `field.type` and apply their own domain checks (e.g. relation envelope
+ * shape, populate-spec match, `_resolved` skip, richText null handling).
+ *
+ * Both `collectRelationLeaves` (populate.ts) and `collectRichTextLeaves`
+ * (richtext-populate.ts) are now thin filters over this primitive — see
+ * docs/TODO.md "walkFieldTree" entry for the rationale.
+ */
+import { type Field, type FieldSet } from '../@types/field-types.js';
+/**
+ * One value-leaf yielded by `walkFieldTree`. The walker hands back a
+ * reference to the *parent container* (`parent[key]`) so consumers can
+ * mutate or replace the value in place — `parent[key] === value` always
+ * holds at yield time.
+ *
+ * `fieldPath` is the dotted path from the root of the walk, with array
+ * indices spelled inline (`faq.0.answer`, `content.1.richText`). Suitable
+ * for error messages and debug logging.
+ */
+export interface FieldLeaf {
+    field: Field;
+    value: unknown;
+    parent: Record<string, any>;
+    key: string;
+    fieldPath: string;
+}
+/**
+ * Walk a field set and a matching reconstructed data tree in lockstep,
+ * yielding every value-leaf the schema declares regardless of nesting
+ * depth.
+ *
+ * **What counts as a leaf:** every non-structure field whose value is
+ * non-null. Structure fields (`group` / `array` / `blocks`) are descended
+ * into, never yielded themselves. Null / undefined values are skipped
+ * silently — the schema is the source of truth for *where* a leaf might
+ * be; the data is the source of truth for *whether one is currently set*.
+ *
+ * Tolerates malformed data gracefully:
+ *   - a `group` whose data is missing or non-object yields nothing
+ *   - an `array` whose data isn't an array yields nothing
+ *   - a `blocks` item with a missing or unknown `_type` is skipped
+ *
+ * The walker is synchronous and lazy (a generator). Async work — DB
+ * fetches, hook fan-out — happens in the consumer after the walk yields.
+ */
+export declare function walkFieldTree(fields: FieldSet, data: Record<string, any> | null | undefined, pathPrefix?: string): Generator<FieldLeaf, void, void>;

package/dist/services/walk-field-tree.js

@@ -0,0 +1,88 @@
+/**
+ * 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
+ */
+/**
+ * Shared field-tree walker.
+ *
+ * `walkFieldTree(fields, data)` traverses a `(FieldSet, data)` pair in
+ * lockstep, descending through `group` / `array` / `blocks` structure
+ * fields and yielding every value-leaf it finds. Consumers filter by
+ * `field.type` and apply their own domain checks (e.g. relation envelope
+ * shape, populate-spec match, `_resolved` skip, richText null handling).
+ *
+ * Both `collectRelationLeaves` (populate.ts) and `collectRichTextLeaves`
+ * (richtext-populate.ts) are now thin filters over this primitive — see
+ * docs/TODO.md "walkFieldTree" entry for the rationale.
+ */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/field-types.js';
+/**
+ * Walk a field set and a matching reconstructed data tree in lockstep,
+ * yielding every value-leaf the schema declares regardless of nesting
+ * depth.
+ *
+ * **What counts as a leaf:** every non-structure field whose value is
+ * non-null. Structure fields (`group` / `array` / `blocks`) are descended
+ * into, never yielded themselves. Null / undefined values are skipped
+ * silently — the schema is the source of truth for *where* a leaf might
+ * be; the data is the source of truth for *whether one is currently set*.
+ *
+ * Tolerates malformed data gracefully:
+ *   - a `group` whose data is missing or non-object yields nothing
+ *   - an `array` whose data isn't an array yields nothing
+ *   - a `blocks` item with a missing or unknown `_type` is skipped
+ *
+ * The walker is synchronous and lazy (a generator). Async work — DB
+ * fetches, hook fan-out — happens in the consumer after the walk yields.
+ */
+export function* walkFieldTree(fields, data, pathPrefix = '') {
+    if (data == null || typeof data !== 'object' || Array.isArray(data))
+        return;
+    for (const field of fields) {
+        const fieldPath = pathPrefix === '' ? field.name : `${pathPrefix}.${field.name}`;
+        yield* walkField(field, data, field.name, fieldPath);
+    }
+}
+function* walkField(field, parent, key, fieldPath) {
+    const value = parent[key];
+    if (value == null)
+        return;
+    if (isGroupField(field)) {
+        if (typeof value !== 'object' || Array.isArray(value))
+            return;
+        yield* walkFieldTree(field.fields, value, fieldPath);
+        return;
+    }
+    if (isArrayField(field)) {
+        if (!Array.isArray(value))
+            return;
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            if (item == null || typeof item !== 'object' || Array.isArray(item))
+                continue;
+            yield* walkFieldTree(field.fields, item, `${fieldPath}.${i}`);
+        }
+        return;
+    }
+    if (isBlocksField(field)) {
+        if (!Array.isArray(value))
+            return;
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            if (item == null || typeof item !== 'object' || Array.isArray(item))
+                continue;
+            const blockType = item._type;
+            if (typeof blockType !== 'string')
+                continue;
+            const block = field.blocks.find((b) => b.blockType === blockType);
+            if (!block)
+                continue;
+            yield* walkFieldTree(block.fields, item, `${fieldPath}.${i}`);
+        }
+        return;
+    }
+    yield { field, value, parent, key, fieldPath };
+}

package/dist/services/walk-field-tree.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/services/walk-field-tree.test.node.js

@@ -0,0 +1,193 @@
+/**
+ * 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 { walkFieldTree } from './walk-field-tree.js';
+// ---------------------------------------------------------------------------
+// Fixture — every nesting shape the walker has to handle, plus a few
+// near-misses (unknown block type, missing _type, non-array `array` data,
+// non-object `group` data) to exercise the tolerance paths.
+// ---------------------------------------------------------------------------
+const fields = [
+    { name: 'title', type: 'text', label: 'Title' },
+    { name: 'body', type: 'richText', label: 'Body' },
+    {
+        name: 'meta',
+        type: 'group',
+        label: 'Meta',
+        fields: [
+            { name: 'summary', type: 'text', label: 'Summary' },
+            {
+                name: 'inner',
+                type: 'group',
+                label: 'Inner',
+                fields: [{ name: 'note', type: 'text', label: 'Note' }],
+            },
+        ],
+    },
+    {
+        name: 'faq',
+        type: 'array',
+        label: 'FAQ',
+        fields: [{ name: 'answer', type: 'richText', label: 'Answer' }],
+    },
+    {
+        name: 'content',
+        type: 'blocks',
+        label: 'Content',
+        blocks: [
+            {
+                blockType: 'photoBlock',
+                fields: [
+                    { name: 'caption', type: 'richText', label: 'Caption' },
+                    { name: 'alt', type: 'text', label: 'Alt' },
+                ],
+            },
+            {
+                blockType: 'richTextBlock',
+                fields: [
+                    // Same field name as `photoBlock.alt` but a different shape — guards
+                    // against any cross-variant leakage in the dispatch.
+                    { name: 'alt', type: 'richText', label: 'Alt-rich' },
+                ],
+            },
+        ],
+    },
+];
+// ---------------------------------------------------------------------------
+// Path coverage — every nesting shape yields the expected dotted paths.
+// ---------------------------------------------------------------------------
+describe('walkFieldTree — paths', () => {
+    it('yields top-level value-leaves with field name as path', () => {
+        const data = { title: 'hello', body: { kind: 'rt' } };
+        const out = Array.from(walkFieldTree(fields, data));
+        const paths = out.map((l) => l.fieldPath).sort();
+        expect(paths).toEqual(['body', 'title']);
+    });
+    it('descends into nested group fields', () => {
+        const data = { meta: { summary: 's', inner: { note: 'n' } } };
+        const out = Array.from(walkFieldTree(fields, data));
+        const paths = out.map((l) => l.fieldPath).sort();
+        expect(paths).toEqual(['meta.inner.note', 'meta.summary']);
+    });
+    it('inlines numeric indices into array paths', () => {
+        const data = {
+            faq: [{ answer: { kind: 'a0' } }, { answer: { kind: 'a1' } }],
+        };
+        const out = Array.from(walkFieldTree(fields, data));
+        const paths = out.map((l) => l.fieldPath).sort();
+        expect(paths).toEqual(['faq.0.answer', 'faq.1.answer']);
+    });
+    it('dispatches blocks on _type and recurses into the matching variant', () => {
+        const data = {
+            content: [
+                { _id: 'a', _type: 'photoBlock', caption: { kind: 'c' }, alt: 'plain' },
+                { _id: 'b', _type: 'richTextBlock', alt: { kind: 'rt' } },
+            ],
+        };
+        const out = Array.from(walkFieldTree(fields, data));
+        const paths = out.map((l) => l.fieldPath).sort();
+        expect(paths).toEqual(['content.0.alt', 'content.0.caption', 'content.1.alt']);
+    });
+    it('honours pathPrefix at the top of the walk', () => {
+        const data = { title: 't' };
+        const out = Array.from(walkFieldTree(fields, data, 'root'));
+        expect(out.map((l) => l.fieldPath)).toEqual(['root.title']);
+    });
+});
+// ---------------------------------------------------------------------------
+// parent[key] === value invariant — consumers rely on this to mutate /
+// replace the leaf in place (e.g. populate writing the resolved doc back).
+// ---------------------------------------------------------------------------
+describe('walkFieldTree — parent / key invariant', () => {
+    it('parent[key] resolves to value at every yield', () => {
+        const data = {
+            title: 'hi',
+            meta: { summary: 's' },
+            faq: [{ answer: { kind: 'rt' } }],
+            content: [{ _id: 'a', _type: 'photoBlock', alt: 'plain' }],
+        };
+        const out = Array.from(walkFieldTree(fields, data));
+        expect(out.length).toBeGreaterThan(0);
+        for (const leaf of out) {
+            expect(leaf.parent[leaf.key]).toBe(leaf.value);
+        }
+    });
+    it('mutation through parent[key] is visible to the caller', () => {
+        const data = { title: 'before' };
+        const out = Array.from(walkFieldTree(fields, data));
+        const leaf = out.find((l) => l.fieldPath === 'title');
+        leaf.parent[leaf.key] = 'after';
+        expect(data.title).toBe('after');
+    });
+});
+// ---------------------------------------------------------------------------
+// Tolerance paths — malformed / missing data is skipped, never thrown.
+// ---------------------------------------------------------------------------
+describe('walkFieldTree — tolerance', () => {
+    it('returns an empty iterator for null / undefined data', () => {
+        expect(Array.from(walkFieldTree(fields, null))).toEqual([]);
+        expect(Array.from(walkFieldTree(fields, undefined))).toEqual([]);
+    });
+    it('returns an empty iterator for non-object top-level data', () => {
+        expect(Array.from(walkFieldTree(fields, []))).toEqual([]);
+    });
+    it('skips leaves whose value is null / undefined', () => {
+        const data = { title: null, body: undefined };
+        expect(Array.from(walkFieldTree(fields, data))).toEqual([]);
+    });
+    it('skips a group whose value is non-object', () => {
+        const data = { meta: 'not-an-object' };
+        expect(Array.from(walkFieldTree(fields, data))).toEqual([]);
+    });
+    it('skips an array field whose value is not actually an array', () => {
+        const data = { faq: { answer: { kind: 'rt' } } };
+        expect(Array.from(walkFieldTree(fields, data))).toEqual([]);
+    });
+    it('skips block items missing _type', () => {
+        const data = {
+            content: [{ _id: 'a', caption: { kind: 'rt' } }],
+        };
+        expect(Array.from(walkFieldTree(fields, data))).toEqual([]);
+    });
+    it('skips block items with an unknown _type', () => {
+        const data = {
+            content: [
+                { _id: 'a', _type: 'unknownBlock', caption: { kind: 'rt' } },
+                { _id: 'b', _type: 'richTextBlock', alt: { kind: 'rt' } },
+            ],
+        };
+        const out = Array.from(walkFieldTree(fields, data));
+        expect(out.map((l) => l.fieldPath)).toEqual(['content.1.alt']);
+    });
+    it('skips a non-object array item silently', () => {
+        const data = { faq: [null, 'string', { answer: { kind: 'rt' } }] };
+        const out = Array.from(walkFieldTree(fields, data));
+        expect(out.map((l) => l.fieldPath)).toEqual(['faq.2.answer']);
+    });
+});
+// ---------------------------------------------------------------------------
+// Field identity — the FieldLeaf carries the actual schema field def, so
+// consumers can branch on `field.type` and read field-specific options.
+// ---------------------------------------------------------------------------
+describe('walkFieldTree — field identity', () => {
+    it('yields the same Field reference declared in the schema', () => {
+        const data = { title: 'hi' };
+        const out = Array.from(walkFieldTree(fields, data));
+        const titleLeaf = out.find((l) => l.fieldPath === 'title');
+        expect(titleLeaf?.field).toBe(fields[0]);
+    });
+    it('yields the block-variant field reference for blocks descents', () => {
+        const data = {
+            content: [{ _id: 'a', _type: 'photoBlock', alt: 'plain' }],
+        };
+        const out = Array.from(walkFieldTree(fields, data));
+        const altLeaf = out.find((l) => l.fieldPath === 'content.0.alt');
+        expect(altLeaf?.field.type).toBe('text'); // photoBlock.alt is a text field
+        expect(altLeaf?.field.name).toBe('alt');
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.3.0"
+    "@byline/auth": "1.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",