@byline/core 3.15.1 → 3.16.0

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

@@ -29,6 +29,14 @@ const testCollection = defineCollection({
             targetCollection: 'test-categories',
             optional: true,
         },
+        {
+            name: 'tags',
+            type: 'relation',
+            label: 'Tags',
+            targetCollection: 'test-categories',
+            hasMany: true,
+            optional: true,
+        },
     ],
 });
 const categoriesCollection = defineCollection({
@@ -715,3 +723,88 @@ describe('mergePredicates', () => {
         expect(parsed.filters[1]).toMatchObject({ kind: 'field', fieldName: 'title' });
     });
 });
+// ---------------------------------------------------------------------------
+// parseWhere — relation quantifiers ($some / $every / $none)
+// ---------------------------------------------------------------------------
+describe('parseWhere — relation quantifiers', () => {
+    it('emits a $some RelationFilter with hasMany flag for a hasMany field', async () => {
+        const result = await parseWhere({ tags: { $some: { slug: 'news' } } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'tags',
+            targetCollectionId: 'id-test-categories',
+            hasMany: true,
+            nested: [
+                {
+                    kind: 'field',
+                    fieldName: 'slug',
+                    storeType: 'text',
+                    valueColumn: 'value',
+                    operator: '$eq',
+                    value: 'news',
+                },
+            ],
+        });
+    });
+    it('treats a plain sub-where on a hasMany field as implicit $some', async () => {
+        const result = await parseWhere({ tags: { slug: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toMatchObject({
+            kind: 'relation',
+            fieldName: 'tags',
+            hasMany: true,
+        });
+        // Default quantifier is omitted from the wire shape.
+        expect(result.filters[0]).not.toHaveProperty('quantifier');
+    });
+    it('emits an $every RelationFilter', async () => {
+        const result = await parseWhere({ tags: { $every: { status: 'published' } } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'tags',
+            targetCollectionId: 'id-test-categories',
+            hasMany: true,
+            quantifier: 'every',
+            nested: [{ kind: 'docColumn', column: 'status', operator: '$eq', value: 'published' }],
+        });
+    });
+    it('emits a $none RelationFilter with empty nested for `$none: {}`', async () => {
+        const result = await parseWhere({ tags: { $none: {} } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'tags',
+            targetCollectionId: 'id-test-categories',
+            hasMany: true,
+            quantifier: 'none',
+            nested: [],
+        });
+    });
+    it('ANDs multiple quantifier keys on one field into separate filters', async () => {
+        const result = await parseWhere({ tags: { $some: { slug: 'a' }, $none: { slug: 'b' } } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(2);
+        expect(result.filters[0]).toMatchObject({ kind: 'relation', fieldName: 'tags', hasMany: true });
+        expect(result.filters[0]).not.toHaveProperty('quantifier');
+        expect(result.filters[1]).toMatchObject({
+            kind: 'relation',
+            fieldName: 'tags',
+            quantifier: 'none',
+        });
+    });
+    it('supports quantifiers on single (non-hasMany) relation fields without the hasMany flag', async () => {
+        const result = await parseWhere({ category: { $none: { slug: 'hidden' } } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toMatchObject({
+            kind: 'relation',
+            fieldName: 'category',
+            quantifier: 'none',
+        });
+        expect(result.filters[0]).not.toHaveProperty('hasMany');
+    });
+    it('skips quantifier objects when ctx is not provided', async () => {
+        const result = await parseWhere({ tags: { $some: { slug: 'news' } } }, testCollection);
+        expect(result.filters).toHaveLength(0);
+    });
+});

package/dist/schemas/zod/builder.js

@@ -208,7 +208,7 @@ export const createBaseSchema = (collection) => {
         id: z.uuid(),
         versionId: z.uuid().optional(),
         path: z.string().optional(),
-        // The document's content source-locale anchor (see docs/I18N.md).
+        // The document's content source-locale anchor (see docs/07-internationalization/index.md).
         // Carried through list/get responses so the admin can badge it; Zod would
         // otherwise strip it as an undeclared key.
         sourceLocale: z.string().optional(),
@@ -216,7 +216,7 @@ export const createBaseSchema = (collection) => {
         hasPublishedVersion: z.boolean().optional(),
         createdAt: z.iso.datetime(),
         updatedAt: z.iso.datetime(),
-        // Version audit metadata — acting user + action (see docs/AUDIT.md — Workstream 1).
+        // Version audit metadata — acting user + action (see docs/06-auth-and-security/02-auditability.md — Workstream 1).
         // Declared so list/get/history responses carry them through the
         // server-fn parse; Zod would otherwise strip them as undeclared keys.
         createdBy: z.uuid().optional(),

package/dist/services/build-search-document.d.ts

@@ -5,7 +5,36 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition, RichTextToTextFn, SearchDocument } from '../@types/index.js';
+/**
+ * `buildSearchDocument` — the document-grain assembler for the
+ * `SearchProvider` seam. Walks a collection's role-based `search` config
+ * against one locale-resolved document and emits a single, type-enriched
+ * `SearchDocument` for a driver to index. See
+ * `docs/05-reading-and-delivery/07-search.md`.
+ *
+ * Role-based and explicit: only the fields named in `search.{body,facets,
+ * filters}` are projected — nothing is auto-pulled, so unindexed content
+ * never leaks into the index. Core derives each field's `SearchFieldType`
+ * from the schema (the "type enrichment") so a driver can map it onto its
+ * own index without re-inspecting the collection definition.
+ *
+ * Pure and synchronous, like `documentToMarkdown`: the rich-text plain-text
+ * extractor is the editor-agnostic `toText` seam passed via options, and
+ * relation targets are resolved through a caller-supplied definition
+ * resolver — no globals, no DB reads. The caller is responsible for handing
+ * in a document whose `facets` relation fields are already populated (depth
+ * 1) with the target's identity + counter fields.
+ *
+ * `search.{facets,filters}` name **top-level** fields. `search.body` may name
+ * a top-level field of any kind: scalar / `richText` leaves index directly,
+ * and container fields (`blocks` / `array` / `group`) are walked recursively —
+ * every nested `richText` and text (`text` / `textArea`) leaf is flattened and
+ * concatenated into one searchable body string. Nested non-text leaves
+ * (`select`, `relation`, numbers, booleans, dates, files) are skipped so block
+ * configuration never pollutes the index — the same "content, not
+ * configuration" rule the markdown assembler follows.
+ */
+import { type CollectionDefinition, type RichTextToTextFn, type SearchDocument } from '../@types/index.js';
 /** A locale-resolved document fed to the assembler — one locale's view. */
 export interface SearchSourceDocument {
     /** Stable document id (shared across versions and locales). */
@@ -43,4 +72,13 @@ export interface BuildSearchDocumentOptions {
  * Assemble one type-enriched `SearchDocument` from a locale-resolved
  * document and its collection's role-based `search` config.
  */
+/**
+ * Resolve the zone set a collection indexes into, or `null` when the
+ * collection doesn't opt into search at all. A collection with a `search`
+ * config but no explicit `zones` belongs to a single implicit zone equal to
+ * its own path. Shared by the assembler (below) and the client's
+ * cross-collection `search({ zone })` membership check so the two can't
+ * drift.
+ */
+export declare function resolveSearchZones(definition: CollectionDefinition): string[] | null;
 export declare function buildSearchDocument(doc: SearchSourceDocument, definition: CollectionDefinition, options?: BuildSearchDocumentOptions): SearchDocument;

package/dist/services/build-search-document.js

@@ -25,20 +25,41 @@
  * in a document whose `facets` relation fields are already populated (depth
  * 1) with the target's identity + counter fields.
  *
- * v1 scope: `search.{body,facets,filters}` name **top-level** fields. Deep
- * paths into blocks / arrays are a follow-up.
+ * `search.{facets,filters}` name **top-level** fields. `search.body` may name
+ * a top-level field of any kind: scalar / `richText` leaves index directly,
+ * and container fields (`blocks` / `array` / `group`) are walked recursively —
+ * every nested `richText` and text (`text` / `textArea`) leaf is flattened and
+ * concatenated into one searchable body string. Nested non-text leaves
+ * (`select`, `relation`, numbers, booleans, dates, files) are skipped so block
+ * configuration never pollutes the index — the same "content, not
+ * configuration" rule the markdown assembler follows.
  */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/index.js';
 import { resolveIdentityField } from './populate.js';
 /**
  * Assemble one type-enriched `SearchDocument` from a locale-resolved
  * document and its collection's role-based `search` config.
  */
+/**
+ * Resolve the zone set a collection indexes into, or `null` when the
+ * collection doesn't opt into search at all. A collection with a `search`
+ * config but no explicit `zones` belongs to a single implicit zone equal to
+ * its own path. Shared by the assembler (below) and the client's
+ * cross-collection `search({ zone })` membership check so the two can't
+ * drift.
+ */
+export function resolveSearchZones(definition) {
+    const search = definition.search;
+    if (search == null)
+        return null;
+    return search.zones != null && search.zones.length > 0 ? search.zones : [definition.path];
+}
 export function buildSearchDocument(doc, definition, options = {}) {
     const locale = options.locale ?? doc.locale;
     const search = definition.search ?? {};
     const fieldsData = doc.fields ?? {};
     const title = stringValue(resolveLocalized(fieldsData[resolveIdentityField(definition) ?? ''], locale)) ?? '';
-    const zones = search.zones != null && search.zones.length > 0 ? search.zones : [definition.path];
+    const zones = resolveSearchZones(definition) ?? [definition.path];
     const fields = [];
     // --- body: searchable text -------------------------------------------------
     for (const decl of search.body ?? []) {
@@ -46,19 +67,7 @@ export function buildSearchDocument(doc, definition, options = {}) {
         const field = definition.fields.find((f) => f.name === name);
         if (field == null)
             continue;
-        let value;
-        if (field.type === 'richText') {
-            value = options.richTextToText
-                ? nonEmpty(options.richTextToText({
-                    value: resolveLocalized(fieldsData[name], locale),
-                    fieldPath: name,
-                    collectionPath: definition.path,
-                }))
-                : null;
-        }
-        else {
-            value = stringValue(resolveLocalized(fieldsData[name], locale));
-        }
+        const value = collectBodyText(field, fieldsData[name], definition.path, locale, options);
         if (value != null) {
             fields.push(withBoost({ name, type: 'text', role: 'body', value }, decl));
         }
@@ -113,6 +122,83 @@ function withBoost(field, decl) {
     const boost = typeof decl === 'string' ? undefined : decl.boost;
     return boost != null ? { ...field, boost } : field;
 }
+/** Text-bearing scalar leaves collected when walking into a container field. */
+const TEXT_LEAF_TYPES = new Set(['text', 'textArea']);
+/**
+ * Resolve a single `search.body` field to its searchable text. A scalar /
+ * `richText` leaf indexes directly (preserving the original top-level
+ * behaviour); a container (`group` / `array` / `blocks`) is walked
+ * recursively, flattening every nested text leaf into one string.
+ */
+function collectBodyText(field, rawValue, collectionPath, locale, options) {
+    const value = resolveLocalized(rawValue, locale);
+    if (isGroupField(field) || isArrayField(field) || isBlocksField(field)) {
+        return collectContainerText(field, value, collectionPath, locale, options);
+    }
+    return collectLeafText(field, value, collectionPath, options, /* permissive */ true);
+}
+/** Walk a container field, concatenating the text of its nested leaves. */
+function collectContainerText(field, value, collectionPath, locale, options) {
+    if (isGroupField(field)) {
+        return collectFieldSetText(field.fields, asRecord(value), collectionPath, locale, options);
+    }
+    if (isArrayField(field)) {
+        if (!Array.isArray(value))
+            return null;
+        return joinTexts(value.map((item) => collectFieldSetText(field.fields, asRecord(item), collectionPath, locale, options)));
+    }
+    // blocks: resolve each item's block definition by `_type`, then walk it.
+    if (!isBlocksField(field) || !Array.isArray(value))
+        return null;
+    const parts = [];
+    for (const item of value) {
+        const record = asRecord(item);
+        const block = field.blocks.find((b) => b.blockType === record._type);
+        if (block == null)
+            continue;
+        parts.push(collectFieldSetText(block.fields, record, collectionPath, locale, options));
+    }
+    return joinTexts(parts);
+}
+/** Collect text from every text-bearing leaf in a field set (one container level). */
+function collectFieldSetText(fields, data, collectionPath, locale, options) {
+    const parts = [];
+    for (const field of fields) {
+        const value = resolveLocalized(data?.[field.name], locale);
+        if (isGroupField(field) || isArrayField(field) || isBlocksField(field)) {
+            parts.push(collectContainerText(field, value, collectionPath, locale, options));
+        }
+        else {
+            // Nested leaves: only text-bearing types contribute — skip configuration
+            // (select, relation, numbers, booleans, dates, files).
+            parts.push(collectLeafText(field, value, collectionPath, options, /* permissive */ false));
+        }
+    }
+    return joinTexts(parts);
+}
+/**
+ * Extract text from a single leaf field. `richText` flows through the `toText`
+ * seam. For other scalars, `permissive` distinguishes a field the implementor
+ * named directly in `search.body` (index any scalar value, as before) from a
+ * leaf reached by walking into a container (restricted to text/textArea so
+ * block configuration values never leak into the index).
+ */
+function collectLeafText(field, value, collectionPath, options, permissive) {
+    if (field.type === 'richText') {
+        return options.richTextToText
+            ? nonEmpty(options.richTextToText({ value, fieldPath: field.name, collectionPath }))
+            : null;
+    }
+    if (permissive || TEXT_LEAF_TYPES.has(field.type)) {
+        return stringValue(value);
+    }
+    return null;
+}
+/** Join non-empty text parts with newlines, or null when there is nothing. */
+function joinTexts(parts) {
+    const filtered = parts.filter((p) => p != null && p.length > 0);
+    return filtered.length > 0 ? filtered.join('\n') : null;
+}
 /** A populated single relation or array of relations → array of envelopes. */
 function toEnvelopeArray(value) {
     if (Array.isArray(value))

package/dist/services/build-search-document.test.node.js

@@ -162,3 +162,114 @@ describe('buildSearchDocument', () => {
         expect(out.title).toBe('Restauration');
     });
 });
+// A collection whose prose lives inside a `blocks` field (the docs shape):
+// RichTextBlock (richText + a checkbox toggle) and PhotoBlock (text alt +
+// richText caption + a select + a relation). Mirrors the real-world case where
+// the searchable body is nested, not top-level.
+const blocksCollection = {
+    path: 'articles',
+    labels: { singular: 'Article', plural: 'Articles' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text', localized: true },
+        {
+            name: 'content',
+            label: 'Content',
+            type: 'blocks',
+            blocks: [
+                {
+                    blockType: 'richTextBlock',
+                    label: 'Richtext Block',
+                    fields: [
+                        { name: 'richText', label: 'Richtext', type: 'richText', localized: true },
+                        { name: 'constrainedWidth', label: 'Constrained', type: 'checkbox' },
+                    ],
+                },
+                {
+                    blockType: 'photoBlock',
+                    label: 'Photo Block',
+                    fields: [
+                        {
+                            name: 'display',
+                            label: 'Display',
+                            type: 'select',
+                            options: [
+                                { label: 'Default', value: 'default' },
+                                { label: 'Wide', value: 'wide' },
+                            ],
+                        },
+                        { name: 'photo', label: 'Photo', type: 'relation', targetCollection: 'media' },
+                        { name: 'alt', label: 'Alt', type: 'text' },
+                        { name: 'caption', label: 'Caption', type: 'richText', localized: true },
+                    ],
+                },
+            ],
+        },
+    ],
+    search: { body: [{ field: 'title', boost: 2 }, 'content'] },
+};
+describe('buildSearchDocument — container (blocks) body', () => {
+    function blockSource() {
+        return {
+            documentId: 'art-1',
+            locale: 'en',
+            status: 'published',
+            path: 'forests',
+            fields: {
+                title: 'Forests',
+                content: [
+                    {
+                        _type: 'richTextBlock',
+                        _id: 'b1',
+                        richText: { text: 'None of this is certain. But it reflects what we observed.' },
+                        constrainedWidth: true,
+                    },
+                    {
+                        _type: 'photoBlock',
+                        _id: 'b2',
+                        display: 'wide',
+                        photo: { _resolved: true, document: { fields: { title: 'A tree' } } },
+                        alt: 'A tall redwood',
+                        caption: { text: 'Old growth in the valley.' },
+                    },
+                ],
+            },
+        };
+    }
+    const doc = buildSearchDocument(blockSource(), blocksCollection, { richTextToText });
+    it('walks the blocks field and flattens nested richText + text leaves', () => {
+        const content = fieldByName(doc.fields, 'content');
+        expect(content).toMatchObject({ name: 'content', type: 'text', role: 'body' });
+        const value = content?.value;
+        expect(value).toContain('it reflects what we observed');
+        expect(value).toContain('A tall redwood');
+        expect(value).toContain('Old growth in the valley.');
+    });
+    it('skips nested non-text leaves (select, relation, checkbox) — no config noise', () => {
+        const value = fieldByName(doc.fields, 'content')?.value;
+        expect(value).not.toContain('wide'); // select
+        expect(value).not.toContain('A tree'); // relation target title
+        expect(value).not.toContain('true'); // checkbox
+    });
+    it('preserves top-level scalar body fields alongside the container', () => {
+        expect(fieldByName(doc.fields, 'title')).toMatchObject({ value: 'Forests', boost: 2 });
+    });
+    it('omits the container body field entirely when no toText seam is registered', () => {
+        // With no richText extractor, the only text-bearing leaves left are the
+        // PhotoBlock `alt` text.
+        const out = buildSearchDocument(blockSource(), blocksCollection);
+        const value = fieldByName(out.fields, 'content')?.value;
+        expect(value).toBe('A tall redwood');
+    });
+    it('produces no content field when a block field set has no text', () => {
+        const empty = {
+            ...blockSource(),
+            fields: {
+                title: 'Forests',
+                content: [{ _type: 'photoBlock', _id: 'b3', display: 'wide' }],
+            },
+        };
+        const out = buildSearchDocument(empty, blocksCollection, { richTextToText });
+        expect(fieldByName(out.fields, 'content')).toBeUndefined();
+    });
+});

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

@@ -38,7 +38,7 @@ export interface AuditCapability {
  * **both** `withTransaction` and `commands.audit`. Returns a non-null
  * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
  * rather than silently skipping the audit row or running it non-atomically.
- * See docs/TRANSACTIONS.md and docs/AUDIT.md.
+ * See docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export declare function requireAuditCapability(db: IDbAdapter): AuditCapability;
 /** Order-insensitive equality for the advertised-locale set. */

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

@@ -7,12 +7,12 @@
  */
 /**
  * Audit-log write helpers for the document-grain lifecycle write-points
- * (docs/AUDIT.md — Workstream 2). The audit log records the changes the
+ * (docs/06-auth-and-security/02-auditability.md — Workstream 2). The audit log records the changes the
  * immutable version stream does NOT capture an actor for: non-versioned
  * system-field writes (path, available-locales), in-place status transitions,
  * and deletions. Each such mutation and its audit row commit atomically inside
  * `withTransaction` — a silently-unwritten audit row is the one unacceptable
- * outcome (see docs/TRANSACTIONS.md).
+ * outcome (see docs/03-architecture/03-transactions.md).
  */
 import { ERR_AUDIT_UNSUPPORTED } from '../../lib/errors.js';
 import { actorId } from './internals.js';
@@ -42,7 +42,7 @@ export function auditActor(ctx) {
  * **both** `withTransaction` and `commands.audit`. Returns a non-null
  * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
  * rather than silently skipping the audit row or running it non-atomically.
- * See docs/TRANSACTIONS.md and docs/AUDIT.md.
+ * See docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export function requireAuditCapability(db) {
     const withTransaction = db.withTransaction;

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

@@ -73,7 +73,7 @@ export interface DocumentLifecycleContext {
      * — `assertActorCanPerform` runs at every lifecycle entry and rejects
      * a missing context.
      *
-     * See docs/AUTHN-AUTHZ.md.
+     * See docs/06-auth-and-security/01-authn-authz.md.
      */
     requestContext?: RequestContext;
 }

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

@@ -39,7 +39,7 @@ export declare function createDocument(ctx: DocumentLifecycleContext, params: {
      * sidebar widget). Document-grain and sticky like `path`: passed straight
      * to the storage primitive, which replaces the document's rows wholesale.
      * `undefined` writes nothing (a new document starts with an empty set —
-     * the safe opt-in default); `[]` clears it. See docs/I18N.md.
+     * the safe opt-in default); `[]` clears it. See docs/07-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<CreateDocumentResult>;

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

@@ -87,7 +87,7 @@ export async function createDocument(ctx, params) {
         // command directly — no `update` re-assertion, no separate tree event
         // (afterCreate covers invalidation). Post-version and best-effort: a
         // failure leaves the document created-but-unplaced and is logged, not
-        // thrown. See docs/DOCUMENT-TREE.md.
+        // thrown. See docs/04-collections/03-document-trees.md.
         if (definition.tree === true) {
             try {
                 await appendTreeRoot(ctx, documentId);

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

@@ -96,9 +96,9 @@ export async function deleteDocument(ctx, params) {
         // 3. Soft-delete all versions, atomically with the audit record. A
         //    whole-document delete mints no new version, so the version stream
         //    never records it — the audit log is the only place a deletion is
-        //    accountable (docs/AUDIT.md). Storage-file cleanup (step 4) is a
+        //    accountable (docs/06-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
         //    DB↔external side-effect and stays OUTSIDE the transaction — it is
-        //    post-commit, best-effort compensation (docs/TRANSACTIONS.md).
+        //    post-commit, best-effort compensation (docs/03-architecture/03-transactions.md).
         const audit = requireAuditCapability(db);
         const actor = auditActor(ctx);
         let deletedVersionCount = 0;
@@ -132,7 +132,7 @@ export async function deleteDocument(ctx, params) {
         //    structural-change invalidation event. Post-commit and best-effort,
         //    like file cleanup: a failure here leaves the soft-delete intact
         //    (status-at-edge already hides the deleted node's subtree from
-        //    reads) and is logged rather than thrown. See docs/DOCUMENT-TREE.md.
+        //    reads) and is logged rather than thrown. See docs/04-collections/03-document-trees.md.
         if (definition.tree === true) {
             try {
                 await promoteChildrenAndRemove(ctx, { documentId: params.documentId });

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

@@ -28,7 +28,7 @@ import type { DocumentLifecycleContext } from './context.js';
  * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
  * `created_by`, which the history strip renders as "unknown". Real
  * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
- * is unaffected. See docs/AUDIT.md — Workstream 1.
+ * is unaffected. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
  */
 export declare function actorId(ctx: DocumentLifecycleContext): string | undefined;
 /**
@@ -76,7 +76,7 @@ export declare function appendTreeRoot(ctx: DocumentLifecycleContext, documentId
  *
  * No-op for non-tree collections. Best-effort and post-version: a failure leaves
  * the document saved-but-unplaced and is logged, never thrown. See
- * docs/DOCUMENT-TREE.md.
+ * docs/04-collections/03-document-trees.md.
  */
 export declare function selfHealTreePlacement(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
 /** Extract `id` from the document object returned by `createDocumentVersion`. */

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

@@ -35,7 +35,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
  * `created_by`, which the history strip renders as "unknown". Real
  * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
- * is unaffected. See docs/AUDIT.md — Workstream 1.
+ * is unaffected. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
  */
 export function actorId(ctx) {
     const id = ctx.requestContext?.actor?.id;
@@ -131,7 +131,7 @@ export async function appendTreeRoot(ctx, documentId) {
  *
  * No-op for non-tree collections. Best-effort and post-version: a failure leaves
  * the document saved-but-unplaced and is logged, never thrown. See
- * docs/DOCUMENT-TREE.md.
+ * docs/04-collections/03-document-trees.md.
  */
 export async function selfHealTreePlacement(ctx, documentId) {
     if (ctx.definition.tree !== true)
@@ -210,7 +210,7 @@ export function resolvePathForUpdate(args) {
         // skip the write (existing path row stays as-is — sticky). The path row
         // lives under the document's source_locale (its anchor), not the mutable
         // global default — so this stays correct after the global default is
-        // switched. See docs/I18N.md.
+        // switched. See docs/07-internationalization/index.md.
         return explicitPath ?? undefined;
     }
     // Non-source-locale (translation) write: reject any path change with a warn

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

@@ -89,7 +89,7 @@ export async function changeDocumentStatus(ctx, params) {
         // 4–5. Mutate status in-place + auto-archive, atomically with the audit
         //      record. Status mutates the version row rather than minting a new
         //      version, so the version stream never captures *who* changed it —
-        //      the audit log is its only accountability home (docs/AUDIT.md).
+        //      the audit log is its only accountability home (docs/06-auth-and-security/02-auditability.md).
         const audit = requireAuditCapability(db);
         const actor = auditActor(ctx);
         await audit.withTransaction(async () => {

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

@@ -25,7 +25,7 @@ export interface UpdateDocumentSystemFieldsResult {
  * version. This service backs the admin path / available-locales widgets'
  * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
  * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/I18N.md.
+ * the resolved version's completeness ledger. See docs/07-internationalization/index.md.
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
@@ -40,7 +40,7 @@ export interface UpdateDocumentSystemFieldsResult {
  * No content hooks fire — these are not content writes. Accountability for
  * these mutations is the document-grain audit log: each field that actually
  * changes records a `document.path.changed` / `document.locales.changed` row
- * atomically with the write (docs/AUDIT.md — Workstream 2).
+ * atomically with the write (docs/06-auth-and-security/02-auditability.md — Workstream 2).
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.

package/dist/services/document-lifecycle/system-fields.js

@@ -22,7 +22,7 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  * version. This service backs the admin path / available-locales widgets'
  * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
  * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/I18N.md.
+ * the resolved version's completeness ledger. See docs/07-internationalization/index.md.
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
@@ -37,7 +37,7 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  * No content hooks fire — these are not content writes. Accountability for
  * these mutations is the document-grain audit log: each field that actually
  * changes records a `document.path.changed` / `document.locales.changed` row
- * atomically with the write (docs/AUDIT.md — Workstream 2).
+ * atomically with the write (docs/06-auth-and-security/02-auditability.md — Workstream 2).
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
@@ -78,7 +78,7 @@ export async function updateDocumentSystemFields(ctx, params) {
         // Both document-grain writes and their audit rows commit atomically.
         // These fields are non-versioned, so the version stream never records
         // them — the audit log is their only accountability home. One audit row
-        // per field that actually changed (docs/AUDIT.md).
+        // per field that actually changed (docs/06-auth-and-security/02-auditability.md).
         const currentPath = originalData.path;
         const currentLocales = originalData.availableLocales ?? [];
         const availableLocalesWritten = params.availableLocales !== undefined;

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

@@ -7,7 +7,7 @@
  */
 /**
  * Document-tree lifecycle service — the unversioned structural mutations for
- * `tree: true` collections (docs/DOCUMENT-TREE.md). Wraps the storage adapter's
+ * `tree: true` collections (docs/04-collections/03-document-trees.md). Wraps the storage adapter's
  * tree commands so that, like the versioned lifecycle services, they enforce the
  * actor ability and fire a collection hook. Tree writes mint no document version
  * and touch no user fields, so the `afterTreeChange` hook is the *only*