@byline/core 3.15.2 → 3.16.1

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

@@ -474,7 +474,7 @@ export interface DeleteContext {
 }
 /**
  * Context passed to the `afterTreeChange` hook — the structural-change
- * invalidation event for `tree: true` collections (docs/DOCUMENT-TREE.md).
+ * invalidation event for `tree: true` collections (docs/04-collections/03-document-trees.md).
  *
  * Tree mutations are document-grain and **unversioned**, so the normal
  * version-write invalidation (`afterCreate` / `afterUpdate` / `afterStatusChange`)
@@ -676,7 +676,7 @@ export declare function resolveUploadHooks(hooks: UploadHooks | UploadHooksLoade
  * 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/RELATIONSHIPS.md`).
+ * essential to foreclose the A→B→A loop (see `docs/04-collections/02-relationships.md`).
  */
 export interface AfterReadContext {
     /** The raw reconstructed document. Mutate in place — changes persist. */
@@ -709,7 +709,7 @@ export interface AfterReadContext {
  *   - `collectionPath` — the collection being queried (useful when the
  *     same hook function is reused across collections).
  *
- * See `docs/AUTHN-AUTHZ.md` for the strategic rationale; the Quick
+ * See `docs/06-auth-and-security/01-authn-authz.md` for the strategic rationale; the Quick
  * Reference there carries six worked recipes.
  */
 export interface BeforeReadContext {
@@ -786,7 +786,7 @@ export interface CollectionHooks {
      * (`removeFromTree`), or the promote-children-to-root that accompanies a
      * delete. Tree writes mint no document version, so this is the only
      * invalidation signal for them. Fires once per write with the full affected
-     * set ({@link TreeChangeContext}). See docs/DOCUMENT-TREE.md.
+     * set ({@link TreeChangeContext}). See docs/04-collections/03-document-trees.md.
      */
     afterTreeChange?: CollectionHookSlot<TreeChangeContext>;
     /**
@@ -795,7 +795,7 @@ export interface CollectionHooks {
      * that the query layer ANDs onto the caller's `where` to enforce
      * 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/AUTHN-AUTHZ.md` (Read-side
+     * combine with implicit AND. See `docs/06-auth-and-security/01-authn-authz.md` (Read-side
      * scoping + Quick Reference recipes).
      */
     beforeRead?: BeforeReadHookSlot;
@@ -970,7 +970,7 @@ export interface CollectionDefinition {
      * collection has at least one `localized` field, so the validator rejects
      * `advertiseLocales: true` on a collection with none.
      *
-     * See `docs/I18N.md`.
+     * See `docs/07-internationalization/index.md`.
      */
     advertiseLocales?: boolean;
     /**
@@ -1061,7 +1061,7 @@ export interface CollectionDefinition {
      * touch no user fields. Do **not** also declare a `parent` relation field; the
      * tree owns structure (a topic that genuinely belongs in two places is a
      * cross-link relation field, never a second tree edge). See
-     * docs/DOCUMENT-TREE.md.
+     * docs/04-collections/03-document-trees.md.
      */
     tree?: boolean;
     /**

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

@@ -39,7 +39,7 @@ export type ReadMode = 'any' | 'published';
  * safe default for internal/direct reads); `@byline/client` defaults it to
  * `'fallback'` for application reads. Availability follows path-coverage against
  * the default content locale; a document with no localized content is available
- * in every locale. See `docs/I18N.md`.
+ * in every locale. See `docs/07-internationalization/index.md`.
  */
 export type MissingLocalePolicy = 'empty' | 'fallback' | 'omit';
 /**
@@ -128,6 +128,28 @@ export interface RelationFilter {
     targetCollectionId: string;
     /** Filters applied to the target document. Recursive. */
     nested: DocumentFilter[];
+    /**
+     * Whether the source field is a multi-target (`hasMany`) relation. hasMany
+     * items are stored as indexed `store_relation` rows (`<field>.0`,
+     * `<field>.1`, …), so the adapter matches `field_name` by prefix instead
+     * of exact equality. Set at parse time from the field definition.
+     */
+    hasMany?: boolean;
+    /**
+     * Quantifier over the relation's target set, for `hasMany` relations
+     * (single relations are a set of ≤ 1 and compose the same way):
+     *
+     *   - `'some'` (default) — at least one target satisfies `nested`.
+     *   - `'every'` — no target fails `nested`. Vacuously true when the
+     *     document has no (resolving) targets on the field.
+     *   - `'none'` — no target satisfies `nested`. With empty `nested`,
+     *     matches documents that have no resolving targets at all.
+     *
+     * Targets that do not resolve in the selected read view (deleted, or
+     * unpublished under `readMode: 'published'`) are ignored by all three —
+     * the same visibility rule populate applies.
+     */
+    quantifier?: 'some' | 'every' | 'none';
 }
 /**
  * A boolean combinator group. Wraps a list of child filters with explicit
@@ -204,7 +226,7 @@ export interface IDbAdapter {
         documents: IDocumentCommands;
         counters: ICounterCommands;
         /**
-         * Append-only audit-log writes (docs/AUDIT.md — Workstream 2). Optional
+         * Append-only audit-log writes (docs/06-auth-and-security/02-auditability.md — Workstream 2). Optional
          * capability, paired with `withTransaction`: a consumer that records audit
          * entries asserts both are present and throws otherwise (it must never
          * silently skip the audit row). Adapters that model the audit log
@@ -215,14 +237,14 @@ export interface IDbAdapter {
     queries: {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
-        /** Audit-log reads — per-document history, system-wide report. See docs/AUDIT.md. */
+        /** Audit-log reads — per-document history, system-wide report. See docs/06-auth-and-security/02-auditability.md. */
         audit?: IAuditQueries;
     };
     /**
      * Optional capability: run `fn` inside a single database transaction so the
      * writes it performs commit or roll back atomically. The adapter propagates
      * the transaction to every `commands.*` call made within `fn` (see
-     * docs/TRANSACTIONS.md — AsyncLocalStorage propagation), so a service can
+     * docs/03-architecture/03-transactions.md — AsyncLocalStorage propagation), so a service can
      * compose multiple commands into one unit of work without threading a
      * transaction handle through their signatures.
      *
@@ -232,7 +254,7 @@ export interface IDbAdapter {
      * method** (or implement it to throw); a consumer that requires atomicity
      * (e.g. the audit log) MUST assert its presence and throw — never silently
      * run non-atomically, which would defeat the very guarantee it provides. See
-     * docs/TRANSACTIONS.md ("Serverless / HTTP-gateway databases — the contract
+     * docs/03-architecture/03-transactions.md ("Serverless / HTTP-gateway databases — the contract
      * seam").
      */
     withTransaction?: <T>(fn: () => Promise<T>) => Promise<T>;
@@ -243,7 +265,7 @@ export interface IDbAdapter {
      * boot by `initBylineCore` so in-place upgrades self-heal without a manual
      * step or a migrate-ordering constraint — a no-op (zero rows) once every
      * document is stamped. Optional so adapters that don't model `source_locale`
-     * need not implement it. See docs/I18N.md.
+     * need not implement it. See docs/07-internationalization/index.md.
      */
     backfillSourceLocales?: () => Promise<{
         rowsUpdated: number;
@@ -252,7 +274,7 @@ export interface IDbAdapter {
 /**
  * The realm of the actor that performed an audited change. `'admin'` for
  * admin-user actions, `'user'` reserved for the end-user realm, `'system'`
- * for deliberate internal-tooling writes. See docs/AUDIT.md.
+ * for deliberate internal-tooling writes. See docs/06-auth-and-security/02-auditability.md.
  */
 export type AuditActorRealm = 'admin' | 'user' | 'system';
 /** Input to `IAuditCommands.append` — one audit-log row. */
@@ -297,7 +319,7 @@ export interface AuditLogPage {
 }
 /**
  * Append-only audit-log writes. The companion read interface is
- * `IAuditQueries`. See docs/AUDIT.md — Workstream 2.
+ * `IAuditQueries`. See docs/06-auth-and-security/02-auditability.md — Workstream 2.
  */
 export interface IAuditCommands {
     /**
@@ -310,7 +332,7 @@ export interface IAuditCommands {
         id: string;
     }>;
 }
-/** Audit-log reads. See docs/AUDIT.md — Workstreams 3 & 4. */
+/** Audit-log reads. See docs/06-auth-and-security/02-auditability.md — Workstreams 3 & 4. */
 export interface IAuditQueries {
     /**
      * The audit history for one document, newest first, paged. Backs the
@@ -324,7 +346,7 @@ export interface IAuditQueries {
         page_size?: number;
     }): Promise<AuditLogPage>;
     /**
-     * The system-wide activity feed (docs/AUDIT.md — Workstream 4), newest
+     * The system-wide activity feed (docs/06-auth-and-security/02-auditability.md — Workstream 4), newest
      * first, paged and filterable. A read-time **union** of two disjoint event
      * sources, normalised onto the `AuditLogEntry` shape:
      *
@@ -364,7 +386,7 @@ export interface IAuditQueries {
 /**
  * Adapter capability for the shared-pool counter mechanism backing the
  * `counter` field type. See `packages/core/src/@types/field-types.ts`
- * (CounterField) for the field-level contract and `docs/COLLECTIONS.md`
+ * (CounterField) for the field-level contract and `docs/04-collections/index.md`
  * (Counter fields) for the conceptual overview.
  *
  * Both methods are keyed by the developer-facing `groupName` (the value
@@ -455,7 +477,7 @@ export interface IDocumentCommands {
          * editorial advertised-locale set. `undefined` leaves the existing set
          * untouched (sticky across versions, like `path`); `[]` clears it. The
          * locale values are the advertised content locales themselves, not the
-         * write locale. See `docs/I18N.md`.
+         * write locale. See `docs/07-internationalization/index.md`.
          */
         availableLocales?: string[];
         locale?: string;
@@ -473,7 +495,7 @@ export interface IDocumentCommands {
          * Only set on the initial create (when `documentId` is undefined) for
          * collections with `orderable: true`. Ignored on subsequent versions of
          * an existing document — order is admin metadata on the logical document,
-         * not per-version content. See docs/COLLECTIONS.md (Orderable collections).
+         * not per-version content. See docs/04-collections/index.md (Orderable collections).
          */
         orderKey?: string;
     }): Promise<{
@@ -487,7 +509,7 @@ export interface IDocumentCommands {
      * the change is immediate and applies across every version. Backs the admin
      * path widget's direct-write Save. The unique constraint on
      * `(collection_id, locale, path)` may surface as `ERR_PATH_CONFLICT` from the
-     * lifecycle layer. See `docs/I18N.md`.
+     * lifecycle layer. See `docs/07-internationalization/index.md`.
      */
     updateDocumentPath(params: {
         documentId: string;
@@ -501,7 +523,7 @@ export interface IDocumentCommands {
      * wholesale **without** minting a new version or touching workflow status —
      * the change is immediate and applies across every version. `[]` clears it.
      * Backs the admin available-locales widget's direct-write Save. See
-     * `docs/I18N.md`.
+     * `docs/07-internationalization/index.md`.
      */
     setDocumentAvailableLocales(params: {
         documentId: string;
@@ -555,7 +577,7 @@ export interface IDocumentCommands {
         documentId: string;
         locale: string;
         status?: string;
-        /** Acting user id for the version audit trail (`created_by`). See docs/AUDIT.md. */
+        /** Acting user id for the version audit trail (`created_by`). See docs/06-auth-and-security/02-auditability.md. */
         createdBy?: string;
     }): Promise<{
         newVersionId: string;
@@ -598,7 +620,7 @@ export interface IDocumentCommands {
      * **before** (its right neighbour). Either may be null — `{}` appends as the
      * only/last child, `beforeDocumentId` alone appends after it, `afterDocumentId`
      * alone prepends before it. Both are resolved within the *target* parent
-     * group. See docs/DOCUMENT-TREE.md.
+     * group. See docs/04-collections/03-document-trees.md.
      */
     placeTreeNode(params: {
         collectionId: string;
@@ -613,7 +635,7 @@ export interface IDocumentCommands {
      * Remove a document's edge row, returning it to the *unplaced* state (in the
      * collection, but not in the tree). Distinct from document deletion — the
      * document and its content are untouched. No-op when the node is already
-     * unplaced. See docs/DOCUMENT-TREE.md.
+     * unplaced. See docs/04-collections/03-document-trees.md.
      */
     removeFromTree(params: {
         documentId: string;
@@ -642,7 +664,7 @@ export interface IDocumentQueries {
         /**
          * 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.
+         * hooks for query scoping. See docs/06-auth-and-security/01-authn-authz.md.
          */
         requestContext?: RequestContext;
         /**
@@ -696,7 +718,7 @@ export interface IDocumentQueries {
      *
      * Source-locale only: this resolves the single canonical slug, which is the
      * only path row a document has today. When per-locale paths land (see
-     * docs/DOCUMENT-PATHS.md → "Phase — per-locale paths"), the write-side hook
+     * docs/04-collections/04-document-paths.md → "Phase — per-locale paths"), the write-side hook
      * contexts that consume this must be enriched to carry the locale each path
      * was derived under (or the full `locale → path` set) — a single canonical
      * `path` is no longer sufficient for per-localised-URL cache/CDN purges.
@@ -925,7 +947,7 @@ export interface IDocumentQueries {
      * parent, increasing toward the root). Empty for a root or unplaced node.
      *
      * Backs breadcrumbs and the read-time hierarchical-URL canonicalization
-     * (docs/DOCUMENT-TREE.md). Depth-bounded as a backstop against pathological
+     * (docs/04-collections/03-document-trees.md). Depth-bounded as a backstop against pathological
      * key state even though the write-path cycle guard prevents true cycles.
      *
      * **Status-at-edge.** `readMode: 'published'` joins
@@ -950,7 +972,7 @@ export interface IDocumentQueries {
      * `order_key`. `parentDocumentId: null` returns the collection's root nodes.
      * Scoped to `collectionId` so root reads (which have no parent to scope by)
      * stay within the collection. One level only — the recursive subtree read is
-     * a separate query. See docs/DOCUMENT-TREE.md.
+     * a separate query. See docs/04-collections/03-document-trees.md.
      */
     getTreeChildren(params: {
         collectionId: string;
@@ -961,7 +983,7 @@ export interface IDocumentQueries {
     }>>;
     /**
      * Resolve a single node's placement state in the tree, distinguishing the
-     * three tri-states (docs/DOCUMENT-TREE.md → "Node placement"):
+     * three tri-states (docs/04-collections/03-document-trees.md → "Node placement"):
      *
      *   - **Unplaced** (no edge row) → `{ placed: false, parentDocumentId: null }`
      *   - **Root** (edge row, null parent) → `{ placed: true,  parentDocumentId: null }`
@@ -993,7 +1015,7 @@ export interface IDocumentQueries {
      * `byline_current_published_documents` and drops any node without a current
      * published version; because the walk only recurses through *included*
      * nodes, an unpublished node's entire subtree is omitted — the spine is
-     * broken and descendants are not promoted (see docs/DOCUMENT-TREE.md).
+     * broken and descendants are not promoted (see docs/04-collections/03-document-trees.md).
      * `readMode: 'any'` (the default) includes every current, non-deleted node.
      * Depth-bounded by `maxDepth` as a backstop.
      *

package/dist/@types/query-predicate.d.ts

@@ -21,13 +21,35 @@ export interface FilterOperators {
     $in?: Array<string | number>;
     $nin?: Array<string | number>;
 }
+/**
+ * Quantifiers usable on a relation field's predicate value — the multi-target
+ * (`hasMany`) analogue of a nested sub-where. Each key carries a nested
+ * `QueryPredicate` evaluated against the relation's *targets*:
+ *
+ *   - `$some`  — at least one target matches (a bare nested sub-where on a
+ *     relation field is shorthand for this).
+ *   - `$every` — no target fails the predicate. Vacuously true when the
+ *     document has no targets on the field (Prisma-style semantics).
+ *   - `$none`  — no target matches. `$none: {}` matches documents with no
+ *     (resolving) targets at all.
+ *
+ * Multiple quantifier keys on one field AND together. Also valid on single
+ * relations (a set of ≤ 1). Targets that don't resolve in the selected read
+ * view (deleted, or unpublished under published-mode reads) are ignored.
+ */
+export interface RelationQuantifiers {
+    $some?: QueryPredicate;
+    $every?: QueryPredicate;
+    $none?: QueryPredicate;
+}
 /**
  * The value side of a predicate entry. Either a bare value (interpreted as
  * `$eq`), an operator object, a nested `QueryPredicate` (for cross-collection
- * relation filters or combinator children), or an array of `QueryPredicate`
- * (the value side of `$and` / `$or`).
+ * relation filters or combinator children), a `RelationQuantifiers` object
+ * (relation fields only), or an array of `QueryPredicate` (the value side of
+ * `$and` / `$or`).
  */
-export type PredicateValue = string | number | boolean | null | FilterOperators | QueryPredicate | QueryPredicate[];
+export type PredicateValue = string | number | boolean | null | FilterOperators | RelationQuantifiers | QueryPredicate | QueryPredicate[];
 /**
  * Structured predicate language used by:
  *   - the client API's `where` clause (re-exported as `WhereClause`),

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

@@ -200,7 +200,14 @@ export interface SearchFacetBucket {
 /** The result envelope returned by `SearchProvider.search`. */
 export interface SearchResults {
     hits: SearchHit[];
-    /** Total matches across all pages (not just the returned `hits`). */
+    /**
+     * Total matches across all pages (not just the returned `hits`).
+     *
+     * This is the *provider's* count. When the querying collection applies
+     * `beforeRead` row scoping, unauthorized hits are dropped **after**
+     * ranking (see `CollectionHandle.search`), so `total` — like facet
+     * counts — is approximate under scoping and exact without it.
+     */
     total: number;
     /**
      * Facet buckets keyed by field name, when `facets` was requested and the

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

@@ -64,7 +64,7 @@ export interface BaseConfig {
              * its path locale, and the completeness ledger — so changing this value
              * is safe for existing data: they keep reading against the locale they
              * were authored in. New documents created after the change anchor to the
-             * new value. See docs/I18N.md.
+             * new value. See docs/07-internationalization/index.md.
              *
              * (Switching this on a live system still needs the one-time
              * `backfillSourceLocales()` maintenance step to have stamped any rows
@@ -103,7 +103,7 @@ export interface BaseConfig {
          *
          * Optional at the type level so `BaseConfig` stays loose for tests
          * and seed scripts; required at runtime via `validateTranslations`
-         * whenever `interface.locales` is non-empty. See `docs/I18N.md` for
+         * whenever `interface.locales` is non-empty. See `docs/07-internationalization/index.md` for
          * the design.
          *
          * The shape is declared inline (rather than imported from

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/AUTHN-AUTHZ.md.
+ * See docs/06-auth-and-security/01-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/AUTHN-AUTHZ.md.
+ * See docs/06-auth-and-security/01-authn-authz.md.
  */
 export function assertActorCanPerform(context, collectionPath, verb) {
     if (!context) {

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

@@ -32,7 +32,7 @@ import type { CollectionDefinition } from '../@types/index.js';
  * predictable and avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/AUTHN-AUTHZ.md.
+ * docs/06-auth-and-security/01-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

@@ -30,7 +30,7 @@
  * predictable and avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/AUTHN-AUTHZ.md.
+ * docs/06-auth-and-security/01-authn-authz.md.
  */
 export function registerCollectionAbilities(registry, definition) {
     const path = definition.path;

package/dist/config/config.d.ts

@@ -47,7 +47,7 @@ export declare function getServerConfig(): ServerConfig;
  * config-driven at the read source. The payoff is canonical downstream
  * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
  * the order a document declared its locales in. Read-time projection only;
- * nothing persisted changes. See docs/I18N.md.
+ * nothing persisted changes. See docs/07-internationalization/index.md.
  */
 export declare function orderByContentLocale(codes: string[]): string[];
 export declare function defineBylineCore(core: unknown): void;

package/dist/config/config.js

@@ -124,7 +124,7 @@ export function getServerConfig() {
  * config-driven at the read source. The payoff is canonical downstream
  * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
  * the order a document declared its locales in. Read-time projection only;
- * nothing persisted changes. See docs/I18N.md.
+ * nothing persisted changes. See docs/07-internationalization/index.md.
  */
 export function orderByContentLocale(codes) {
     const content = getServerConfigInstance()?.i18n?.content;

package/dist/core.d.ts

@@ -38,7 +38,7 @@ export interface BylineCore<TAdminStore = unknown> {
      * during server bootstrap and before any admin UI renders.
      *
      * Consumed at runtime by `AdminAuth.assertAbility()` and at design
-     * time by the admin role-editor UI. See docs/AUTHN-AUTHZ.md.
+     * time by the admin role-editor UI. See docs/06-auth-and-security/01-authn-authz.md.
      */
     abilities: AbilityRegistry;
     /** Convenience wrapper around `abilities.register()`. */

package/dist/core.js

@@ -103,7 +103,7 @@ export const initBylineCore = async (config, pinoLogger) => {
     // and is a no-op (zero rows) once every document is stamped. Self-heals
     // in-place upgrades without a manual maintenance step. The write path stamps
     // new documents directly, so steady-state boots touch nothing. See
-    // docs/I18N.md.
+    // docs/07-internationalization/index.md.
     if (typeof composed.db.backfillSourceLocales === 'function') {
         const { rowsUpdated } = await composed.db.backfillSourceLocales();
         if (rowsUpdated > 0) {

package/dist/lib/errors.d.ts

@@ -111,6 +111,6 @@ export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstruc
  * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
  * user error: an auditability guarantee cannot be honoured non-atomically, so
  * the write is refused loudly rather than recorded with a gap. See
- * docs/TRANSACTIONS.md and docs/AUDIT.md.
+ * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;

package/dist/lib/errors.js

@@ -147,6 +147,6 @@ export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn
  * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
  * user error: an auditability guarantee cannot be honoured non-atomically, so
  * the write is refused loudly rather than recorded with a gap. See
- * docs/TRANSACTIONS.md and docs/AUDIT.md.
+ * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);

package/dist/query/parse-where.js

@@ -249,12 +249,19 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
         const field = definition.fields.find((f) => f.name === key);
         if (!field)
             continue; // Unknown field — skip silently
-        // Relation field with a plain-object sub-clause → cross-collection filter.
-        // A "plain object with no $-prefixed top-level keys" is unambiguously a
-        // nested where; anything else (bare value, operator object) stays in the
-        // ordinary field-filter path below and matches the relation's
+        // Relation field with a quantifier object (`$some` / `$every` / `$none`)
+        // or a plain-object sub-clause → cross-collection filter(s).
+        //
+        //   - `{ gallery: { $some: { … } } }` — explicit quantifier(s) over the
+        //     relation's target set; multiple quantifier keys AND together.
+        //   - `{ category: { path: 'news' } }` — a plain object with no
+        //     $-prefixed top-level keys is unambiguously a nested where,
+        //     shorthand for `$some`.
+        //
+        // Anything else (bare value, operator object) stays in the ordinary
+        // field-filter path below and matches the relation's
         // target_document_id column directly.
-        if (field.type === 'relation' && isPlainSubWhere(rawValue)) {
+        if (field.type === 'relation' && (isQuantifierObject(rawValue) || isPlainSubWhere(rawValue))) {
             if (!ctx) {
                 // No way to resolve the target without a ParseContext. Direct
                 // callers of `parseWhere` (tests, tooling) can legitimately hit
@@ -273,21 +280,35 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 continue;
             }
             const targetCollectionId = await ctx.resolveCollectionId(targetPath);
-            const nested = await parseWhereInternal(rawValue, targetDef, ctx, {
-                isNested: true,
-                inCombinator: false,
-            });
-            // 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,
-                targetCollectionId,
-                nested: nested.filters,
-            });
+            // Normalise both forms to a list of (quantifier, sub-where) pairs —
+            // the plain sub-where is shorthand for a single `$some`.
+            const quantified = isQuantifierObject(rawValue)
+                ? Object.entries(rawValue).map(([qKey, sub]) => ({
+                    quantifier: qKey.slice(1),
+                    sub: sub,
+                }))
+                : [{ quantifier: 'some', sub: rawValue }];
+            for (const { quantifier, sub } of quantified) {
+                const nested = await parseWhereInternal(sub, targetDef, ctx, {
+                    isNested: true,
+                    inCombinator: false,
+                });
+                // 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.
+                // `hasMany: false` / `quantifier: 'some'` are the adapter defaults —
+                // omit them so the plain single-relation filter shape is unchanged.
+                result.filters.push({
+                    kind: 'relation',
+                    fieldName: key,
+                    targetCollectionId,
+                    nested: nested.filters,
+                    ...(relation.hasMany === true ? { hasMany: true } : {}),
+                    ...(quantifier === 'some' ? {} : { quantifier }),
+                });
+            }
             continue;
         }
         const storeInfo = fieldTypeToStore[field.type];
@@ -350,6 +371,36 @@ export function parseSort(sort, definition) {
  * than a comparison value.
  */
 const COMBINATOR_KEYS = new Set(['$and', '$or']);
+/**
+ * Relation quantifier keys (`{ gallery: { $some: { … } } }`). Only
+ * meaningful on relation fields; each key's value is a nested sub-where
+ * evaluated against the relation's targets.
+ */
+const QUANTIFIER_KEYS = new Set(['$some', '$every', '$none']);
+/**
+ * A quantifier object is a non-null, non-array object whose keys are *all*
+ * quantifier keys (`$some` / `$every` / `$none`), each carrying a nested
+ * sub-where object (empty allowed — `$none: {}` means "no targets at all").
+ * Mixing quantifier keys with field names or operators is not a recognised
+ * shape and falls through to the ordinary operator path (which rejects it).
+ */
+function isQuantifierObject(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    if (Array.isArray(raw))
+        return false;
+    const keys = Object.keys(raw);
+    if (keys.length === 0)
+        return false;
+    for (const k of keys) {
+        if (!QUANTIFIER_KEYS.has(k))
+            return false;
+        const v = raw[k];
+        if (v === null || typeof v !== 'object' || Array.isArray(v))
+            return false;
+    }
+    return true;
+}
 /**
  * A "plain sub-where" is a non-null, non-array object whose top-level keys
  * are field names or predicate-level combinators (`$and` / `$or`) — but

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

@@ -72,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

@@ -40,12 +40,26 @@ 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 ?? []) {

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*

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

@@ -43,7 +43,7 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
      * The editorial advertised-locale set. `undefined` leaves the existing
      * set untouched (sticky — document-grain, like `path`); an explicit array
      * (empty included) replaces it wholesale. Driven by the admin
-     * available-locales sidebar widget. See docs/I18N.md.
+     * available-locales sidebar widget. See docs/07-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentResult>;
@@ -78,7 +78,7 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      * The editorial advertised-locale set (typically supplied alongside
      * patches when the admin available-locales widget has been edited).
      * `undefined` leaves the existing set untouched (sticky); an explicit
-     * array replaces it wholesale. See docs/I18N.md.
+     * array replaces it wholesale. See docs/07-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentWithPatchesResult>;

package/dist/services/document-lifecycle.test.node.js

@@ -36,7 +36,7 @@ function createMockDb() {
     const getDocumentById = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
     const getCurrentPath = vi.fn().mockResolvedValue('current-path');
-    // Audit capability (docs/AUDIT.md — W2). `withTransaction` is a passthrough
+    // Audit capability (docs/06-auth-and-security/02-auditability.md — W2). `withTransaction` is a passthrough
     // in unit tests (runs the unit of work immediately, no real tx); `append`
     // records the calls so write-point tests can assert the audit rows emitted.
     const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
@@ -165,7 +165,7 @@ describe('Document lifecycle service', () => {
                 data: { title: 'Hello' },
                 locale: 'en',
             });
-            // Audit contract (docs/AUDIT.md — W1): every version row
+            // Audit contract (docs/06-auth-and-security/02-auditability.md — W1): every version row
             // records the actor that created it.
             expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe(TEST_ACTOR_ID);
         });
@@ -703,7 +703,7 @@ describe('Document lifecycle service', () => {
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
             await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
-            // The mutation + audit row run inside one withTransaction (docs/AUDIT.md).
+            // The mutation + audit row run inside one withTransaction (docs/06-auth-and-security/02-auditability.md).
             expect(withTransaction).toHaveBeenCalledOnce();
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',

package/dist/services/document-to-markdown.d.ts

@@ -8,7 +8,7 @@
 /**
  * `documentToMarkdown` — the document-grain markdown assembler for the
  * agent-readable export surface (`.md` routes, `llms.txt`). See
- * docs/TODO.md → "Markdown export".
+ * TODO-INTERNAL.md → "Markdown export".
  *
  * A page is a composite (text, richtext, blocks, arrays, relations); this
  * walks the collection's schema and the locale-resolved field data in

package/dist/services/document-to-markdown.js

@@ -8,7 +8,7 @@
 /**
  * `documentToMarkdown` — the document-grain markdown assembler for the
  * agent-readable export surface (`.md` routes, `llms.txt`). See
- * docs/TODO.md → "Markdown export".
+ * TODO-INTERNAL.md → "Markdown export".
  *
  * A page is a composite (text, richtext, blocks, arrays, relations); this
  * walks the collection's schema and the locale-resolved field data in

package/dist/services/document-to-markdown.test.node.js

@@ -9,7 +9,7 @@
  * Contract tests for the document-grain markdown assembler. The expected
  * strings ARE the format contract — agents build on this shape, so a
  * change here is a consumer-visible format change and should be
- * deliberate (docs/TODO.md → "The output is a contract surface").
+ * deliberate (TODO-INTERNAL.md → "The output is a contract surface").
  */
 import { describe, expect, it } from 'vitest';
 import { documentToMarkdown } from './document-to-markdown.js';

package/dist/services/index.d.ts

@@ -1,7 +1,7 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { type AssignCounterValuesInput, assignCounterValues } from './assign-counter-values.js';
-export { type BuildSearchDocumentOptions, buildSearchDocument, type SearchSourceDocument, } from './build-search-document.js';
+export { type BuildSearchDocumentOptions, buildSearchDocument, resolveSearchZones, type SearchSourceDocument, } from './build-search-document.js';
 export { type CollectionRecord, type EnsureCollectionsInput, ensureCollections, } from './collection-bootstrap.js';
 export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';

package/dist/services/index.js

@@ -2,7 +2,7 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { assignCounterValues } from './assign-counter-values.js';
-export { buildSearchDocument, } from './build-search-document.js';
+export { buildSearchDocument, resolveSearchZones, } from './build-search-document.js';
 export { ensureCollections, } from './collection-bootstrap.js';
 export { discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';

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/RELATIONSHIPS.md for the full design rationale.
+ * See docs/04-collections/02-relationships.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.15.2",
+  "version": "3.16.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -73,19 +73,17 @@
   ],
   "dependencies": {
     "dotenv": "^17.4.2",
-    "jose": "^6.2.3",
-    "npm-run-all": "^4.1.5",
     "pino": "^10.3.1",
     "sharp": "^0.34.5",
-    "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.15.2"
+    "@byline/auth": "3.16.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
     "@types/node": "^25.9.1",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
+    "npm-run-all": "^4.1.5",
     "tsc-alias": "^1.8.17",
     "tsx": "^4.22.3",
     "typescript": "6.0.3",