@byline/core 1.8.0 → 1.8.2

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

@@ -516,9 +516,7 @@ export interface UploadHooks {
  * by populate. A hook that performs its own reads should thread this
  * context back in via `client.collection(...).findById(id, { _readContext:
  * readContext })` so the visited set and read budget are preserved —
- * essential to foreclose the A→B→A loop (see
- * `docs/analysis/RELATIONSHIPS-ANALYSIS.md` § "Special consideration:
- * recursive-read safety").
+ * essential to foreclose the A→B→A loop (see `docs/RELATIONSHIPS.md`).
  */
 export interface AfterReadContext {
     /** The raw reconstructed document. Mutate in place — changes persist. */
@@ -551,9 +549,8 @@ export interface AfterReadContext {
  *   - `collectionPath` — the collection being queried (useful when the
  *     same hook function is reused across collections).
  *
- * See `docs/analysis/AUTHN-AUTHZ-ANALYSIS.md` (Phase 7) for the strategic
- * rationale and `docs/analysis/ACCESS-CONTROL-RECIPES.md` for worked
- * examples.
+ * See `docs/AUTHN-AUTHZ.md` for the strategic rationale and
+ * `docs/ACCESS-CONTROL-RECIPES.md` for worked examples.
  */
 export interface BeforeReadContext {
     collectionPath: string;
@@ -630,7 +627,7 @@ export interface CollectionHooks {
      * read-side row scoping (multi-tenant, owner-only-drafts, soft-delete
      * hide, etc). Returning `void` applies no scoping. Multiple functions
      * combine with implicit AND. See
-     * `docs/analysis/ACCESS-CONTROL-RECIPES.md`.
+     * `docs/ACCESS-CONTROL-RECIPES.md`.
      */
     beforeRead?: BeforeReadHookSlot;
     /**
@@ -675,11 +672,12 @@ export interface CollectionDefinition {
      */
     useAsTitle?: string;
     /**
-     * Names the field whose value initialises this collection's
-     * `documentVersions.path` column. The value is slugified (in the
-     * default content locale) using the installation slugifier and stored
-     * as system metadata — `path` itself is a reserved name and cannot be
-     * declared as a field.
+     * Names the field whose value initialises a document's `path` row in
+     * `byline_document_paths` (the dedicated per-(document, locale) URL slug
+     * table, separate from `documentVersions`). The value is slugified (in
+     * the default content locale) using the installation slugifier and
+     * stored as system metadata — `path` itself is a reserved name and
+     * cannot be declared as a field.
      *
      * `path` is sticky after creation: subsequent updates do not
      * re-derive. Users edit it via the system path widget; collections

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

@@ -285,10 +285,9 @@ export interface IDocumentQueries {
          */
         filters?: DocumentFilter[];
         /**
-         * Request-scoped auth context. Plumbing only in Phase 0 — adapters
-         * currently ignore it. Phase 4 uses it for `collections.<path>.read`
-         * ability assertion and for `beforeRead`-hook query scoping.
-         * See docs/analysis/AUTHN-AUTHZ-ANALYSIS.md.
+         * Request-scoped auth context. Adapters thread it through to
+         * `assertActorCanPerform` for ability assertion and to `beforeRead`
+         * hooks for query scoping. See docs/AUTHN-AUTHZ.md.
          */
         requestContext?: RequestContext;
         /**
@@ -306,9 +305,12 @@ export interface IDocumentQueries {
      * Fetch only the current version's metadata row (no field reconstruction).
      *
      * Use this when the caller only needs `{document_version_id, status,
-     * path, ...}` — for example, workflow transitions that read the current
-     * status and version ID before mutating. Skipping reconstruction avoids
-     * the full 7-way UNION ALL and the meta-row fetch.
+     * created_at, updated_at}` — for example, workflow transitions that read
+     * the current status and version ID before mutating. Skipping
+     * reconstruction avoids the full 7-way UNION ALL and the meta-row fetch.
+     *
+     * `path` is intentionally not returned: callers that need it should
+     * use `getDocumentById` (which projects the locale-resolved path).
      *
      * Returns `null` when the document does not exist (or has been soft-deleted).
      */
@@ -319,7 +321,6 @@ export interface IDocumentQueries {
         document_version_id: string;
         document_id: string;
         collection_id: string;
-        path: string;
         status: string;
         created_at: Date;
         updated_at: Date;
@@ -462,7 +463,7 @@ export interface IDocumentQueries {
         /** Text search across the collection's configured search fields. */
         query?: string;
         sort?: FieldSort;
-        /** Document-level sort column (created_at, updated_at, path). Used when sort is not a field-level sort. */
+        /** Document-level sort column (`created_at`, `updated_at`). Used when `sort` is not a field-level sort. */
         orderBy?: string;
         orderDirection?: 'asc' | 'desc';
         locale?: string;

package/dist/@types/site-config.d.ts

@@ -123,8 +123,9 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      */
     storage?: IStorageProvider;
     /**
-     * Installation-wide slugifier used to derive `documentVersions.path`
-     * from the field named by `CollectionDefinition.useAsPath`.
+     * Installation-wide slugifier used to derive a document's `path` (stored
+     * in `byline_document_paths`) from the field named by
+     * `CollectionDefinition.useAsPath`.
      *
      * Falls back to the default `slugify` from `@byline/core` when not set.
      * Must be pure and synchronous — it runs server-side at write time and

package/dist/auth/assert-actor-can-perform.d.ts

@@ -33,6 +33,6 @@ import { type CollectionAbilityVerb } from './register-collection-abilities.js';
  * bypass this helper — the same escape hatch that skips collection
  * hooks. Seeds, migrations, and internal tooling live there.
  *
- * See docs/analysis/AUTHN-AUTHZ-ANALYSIS.md §8.
+ * See docs/AUTHN-AUTHZ.md.
  */
 export declare function assertActorCanPerform(context: RequestContext | undefined, collectionPath: string, verb: CollectionAbilityVerb): void;

package/dist/auth/assert-actor-can-perform.js

@@ -33,7 +33,7 @@ import { collectionAbilityKey, } from './register-collection-abilities.js';
  * bypass this helper — the same escape hatch that skips collection
  * hooks. Seeds, migrations, and internal tooling live there.
  *
- * See docs/analysis/AUTHN-AUTHZ-ANALYSIS.md §8.
+ * See docs/AUTHN-AUTHZ.md.
  */
 export function assertActorCanPerform(context, collectionPath, verb) {
     if (!context) {

package/dist/auth/register-collection-abilities.d.ts

@@ -29,7 +29,7 @@ import type { CollectionDefinition } from '../@types/index.js';
  * avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/analysis/AUTHN-AUTHZ-ANALYSIS.md §3 and Phase 1.
+ * docs/AUTHN-AUTHZ.md.
  */
 export declare function registerCollectionAbilities(registry: AbilityRegistry, definition: CollectionDefinition): void;
 /** The ability suffixes that every collection contributes. Exposed for contract tests. */

package/dist/auth/register-collection-abilities.js

@@ -27,7 +27,7 @@
  * avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/analysis/AUTHN-AUTHZ-ANALYSIS.md §3 and Phase 1.
+ * docs/AUTHN-AUTHZ.md.
  */
 export function registerCollectionAbilities(registry, definition) {
     const path = definition.path;

package/dist/core.d.ts

@@ -37,9 +37,8 @@ export interface BylineCore<TAdminStore = unknown> {
      * `registerAbility()` — or directly against `core.abilities` — typically
      * during server bootstrap and before any admin UI renders.
      *
-     * Consumed at runtime by `AdminAuth.assertAbility()` (Phase 4) and at
-     * design time by the admin role-editor UI (Phase 6). See
-     * docs/analysis/AUTHN-AUTHZ-ANALYSIS.md §3.
+     * Consumed at runtime by `AdminAuth.assertAbility()` and at design
+     * time by the admin role-editor UI. See docs/AUTHN-AUTHZ.md.
      */
     abilities: AbilityRegistry;
     /** Convenience wrapper around `abilities.register()`. */

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

@@ -43,7 +43,10 @@ export interface ParsedWhere {
     status?: string;
     /** Text search query (for collection-configured search fields). */
     query?: string;
-    /** Filter on document_versions.path with an operator. */
+    /**
+     * Filter on a document's `path` (resolved against `byline_document_paths`
+     * via the locale priority chain) with an operator.
+     */
     pathFilter?: {
         operator: FieldFilterOperator;
         value: string;

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

@@ -41,7 +41,7 @@ const categoriesCollection = defineCollection({
     fields: [
         { name: 'name', type: 'text', label: 'Name', localized: true },
         // `slug`, not `path` — `path` is a reserved key that resolves to the
-        // target version's `document_versions.path` column inside a nested
+        // target document's `byline_document_paths` row 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' },
@@ -245,9 +245,9 @@ 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.
+        // the target document's `byline_document_paths` row, never to a field
+        // of the same name. The adapter resolves it via a `pathProjection`
+        // subquery scoped to the inner relation hop's `td${depth}.document_id`.
         const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
         expect(result.filters).toHaveLength(1);
         expect(result.filters[0]).toEqual({

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

@@ -83,10 +83,12 @@ export interface DocumentLifecycleContext {
      * entry points will call `context.requestContext?.actor?.assertAbility(...)`
      * before any storage mutation.
      *
-     * Optional in Phase 0 so that existing callers (admin server fns, seed
-     * scripts, tests) continue to compile. Phase 4 tightens the type.
+     * Optional so that internal-tooling callers (seed scripts, migration
+     * tools) continue to compile. Production write paths always supply it
+     * — `assertActorCanPerform` runs at every lifecycle entry and rejects
+     * a missing context.
      *
-     * See docs/analysis/AUTHN-AUTHZ-ANALYSIS.md.
+     * See docs/AUTHN-AUTHZ.md.
      */
     requestContext?: RequestContext;
 }

package/dist/services/document-lifecycle.js

@@ -96,7 +96,8 @@ function extractDocumentId(document) {
     return document?.document_id ?? '';
 }
 /**
- * Derive a `documentVersions.path` value at create time.
+ * Derive the `path` value written into `byline_document_paths` at
+ * create time.
  *
  *   1. `definition.useAsPath` set → slugify the named source field's value
  *      in the default content locale.

package/dist/services/populate.d.ts

@@ -25,7 +25,7 @@
  * documents. The guard is in place from day one so that the hook work
  * in Phase 4+ cannot reintroduce the problem.
  *
- * See docs/analysis/RELATIONSHIPS-ANALYSIS.md for the full design rationale.
+ * See docs/RELATIONSHIPS.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

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

@@ -15,8 +15,7 @@
  * 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.
+ * (richtext-populate.ts) are thin filters over this primitive.
  */
 import { type Field, type FieldSet } from '../@types/field-types.js';
 /**

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

@@ -15,8 +15,7 @@
  * 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.
+ * (richtext-populate.ts) are thin filters over this primitive.
  */
 import { isArrayField, isBlocksField, isGroupField, } from '../@types/field-types.js';
 /**

package/dist/utils/slugify.d.ts

@@ -9,7 +9,8 @@
  * Context passed to a `SlugifierFn`.
  *
  * `locale`         - The content locale being slugified (e.g. the default
- *                    content locale when deriving `documentVersions.path`).
+ *                    content locale when deriving a document's `path`
+ *                    row in `byline_document_paths`).
  * `collectionPath` - The collection that owns the value being slugified.
  *                    Lets installation-supplied slugifiers branch by
  *                    collection if URL policies differ.

package/package.json

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