@byline/db-postgres 3.15.1 → 3.16.0

package/dist/database/schema/auth.js

@@ -20,7 +20,7 @@
  *     to 1; bumped by write paths when needed).
  *   - snake_case column names matching the rest of the Byline schema.
  *
- * See docs/AUTHN-AUTHZ.md for the full data model and present-state
+ * See docs/06-auth-and-security/01-authn-authz.md for the full data model and present-state
  * reference.
  */
 import { relations } from 'drizzle-orm';

package/dist/database/schema/index.js

@@ -21,7 +21,7 @@ import { createdAt, timestamps } from './common.js';
  *
  * Captured here (rather than only in a hand-written migration) so future
  * regenerations from this schema reproduce the COLLATE clause cleanly.
- * See migration `0003_order_key_byte_collation.sql` and `docs/COLLECTIONS.md` (Orderable collections).
+ * See migration `0003_order_key_byte_collation.sql` and `docs/04-collections/index.md` (Orderable collections).
  */
 const varcharByteSorted = customType({
     dataType(config) {
@@ -61,7 +61,7 @@ export const documents = pgTable('byline_documents', {
     //
     // Uses `varcharByteSorted` (COLLATE "C") so DB ordering matches JS string
     // comparison — the fractional-index algorithm requires this. See
-    // `varcharByteSorted` above and docs/COLLECTIONS.md (Orderable collections).
+    // `varcharByteSorted` above and docs/04-collections/index.md (Orderable collections).
     order_key: varcharByteSorted('order_key', { length: 128 }),
     // The content locale this document was first authored in — its per-document
     // data anchor. Set once at creation (= the global default content locale at
@@ -119,7 +119,7 @@ export const documentVersions = pgTable('byline_document_versions', {
 // installation's default content locale; per-locale UI is a future phase
 // that adds rows for additional locales without reshaping the schema.
 // History is intentionally not preserved here — path rows are updated in
-// place. See `docs/DOCUMENT-PATHS.md` § "Path uniqueness".
+// place. See `docs/04-collections/04-document-paths.md` § "Path uniqueness".
 export const documentPaths = pgTable('byline_document_paths', {
     document_id: uuid('document_id')
         .notNull()
@@ -148,7 +148,7 @@ export const documentPaths = pgTable('byline_document_paths', {
 // carries forward across edits and survives restore. Surfaced on reads as
 // `availableLocales`; the public advertised set is the intersection with the
 // ledger's `_availableVersionLocales`. Replaced wholesale on write (the lifecycle
-// deletes then re-inserts the set), never appended. See docs/I18N.md.
+// deletes then re-inserts the set), never appended. See docs/07-internationalization/index.md.
 export const documentAvailableLocales = pgTable('byline_document_available_locales', {
     document_id: uuid('document_id')
         .notNull()
@@ -172,14 +172,14 @@ export const documentAvailableLocales = pgTable('byline_document_available_local
 // identically in any locale). Computed status-blind at write time and frozen
 // on the immutable version, so restore / point-in-time reads stay consistent.
 // Drives `localeFallback: 'strict'` reads via an indexed EXISTS gate without
-// scanning the store_* tables. See docs/I18N.md.
+// scanning the store_* tables. See docs/07-internationalization/index.md.
 export const documentVersionLocales = pgTable('byline_document_version_locales', {
     document_version_id: uuid('document_version_id')
         .notNull()
         .references(() => documentVersions.id, { onDelete: 'cascade' }),
     locale: varchar('locale', { length: 10 }).notNull(),
 }, (table) => [primaryKey({ columns: [table.document_version_id, table.locale] })]);
-// Document Tree — single-parent ordered adjacency. See docs/DOCUMENT-TREE.md.
+// Document Tree — single-parent ordered adjacency. See docs/04-collections/03-document-trees.md.
 //
 // A document-grain, unversioned hierarchy primitive for `tree: true`
 // collections (self-referential, single collection). Rows reference the logical
@@ -217,7 +217,7 @@ export const documentRelationships = pgTable('byline_document_relationships', {
 // `path` is intentionally NOT projected here. Path resolution is locale-
 // aware and lives in the storage adapter's read functions, which join
 // `byline_document_paths` with the requested locale + default-locale
-// fallback. See docs/DOCUMENT-PATHS.md.
+// fallback. See docs/04-collections/04-document-paths.md.
 export const currentDocumentsView = pgView('byline_current_documents').as((qb) => {
     const sq = qb.$with('sq').as(qb
         .select({
@@ -260,7 +260,7 @@ export const currentDocumentsView = pgView('byline_current_documents').as((qb) =
         // read paths (`buildLocaleChain` / `pathProjection` / field-fallback)
         // re-base onto the per-document source rather than the mutable global
         // default — a primary-key join, already present for `order_key`.
-        // See docs/I18N.md.
+        // See docs/07-internationalization/index.md.
         source_locale: documents.source_locale,
     })
         .from(sq)
@@ -556,7 +556,7 @@ export const documentRelationshipsRelations = relations(documentRelationships, (
     }),
 }));
 // Document-tree edges on the logical document. The tree read path itself is a
-// recursive CTE (see docs/DOCUMENT-TREE.md), not the Drizzle query builder —
+// recursive CTE (see docs/04-collections/03-document-trees.md), not the Drizzle query builder —
 // these relations exist for completeness / ad-hoc joins.
 export const documentTreeRelations = relations(documents, ({ many }) => ({
     // The membership edge where this document is the child — its placement in the
@@ -660,7 +660,7 @@ export const jsonStoreRelations = relations(jsonStore, ({ one }) => ({
 // fit without a second migration. Append-only and deliberately **FK-free**: an
 // audit row is an immutable historical fact that must outlive the document,
 // collection, or actor it references — a `document.deleted` row cannot be
-// allowed to cascade-delete itself. See docs/AUDIT.md — Workstream 2.
+// allowed to cascade-delete itself. See docs/06-auth-and-security/02-auditability.md — Workstream 2.
 export const auditLog = pgTable('byline_audit_log', {
     id: uuid('id').primaryKey(), // UUIDv7 — time-ordered, so id ordering ≈ time ordering
     document_id: uuid('document_id'), // NULL for admin-realm (non-document) events; no FK

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export interface PgAdapter extends IDbAdapter {
      * existed, so `localeFallback: 'strict'` reads can see pre-existing
      * documents. Idempotent; uses the configured default content locale. Kept
      * off the core `IDbAdapter` contract (no service depends on it) — see
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     backfillVersionLocales(): Promise<{
         rowsInserted: number;
@@ -42,7 +42,7 @@ export interface PgAdapter extends IDbAdapter {
      * default content locale (the anchor they were implicitly authored against).
      * Idempotent; run automatically at boot by `initBylineCore` (also exposed on
      * the core `IDbAdapter` contract as an optional method) — see
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     backfillSourceLocales(): Promise<{
         rowsUpdated: number;
@@ -53,7 +53,7 @@ export interface PgAdapter extends IDbAdapter {
      * unless the document is complete in the target. Writes a new immutable
      * version. `dryRun` reports the would-be outcome without writing. Off the
      * core `IDbAdapter` contract (maintenance/admin operation) — see
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     reAnchorDocument(params: {
         documentId: string;
@@ -83,7 +83,7 @@ export declare const pgAdapter: ({ connectionString, collections, defaultContent
      * for documents whose `source_locale` is not yet backfilled. Per-document
      * reads and writes otherwise re-base onto each document's own `source_locale`
      * (carried on the current-documents views), so changing this value does not
-     * re-interpret existing data. See docs/I18N.md.
+     * re-interpret existing data. See docs/07-internationalization/index.md.
      */
     defaultContentLocale: string;
     /**

package/dist/index.js

@@ -22,7 +22,7 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
         connectionTimeoutMillis,
     });
     const db = drizzle(pool, { schema });
-    // Request-scoped transaction propagation (docs/TRANSACTIONS.md). The command
+    // Request-scoped transaction propagation (docs/03-architecture/03-transactions.md). The command
     // builders run on the DBManager — each `this.db` access resolves to the
     // ambient transaction when a `withTransaction` boundary is open, else the
     // pool. Queries and counters stay on the raw `db` for now (reads don't need

package/dist/lib/db-manager.d.ts

@@ -12,7 +12,7 @@
  * `withLogContext`). The full design — the service-owned `withTransaction`
  * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
  * caveat, and the serverless db-contract-seam decisions — lives in
- * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * `docs/03-architecture/03-transactions.md`. This machinery is deliberately adapter-internal:
  * transactions are driver-specific, so `@byline/core` only declares the
  * `withTransaction` capability on `IDbAdapter`, never the implementation.
  */

package/dist/lib/db-manager.js

@@ -12,7 +12,7 @@
  * `withLogContext`). The full design — the service-owned `withTransaction`
  * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
  * caveat, and the serverless db-contract-seam decisions — lives in
- * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * `docs/03-architecture/03-transactions.md`. This machinery is deliberately adapter-internal:
  * transactions are driver-specific, so `@byline/core` only declares the
  * `withTransaction` capability on `IDbAdapter`, never the implementation.
  */
@@ -37,7 +37,7 @@ export class TXManagerImpl {
         // `tx` is Drizzle's PgTransaction; it carries the full query-builder
         // surface every command uses. The cast bridges the one structural gap
         // to NodePgDatabase — the transaction lacks `$client`, which no command
-        // touches. See docs/TRANSACTIONS.md.
+        // touches. See docs/03-architecture/03-transactions.md.
         transactionALS.run(tx, fn));
     }
 }

package/dist/modules/audit/audit-commands.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Append-only audit-log writes (docs/AUDIT.md — Workstream 2). A deliberately
+ * Append-only audit-log writes (docs/06-auth-and-security/02-auditability.md — Workstream 2). A deliberately
  * dumb command: it inserts one row and knows nothing about *which* changes
  * warrant an audit entry — that policy lives in the lifecycle services, which
  * wrap the mutation + this append in `withTransaction` so they commit

package/dist/modules/audit/audit-queries.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Audit-log reads (docs/AUDIT.md — Workstreams 3 & 4). Reads run on the pool
+ * Audit-log reads (docs/06-auth-and-security/02-auditability.md — Workstreams 3 & 4). Reads run on the pool
  * directly — they never need to join an audit write's transaction — so this
  * takes the raw connection rather than the `DBManager`. Access scoping is the
  * caller's responsibility (the document's own read gate); these queries do no

package/dist/modules/audit/tests/activity-feed.test.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Integration tests for the system-wide activity feed (docs/AUDIT.md — W4):
+ * Integration tests for the system-wide activity feed (docs/06-auth-and-security/02-auditability.md — W4):
  * `audit.findAuditLog`, the read-time UNION of the version stream (content
  * saves → `document.created` / `document.updated`) and the audit log
  * (everything else). Exercises both sources, the cross-source `occurred_at`

package/dist/modules/audit/tests/audit-log.test.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Integration tests for the audit-log storage layer (docs/AUDIT.md — W2):
+ * Integration tests for the audit-log storage layer (docs/06-auth-and-security/02-auditability.md — W2):
  * `audit.append` (write) + `audit.getDocumentAuditLog` (read), and the
  * load-bearing property that an `append` issued inside `withTransaction`
  * commits or rolls back **with** the transaction it is part of.

package/dist/modules/storage/storage-commands.d.ts

@@ -40,7 +40,7 @@ export declare class CollectionCommands implements ICollectionCommands {
      * The executor for this call — the ambient transaction when a
      * `withTransaction` boundary is open, otherwise the pool. Resolved per
      * access so every `this.db.*` below transparently joins an enclosing
-     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
      */
     private get db();
     create(path: string, config: CollectionDefinition, opts?: {
@@ -85,7 +85,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * The executor for this call — the ambient transaction when a
      * `withTransaction` boundary is open, otherwise the pool. Resolved per
      * access so every `this.db.*` below transparently joins an enclosing
-     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
      */
     private get db();
     /**
@@ -116,7 +116,7 @@ export declare class DocumentCommands implements IDocumentCommands {
          * `undefined` leaves the existing set untouched (sticky across versions,
          * like `path`); an empty array clears it (advertise nothing). The locale
          * values are the advertised content locales themselves, not the default
-         * locale. See docs/I18N.md.
+         * locale. See docs/07-internationalization/index.md.
          */
         availableLocales?: string[];
         locale?: string;
@@ -163,7 +163,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * empty array clears the set (advertise nothing). Shared by
      * `createDocumentVersion` (step 2b, create write path) and the standalone
      * `setDocumentAvailableLocales` command (the non-versioned admin
-     * available-locales widget write). See docs/I18N.md.
+     * available-locales widget write). See docs/07-internationalization/index.md.
      */
     private writeDocumentAvailableLocales;
     /**
@@ -194,7 +194,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * **without** minting a new document version or touching workflow status. The
      * change is immediate and applies across every version of the document; the
      * public advertised set remains the intersection with the resolved version's
-     * completeness ledger. See docs/I18N.md.
+     * completeness ledger. See docs/07-internationalization/index.md.
      */
     setDocumentAvailableLocales(params: {
         documentId: string;
@@ -211,7 +211,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * so callers must have written them first. Shared by the create write path
      * (step 6) and `reAnchorDocument` (which recomputes against the new source).
      * Assumes the version has no ledger rows yet (a freshly-inserted version).
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     private writeVersionLocaleLedger;
     /**
@@ -275,7 +275,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * identities preserved), and computes that version's ledger against the new
      * source. `dryRun` performs only the eligibility check and reports the
      * outcome that *would* result, writing nothing. See
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     reAnchorDocument(params: {
         documentId: string;
@@ -294,7 +294,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * "client switched the default content locale, move every fully-translated
      * document onto it" operation; the `skipped-incomplete` results double as the
      * outstanding-translation backlog. `dryRun` reports what would happen without
-     * writing. See docs/I18N.md.
+     * writing. See docs/07-internationalization/index.md.
      */
     reAnchorDocuments(params: {
         targetLocale: string;
@@ -320,7 +320,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * a version's computed locale set never changes. Returns the number of
      * `(version, locale)` rows inserted.
      *
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     backfillVersionLocales(): Promise<{
         rowsInserted: number;
@@ -339,7 +339,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      *
      * Returns the number of document rows stamped.
      *
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     backfillSourceLocales(): Promise<{
         rowsUpdated: number;

package/dist/modules/storage/storage-commands.js

@@ -16,7 +16,7 @@ import { getFirstOrThrow } from './storage-utils.js';
  * Depth backstop for the document-tree recursive walks (cycle guard, ancestor
  * walk). The write-path cycle guard prevents true cycles, so this only bounds
  * recursion against pre-existing pathological state — far deeper than any real
- * documentation hierarchy. See docs/DOCUMENT-TREE.md.
+ * documentation hierarchy. See docs/04-collections/03-document-trees.md.
  */
 const TREE_MAX_DEPTH = 10_000;
 /**
@@ -31,7 +31,7 @@ export class CollectionCommands {
      * The executor for this call — the ambient transaction when a
      * `withTransaction` boundary is open, otherwise the pool. Resolved per
      * access so every `this.db.*` below transparently joins an enclosing
-     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
      */
     get db() {
         return this.dbManager.get();
@@ -78,7 +78,7 @@ export class DocumentCommands {
      * The executor for this call — the ambient transaction when a
      * `withTransaction` boundary is open, otherwise the pool. Resolved per
      * access so every `this.db.*` below transparently joins an enclosing
-     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
      */
     get db() {
         return this.dbManager.get();
@@ -103,7 +103,7 @@ export class DocumentCommands {
             // source locale rather than the mutable global default. NULL (a row not
             // yet touched by `backfillSourceLocales`) falls back to the configured
             // default — the value it was implicitly authored against.
-            // See docs/I18N.md.
+            // See docs/07-internationalization/index.md.
             let sourceLocale;
             if (documentId == null) {
                 documentId = uuidv7();
@@ -282,7 +282,7 @@ export class DocumentCommands {
             // accounts for the per-locale carry-forward in step 5 — not just the
             // freshly-flattened locale. A version with no localized content at all
             // records a single `'all'` sentinel (it renders identically in any
-            // locale). Status-blind by design — see docs/I18N.md.
+            // locale). Status-blind by design — see docs/07-internationalization/index.md.
             await this.writeVersionLocaleLedger(tx, documentVersion.id, sourceLocale);
             return {
                 document: documentVersion,
@@ -329,7 +329,7 @@ export class DocumentCommands {
      * empty array clears the set (advertise nothing). Shared by
      * `createDocumentVersion` (step 2b, create write path) and the standalone
      * `setDocumentAvailableLocales` command (the non-versioned admin
-     * available-locales widget write). See docs/I18N.md.
+     * available-locales widget write). See docs/07-internationalization/index.md.
      */
     async writeDocumentAvailableLocales(tx, args) {
         await tx
@@ -376,7 +376,7 @@ export class DocumentCommands {
      * **without** minting a new document version or touching workflow status. The
      * change is immediate and applies across every version of the document; the
      * public advertised set remains the intersection with the resolved version's
-     * completeness ledger. See docs/I18N.md.
+     * completeness ledger. See docs/07-internationalization/index.md.
      */
     async setDocumentAvailableLocales(params) {
         await this.db.transaction(async (tx) => {
@@ -397,7 +397,7 @@ export class DocumentCommands {
      * so callers must have written them first. Shared by the create write path
      * (step 6) and `reAnchorDocument` (which recomputes against the new source).
      * Assumes the version has no ledger rows yet (a freshly-inserted version).
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     async writeVersionLocaleLedger(tx, versionId, sourceLocale) {
         await tx.execute(sql `
@@ -578,7 +578,7 @@ export class DocumentCommands {
      * identities preserved), and computes that version's ledger against the new
      * source. `dryRun` performs only the eligibility check and reports the
      * outcome that *would* result, writing nothing. See
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     async reAnchorDocument(params) {
         const { documentId, targetLocale, dryRun = false, createdBy } = params;
@@ -660,7 +660,7 @@ export class DocumentCommands {
      * "client switched the default content locale, move every fully-translated
      * document onto it" operation; the `skipped-incomplete` results double as the
      * outstanding-translation backlog. `dryRun` reports what would happen without
-     * writing. See docs/I18N.md.
+     * writing. See docs/07-internationalization/index.md.
      */
     async reAnchorDocuments(params) {
         const { targetLocale, collectionId, dryRun = false } = params;
@@ -721,7 +721,7 @@ export class DocumentCommands {
      * a version's computed locale set never changes. Returns the number of
      * `(version, locale)` rows inserted.
      *
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     async backfillVersionLocales() {
         const result = await this.db.execute(sql `
@@ -779,7 +779,7 @@ export class DocumentCommands {
      *
      * Returns the number of document rows stamped.
      *
-     * See docs/I18N.md.
+     * See docs/07-internationalization/index.md.
      */
     async backfillSourceLocales() {
         const result = await this.db

package/dist/modules/storage/storage-queries.d.ts

@@ -84,7 +84,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * document, or any document read after the global default is switched, falls
      * back to the locale it was actually authored in) — otherwise the configured
      * global default, which is correct for not-yet-anchored rows and for
-     * row-less lookups (findByPath). See docs/I18N.md.
+     * row-less lookups (findByPath). See docs/07-internationalization/index.md.
      */
     private buildLocaleChain;
     /**
@@ -115,7 +115,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * `availableLocales` — the deliberate
      * counterpart to the version-grain `_availableVersionLocales` ledger fact;
      * the public advertised set is their intersection. One indexed query per
-     * call. See docs/I18N.md.
+     * call. See docs/07-internationalization/index.md.
      */
     private getAdvertisedLocalesByDocument;
     /**
@@ -635,10 +635,26 @@ export declare class DocumentQueries implements IDocumentQueries {
      * the outer read is in published mode), then recurses each nested
      * filter against the target version's own `td.id`.
      *
-     * With no nested filters this reduces to "source has any relation row
-     * at all on this field pointing at a target that resolves in the
-     * selected view" — useful as a base case but more typically the
-     * nested list carries a predicate.
+     * `hasMany` relations store one row per item at an indexed field name
+     * (`<field>.0`, `<field>.1`, …), so the field match switches to a prefix
+     * `LIKE`; single relations match the exact name.
+     *
+     * The `quantifier` selects the set semantics over the relation's
+     * (resolving) targets:
+     *
+     *   - `'some'` (default): `EXISTS (… AND nested…)` — at least one target
+     *     matches. With no nested filters this reduces to "has any resolving
+     *     target on this field".
+     *   - `'none'`: `NOT` of the `'some'` form — no target matches. With no
+     *     nested filters: "has no resolving targets at all".
+     *   - `'every'`: `NOT EXISTS (… AND NOT (nested…))` — no target *fails*
+     *     the nested predicate. Vacuously true for documents with no
+     *     resolving targets (Prisma-style). With no nested filters there is
+     *     nothing to fail: compile to TRUE.
+     *
+     * Rows whose target doesn't resolve in the selected view (deleted, or
+     * unpublished in published mode) drop out of the JOIN in all three
+     * forms — the same visibility rule populate applies.
      */
     private buildRelationExists;
     /**

package/dist/modules/storage/storage-queries.js

@@ -105,7 +105,7 @@ export class DocumentQueries {
      * document, or any document read after the global default is switched, falls
      * back to the locale it was actually authored in) — otherwise the configured
      * global default, which is correct for not-yet-anchored rows and for
-     * row-less lookups (findByPath). See docs/I18N.md.
+     * row-less lookups (findByPath). See docs/07-internationalization/index.md.
      */
     buildLocaleChain(requestedLocale, sourceLocale) {
         const floor = sourceLocale ?? this.defaultContentLocale;
@@ -177,7 +177,7 @@ export class DocumentQueries {
      * `availableLocales` — the deliberate
      * counterpart to the version-grain `_availableVersionLocales` ledger fact;
      * the public advertised set is their intersection. One indexed query per
-     * call. See docs/I18N.md.
+     * call. See docs/07-internationalization/index.md.
      */
     async getAdvertisedLocalesByDocument(documentIds) {
         const result = new Map();
@@ -1440,10 +1440,26 @@ export class DocumentQueries {
      * the outer read is in published mode), then recurses each nested
      * filter against the target version's own `td.id`.
      *
-     * With no nested filters this reduces to "source has any relation row
-     * at all on this field pointing at a target that resolves in the
-     * selected view" — useful as a base case but more typically the
-     * nested list carries a predicate.
+     * `hasMany` relations store one row per item at an indexed field name
+     * (`<field>.0`, `<field>.1`, …), so the field match switches to a prefix
+     * `LIKE`; single relations match the exact name.
+     *
+     * The `quantifier` selects the set semantics over the relation's
+     * (resolving) targets:
+     *
+     *   - `'some'` (default): `EXISTS (… AND nested…)` — at least one target
+     *     matches. With no nested filters this reduces to "has any resolving
+     *     target on this field".
+     *   - `'none'`: `NOT` of the `'some'` form — no target matches. With no
+     *     nested filters: "has no resolving targets at all".
+     *   - `'every'`: `NOT EXISTS (… AND NOT (nested…))` — no target *fails*
+     *     the nested predicate. Vacuously true for documents with no
+     *     resolving targets (Prisma-style). With no nested filters there is
+     *     nothing to fail: compile to TRUE.
+     *
+     * Rows whose target doesn't resolve in the selected view (deleted, or
+     * unpublished in published mode) drop out of the JOIN in all three
+     * forms — the same visibility rule populate applies.
      */
     buildRelationExists(filter, locale, outerScope, readMode, depth) {
         const targetView = readMode === 'published'
@@ -1464,17 +1480,40 @@ export class DocumentQueries {
             path: this.pathProjection(sql.raw(`td${depth}.document_id`), locale, sql.raw(`td${depth}.source_locale`)),
         };
         const nestedConditions = filter.nested.map((nested) => this.buildFilterExists(nested, locale, innerScope, readMode, depth + 1));
-        const nestedAnd = nestedConditions.length > 0 ? sql ` AND ${sql.join(nestedConditions, sql ` AND `)}` : sql ``;
-        return sql `EXISTS (
+        const quantifier = filter.quantifier ?? 'some';
+        // `every` with nothing to fail is vacuously true for every document —
+        // short-circuit rather than emitting `NOT (TRUE)` noise.
+        if (quantifier === 'every' && nestedConditions.length === 0) {
+            return sql `TRUE`;
+        }
+        // 'some'/'none' assert the nested conjunction on a matching row;
+        // 'every' asserts the *negated* conjunction (a failing row) and wraps
+        // the whole scan in NOT.
+        const nestedAnd = nestedConditions.length === 0
+            ? sql ``
+            : quantifier === 'every'
+                ? sql ` AND NOT (${sql.join(nestedConditions, sql ` AND `)})`
+                : sql ` AND ${sql.join(nestedConditions, sql ` AND `)}`;
+        // hasMany rows are stored at indexed paths (`gallery.0`, `gallery.1`, …)
+        // where `field_name` is the *index segment* ('0', '1', …) and
+        // `parent_path` is the field name — so multi-target rows match on
+        // `parent_path` exactly, single-target rows on `field_name`. (A where
+        // clause only addresses top-level fields, so `parent_path` needs no
+        // prefix handling.)
+        const fieldMatch = filter.hasMany
+            ? sql `${rAlias}.parent_path = ${filter.fieldName}`
+            : sql `${rAlias}.field_name = ${filter.fieldName}`;
+        const existsSql = sql `EXISTS (
       SELECT 1 FROM byline_store_relation ${rAlias}
       JOIN ${targetView} ${tdAlias}
         ON ${tdAlias}.document_id = ${rAlias}.target_document_id
        AND ${tdAlias}.collection_id = ${rAlias}.target_collection_id
       WHERE ${rAlias}.document_version_id = ${outerScope.docVersionId}
-        AND ${rAlias}.field_name = ${filter.fieldName}
+        AND ${fieldMatch}
         AND ${rAlias}.target_collection_id = ${filter.targetCollectionId}
         AND (${rAlias}.locale = ${locale} OR ${rAlias}.locale = 'all')${nestedAnd}
     )`;
+        return quantifier === 'some' ? existsSql : sql `NOT ${existsSql}`;
     }
     /**
      * Build a comparison condition for a filter operator.

package/dist/modules/storage/tests/storage-transactions.test.js

@@ -7,7 +7,7 @@
  */
 /**
  * Integration tests for request-scoped transaction propagation
- * (`withTransaction` / DBManager / TXManager — see docs/TRANSACTIONS.md).
+ * (`withTransaction` / DBManager / TXManager — see docs/03-architecture/03-transactions.md).
  *
  * Proves the load-bearing guarantee the audit log depends on: multiple
  * `commands.*` calls wrapped in one `withTransaction` commit or roll back

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.15.1",
+  "version": "3.16.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -56,10 +56,9 @@
     "npm-run-all": "^4.1.5",
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
-    "zod": "^4.4.3",
-    "@byline/admin": "3.15.1",
-    "@byline/core": "3.15.1",
-    "@byline/auth": "3.15.1"
+    "@byline/admin": "3.16.0",
+    "@byline/auth": "3.16.0",
+    "@byline/core": "3.16.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",