json-rest-api 2.4.0 → 3.0.0

package/README.md

@@ -73,8 +73,13 @@ app.listen(3000, () => {
 
 ## Documentation
 
-The [API migration guide](docs/GUIDE/33-migrating-to-v2.md) describes the breaking
-v2 API changes and the steps for upgrading applications.
+Version 3 adds many-row writes (`postMany`, `patchMany`, `patchWhereIds`,
+`patchWhere`, `deleteMany`, `deleteWhere`), scoped reads (`scopedQuery`,
+`queryAll`), row locks (`lockByIds`, `lockWhere`, `claim`), lock versions, shared
+rows and system contexts, and replaces the 2.x bulk methods. The
+[v3 migration guide](docs/GUIDE/35-migrating-to-v3.md) lists the breaking changes
+with old → new tables; the [v2 migration guide](docs/GUIDE/33-migrating-to-v2.md)
+covers upgrades from 1.x.
 
 
 - [Quick Start](docs/QUICKSTART.md) - Quick start

package/docs/API.md

@@ -8,7 +8,8 @@ This reference provides comprehensive documentation for all methods, parameters,
 
 ## Current contract
 
-This reference describes the v2 API. See the [migration guide](GUIDE/33-migrating-to-v2.md) and
+This reference describes the v3 API. See the migration guides
+([to v2](GUIDE/33-migrating-to-v2.md), [to v3](GUIDE/35-migrating-to-v3.md)) and
 [backend limits](GUIDE/30-backend-capabilities.md) before upgrading.
 
 Pass method controls in the first `params` object and application information in
@@ -60,8 +61,10 @@ compound writes and JSON:API extensions are not enabled by accepting a document.
 On a resource configured with `versionField`, PUT/PATCH/DELETE and relationship
 writes accept an `expectedVersion` string; unconditional writes may omit it.
 POST does not accept that condition. See [optimistic concurrency](GUIDE/33-migrating-to-v2.md)
-for version-field configuration, bulk version arrays and the separate opt-in
-HTTP validator contract.
+for version-field configuration and the separate opt-in HTTP validator
+contract. Many-row writes refuse versioned resources; a
+[`lockVersionField`](GUIDE/34-scoped-reads-and-locks.md#lock-versions) with
+`onlyIf` gives them compare-and-set instead.
 
 Read calls can borrow raw Knex transactions. Library writes must use the handle
 from `api.transaction` when grouping operations; they reject unmanaged raw
@@ -79,25 +82,31 @@ a separate context for each enlisted operation. See [transaction support](#trans
    - [PATCH - Update Resource](#patch---update-resource)
    - [DELETE - Remove Resource](#delete---remove-resource)
    - [AGGREGATE - Grouped Totals](#aggregate---grouped-totals)
-3. [Relationship Methods](#relationship-methods)
+3. [Data-Access Methods](#data-access-methods)
+   - [scopedQuery - Scoped Read-Only Builder](#scopedquery---scoped-read-only-builder)
+   - [queryAll - Every Matching Record](#queryall---every-matching-record)
+   - [Many-Row Writes](#many-row-writes)
+   - [lockByIds, lockWhere and claim - Row Locks](#lockbyids-lockwhere-and-claim---row-locks)
+   - [System Contexts](#system-contexts)
+4. [Relationship Methods](#relationship-methods)
    - [getRelated - Retrieve Related Resources](#getrelated---retrieve-related-resources)
    - [getRelationship - Retrieve Relationship Identifiers](#getrelationship---retrieve-relationship-identifiers)
    - [postRelationship - Add to Relationship](#postrelationship---add-to-relationship)
    - [patchRelationship - Replace Relationship](#patchrelationship---replace-relationship)
    - [deleteRelationship - Remove from Relationship](#deleterelationship---remove-from-relationships)
-4. [Hook System](#hook-system)
+5. [Hook System](#hook-system)
    - [Complete Hook Execution Order](#complete-hook-execution-order)
    - [Hook Context Objects](#hook-context-objects)
-5. [Query Features](#query-features)
+6. [Query Features](#query-features)
    - [Filtering](#filtering)
    - [Sorting](#sorting)
    - [Pagination](#pagination)
    - [Sparse Fieldsets](#sparse-fieldsets)
    - [Including Related Resources](#including-related-resources)
-6. [Configuration Options](#configuration-options)
-7. [Schema Configuration](#schema-configuration)
-8. [Error Handling](#error-handling)
-9. [Advanced Features](#advanced-features)
+7. [Configuration Options](#configuration-options)
+8. [Schema Configuration](#schema-configuration)
+9. [Error Handling](#error-handling)
+10. [Advanced Features](#advanced-features)
 
 ---
 
@@ -1154,8 +1163,8 @@ await api.resources.sales.aggregate(params, context)
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `groupBy` | string[] | Fields to group by. Omit for one row over all selected records. |
-| `measures` | object | Output names mapped to `{ count \| countDistinct \| sum \| avg \| min \| max: field }`. Only `count` accepts `'*'`. |
+| `groupBy` | (string \| object)[] | Fields to group by, or date buckets `{ field, bucket, timezone, as }`. Omit for one row over all selected records. |
+| `measures` | object | Output names mapped to `{ count \| countDistinct \| sum \| avg \| min \| max: field, where? }`. Only `count` accepts `'*'`. |
 | `queryParams.filters` | object | Search schema filters, validated as for `query`. |
 | `queryParams.sort` | string[] | Grouped field or measure names, `-` for descending. Grouped fields break ties. |
 | `queryParams.page` | object | `size` and `number`, for grouped results only. `size` defaults to `queryDefaultLimit` and cannot exceed `queryMaxLimit`. |
@@ -1165,7 +1174,56 @@ await api.resources.sales.aggregate(params, context)
 times. Grouping and counting accept any scalar stored field, including belongs-to
 foreign keys. Fields that are `hidden`, virtual, computed, or that have a getter or
 `storage.serialize` are rejected, because SQL would group or sum values other than
-the ones clients read. `normallyHidden` fields are allowed.
+the ones clients read. The exception is a `date` or `dateTime` field with
+`storage.serialize`: it may be bucketed and take `min` and `max`, whose results
+are read back as that field's values. `normallyHidden` fields are allowed.
+In a [system context](GUIDE/34-scoped-reads-and-locks.md#system-contexts), a
+hidden ownership (autofilter) field may also be grouped and take
+`countDistinct`, so a job can find which owners have rows; other callers are
+refused it, since one whose optional owner filter does not resolve would see
+every owner.
+
+#### Conditional measures
+
+A measure's `where` limits the rows it counts or adds up, so one call can
+return "this week" next to "this month". Every entry must hold:
+
+```javascript
+measures: {
+  open: { count: '*', where: { status: 'open' } },
+  bigOpen: { sum: 'amount', where: { status: 'open', amount: { gte: 1000 } } },
+  late: { count: '*', where: { status: ['overdue', 'disputed'] } },
+  unassigned: { count: '*', where: { owner_id: null } }
+}
+```
+
+A condition is a value, an array (IN), `null`, or an object of `eq`, `ne`,
+`gt`, `gte`, `lt`, `lte`, `in` and `notIn`. Fields may be any stored scalar field
+aggregates accept; values are translated as filter values are. The SQL is
+`fn(CASE WHEN … THEN value END)`, so conditional and plain measures share one
+statement.
+
+#### Date buckets
+
+A `groupBy` entry `{ field, bucket, timezone, as }` groups a `date` or
+`dateTime` field by `'day'`, `'week'`, `'month'` or `'year'`. The group value
+is the `'YYYY-MM-DD'` of the bucket's first day; weeks start on Monday. The
+output name is `as`, default the field name.
+
+```javascript
+await api.resources.sales.aggregate({
+  groupBy: [{ field: 'closedAt', bucket: 'month', timezone: 'Europe/Rome', as: 'month' }],
+  measures: { total: { sum: 'amount' } },
+  queryParams: { sort: ['month'] }
+}, context)
+// { data: [{ month: '2026-01-01', total: 1250 }, ...] }
+```
+
+`timezone` is `'UTC'` (default), a fixed offset such as `'-09:00'`, or an IANA
+name. PostgreSQL has zone data; MySQL and MariaDB need their time zone tables
+loaded (checked once per name); SQLite takes offsets only. `date` fields have
+no time of day and take no time zone. Buckets need table storage; AnyAPI
+resources refuse them.
 
 #### Return Value
 
@@ -1201,6 +1259,145 @@ const totals = await api.resources.sales.aggregate({
 
 ---
 
+## Data-Access Methods
+
+Methods for work that does not fit one page or one record: reports, imports and
+jobs. They keep the caller's ownership filters (autofilter) and row policies.
+The guides have the details:
+[many-row writes](GUIDE/27-many-row-writes.md) and
+[scoped reads, locks and system work](GUIDE/34-scoped-reads-and-locks.md).
+Many-row writes and locks need table storage (`RestApiKnexPlugin`); AnyAPI
+resources refuse them with `RestApiBulkWriteUnsupportedError`. `queryAll` and
+`scopedQuery` work on both storages; on AnyAPI the scoped builder reads the
+canonical rows, whose fields live in storage slots.
+
+### scopedQuery - Scoped Read-Only Builder
+
+```javascript
+const { query } = await api.resources.entries.scopedQuery(
+  { filters, alias, purpose, transaction }, context)
+```
+
+Resolves to `{ query }`, a Knex builder over a derived table of the resource's
+rows with ownership filters, row policy and the search `filters` applied, so
+conditions the caller adds (`orWhere` included) only narrow them. It is wrapped
+because a builder is thenable. `purpose` is `'report'` (default; includes
+shared rows), `'bulk-write'`, `'lock'` or `'claim'`; row policies receive it as
+`queryPurpose`. The caller needs `query` permission. The builder refuses
+writes, locking reads, table changes, clearing predicates, set operations,
+common table expressions and access to its Knex client, on clones too
+(`RestApiScopedQueryReadOnlyError`); joined tables are not scoped. It guards
+against mistakes, not hostile code.
+
+### queryAll - Every Matching Record
+
+```javascript
+const { data, included } = await api.resources.entries.queryAll(
+  { queryParams, pageSize, rowLimit, format, transaction }, context)
+```
+
+Reads every record `query` would select, in cursor pages of `pageSize` rows
+(default 1,000) in id order or `queryParams.sort`. `queryParams` takes
+`filters`, `sort`, `fields` and `include`, but not `page`. Past `rowLimit` rows
+it throws `RestApiRowLimitError`. Works on both storages.
+
+### Many-Row Writes
+
+```javascript
+await resource.postMany({ data | document, onConflict, returning, format, queryParams, chunkSize, transaction }, context)
+await resource.patchMany({ data | document, onlyIf, missing, returning, format, queryParams, chunkSize, transaction }, context)
+await resource.patchWhereIds({ ids, data | document, onlyIf, missing, returning, format, queryParams, chunkSize, transaction }, context)
+await resource.patchWhere({ filters | all: true, data | document, onlyIf, returning, format, queryParams, chunkSize, transaction }, context)
+await resource.deleteMany({ ids, missing, returning, chunkSize, transaction }, context)
+await resource.deleteWhere({ filters | all: true, returning, chunkSize, transaction }, context)
+```
+
+| Parameter | Description |
+| --- | --- |
+| `data` / `document` | `postMany`, `patchMany`: an array of plain records, or `{ data: [resource objects] }`; `patchMany` rows carry `id`. `patchWhereIds`, `patchWhere`: one record of changes. |
+| `ids` / `filters` / `all` | The records to change: listed ids, or non-empty search filters validated as `query` validates them, or `all: true` for every row the caller can see. |
+| `returning` | `'none'` (default), `'minimal'` (`{ data: [{ type, id }] }`), `'full'` (`{ data: [records] }`, not for deletes) or `'count'` (`{ meta: { count } }`, the number of rows written, with no row data). |
+| `format`, `queryParams` | Output format, `fields` and `include` of full records. |
+| `onConflict` | Upsert: `{ keys, action: 'ignore' \| 'merge', merge? }`. `keys` must include every ownership field, and a unique index must cover them; rows may not carry an `id` or repeat keys. On a resource with no ownership fields and no row policy, `keys: ['id']` (or the `idProperty`) keys the upsert on the id, and every row carries one; keys compare exactly (a match only by collation fails with 409); only a match on the keys counts, and a clash on another unique index fails the batch. `merge` updates only the fields each row supplies (never `defaultTo` values), runs the patch checks (`checkPermissions` with `method: 'patch'`) on the records it updates and is refused under a row policy. |
+| `onlyIf` | Compare-and-set: only rows whose stored values equal these change and are returned. |
+| `missing` | Id lists only: `'throw'` (default; `RestApiRecordsNotFoundError`, 404) or `'skip'` for ids the caller cannot see. `patchWhere` and `deleteWhere` refuse it: they write the rows their selection finds, with the scope and filters inside each write, and return only the rows written. |
+| `chunkSize` | Rows per statement (default 500), lowered to the database's parameter limit. |
+| `transaction` | A transaction from `api.transaction` to join; otherwise the call owns one. |
+
+Each call is all-or-nothing. Every row is validated, stamped, passed through
+setters and authorized with `checkPermissions` (`method` `post`, `patch` or
+`delete`, `originalContext.bulkIndex` the row's position); belongs-to targets
+are checked with one read per related type; then one statement runs per chunk.
+Patches refuse the id, ownership fields (also through a polymorphic
+relationship) and the `lockVersionField`, and accept real `knex.raw()` values
+for stored, non-relationship fields. The UPDATE, DELETE and lock statements
+repeat the caller's ownership conditions, so a row that moved to another owner
+after the visibility read is left alone and counts as missing. Deletes remove
+the records' pivot rows. Batch hooks run once per call:
+`beforeProcessingPostMany`, `beforeDataCallPostMany`, `afterDataCallPostMany`,
+the `PatchMany` trio and `beforeDataCallDeleteMany` / `afterDataCallDeleteMany`.
+
+`RestApiBulkWriteUnsupportedError` (422) is thrown before writing for AnyAPI
+storage, versioned resources (and those whose writes advance a version),
+per-record write hooks not registered with `{ batch: true }`, rows that set
+many-to-many or reverse relationships, file fields, or positions.
+`BulkOperationsPlugin` exposes `postMany`, `patchMany` and `deleteMany` as
+`POST`, `PATCH` and `DELETE /RESOURCE/bulk`.
+
+### lockByIds, lockWhere and claim - Row Locks
+
+```javascript
+await api.transaction(async transaction => {
+  const { data: locked } = await resource.lockByIds({ ids, transaction, missing, format, queryParams: { fields } }, context)
+  const { data: matching } = await resource.lockWhere({ filters, transaction, format, queryParams: { fields } }, context)
+  const { data: taken } = await resource.claim({ filters, sort, limit, transaction, format, queryParams: { fields } }, context)
+})
+```
+
+All three need a transaction (`RestApiLockOutsideTransactionError` otherwise)
+and return the records as the locking read saw them, through the read hooks of
+`query` (`enrichRecord`, `finish`, `finishQuery`) and `checkDataPermissions`
+for each row. The locking read is the first statement and applies the scope
+itself, so plain reads later in the transaction see what a previous lock holder
+committed. `lockByIds` locks the visible rows among `ids` in id order
+(`FOR UPDATE`), sorting lists longer than its 1,000-id statements first; hidden
+or missing ids throw `RestApiRecordsNotFoundError` unless `missing: 'skip'`. On
+MySQL and MariaDB it locks every listed id, hidden ones too, until commit, so
+pass ids from a scoped read, never a raw request list. `lockWhere` locks the
+visible rows the filters select in id order, waiting for other transactions and
+including rows that start to match meanwhile; more than 1,000 throw
+`RestApiRowLimitError`. On MySQL and MariaDB it has no `ORDER BY` and forces an
+index that starts with the whole ownership columns (or, without ownership
+conditions, a filtered column), and throws `RestApiBulkWriteUnsupportedError`
+when the table has none.
+`claim` takes up to `limit` (default 1, at most 1,000) matching rows that no
+other transaction holds (`SKIP LOCKED`), in `sort` order (stored fields, default
+`['id']`). A row policy that joins tables is refused for all three. On SQLite,
+which has one writer, they take the database's write lock with a write that
+changes nothing, then read.
+
+A resource option `lockVersionField: 'lock_version'` names a stored integer
+that every update (single, many-row and upsert merge) sets to `column + 1`.
+Callers cannot set it; use it with `onlyIf`.
+
+### System Contexts
+
+```javascript
+import { createSystemContext, isSystemContext, readOnlyQueryBuilder } from 'json-rest-api'
+
+const context = createSystemContext('nightly report', { jobId })
+```
+
+A system context skips autofilter ownership predicates; creates must set every
+ownership field explicitly. Row policies receive `system: true`. The marker is
+a private symbol that object spread keeps and serialization drops; a context
+with `system: true` but no marker throws `REST_API_SYSTEM_CONTEXT_FORGED`.
+Autofilter filters may be `shared: true` (on a nullable field): reads include
+rows whose field is NULL, while many-row writes, locks and single writes stay
+on the owner's rows.
+
+---
+
 ## Relationship Methods
 
 ### getRelated - Retrieve Related Resources
@@ -1820,8 +2017,9 @@ const result = await api.resources.articles.query({
 ```
 
 Pagination metadata is under `meta.pagination`. With counts disabled, it includes
-`page` and `pageSize`, without
-promising totals or `hasMore`. The library supplies pagination links appropriate
+`page`, `pageSize` and `hasMore`, without totals: the page reads one extra row
+instead of running a count query, so it is one statement and links to `first`,
+`prev` and `next` but not `last`. The library supplies pagination links appropriate
 to the available count/boundary information.
 
 #### Cursor Pagination
@@ -1939,6 +2137,27 @@ purpose. See [row policies](GUIDE/17-row-policies.md),
 [include configuration](GUIDE/33-migrating-to-v2.md#include-configuration-is-validated-before-publication)
 and the query hook contract above.
 
+#### Per-Parent Limits (Window Includes)
+
+A to-many relationship can include only the first few related records of each
+parent, such as the newest snapshot per booking. Configure it on the
+relationship, not in the query:
+
+```javascript
+relationships: {
+  snapshots: {
+    type: 'hasMany', target: 'snapshots', foreignKey: 'booking_id',
+    include: { strategy: 'window', limit: 1, orderBy: ['-revision'] }
+  }
+}
+```
+
+`include: ['snapshots']` then returns at most `limit` visible snapshots per
+booking, ordered by `orderBy`, in one query. The default (`standard`) strategy
+applies one limit to the whole included set instead. Window includes need
+database window functions (`api.knex.capabilities.windowFunctions`). See
+[window includes](GUIDE/34-scoped-reads-and-locks.md#window-includes).
+
 ## Configuration Options
 
 ### Plugin Configuration
@@ -2175,8 +2394,22 @@ For example, a resource not-found error maps to:
 | `REST_API_FIELDSET_INVALID`, `REST_API_INCLUDE_INVALID` | 400 |
 | `REST_API_VERSION_CONFLICT` | 409 |
 | `REST_API_PRECONDITION_FAILED` | 412 |
+| `RestApiRecordsNotFoundError` (subtype `not_found`) | 404 |
+| `RestApiBulkWriteUnsupportedError` / `REST_API_BULK_WRITE_UNSUPPORTED` | 422 |
+| `RestApiLockOutsideTransactionError` (a validation error) | 422 |
+| `RestApiBulkInsertIdsError` / `REST_API_BULK_INSERT_IDS` | 500 |
+| `RestApiScopedQueryReadOnlyError` / `REST_API_SCOPED_QUERY_READ_ONLY` | programmatic only |
+| `RestApiRowLimitError` / `REST_API_ROW_LIMIT` | 500 |
+| `REST_API_SYSTEM_CONTEXT_FORGED` | 500 |
 | Unexpected or temporal output failure | 500 |
 
+A 500 answer carries the error's message only for the library's own
+`RestApi…Error` classes. Any other error, a database error or a plain `Error`
+thrown by a hook, answers with the detail `An unexpected error occurred`: a
+database error's message repeats the SQL and its values. The connector's
+`HTTP request error` or `Fastify request error` log entry records only the
+`name` and `code` of a database error.
+
 Validation violations produce individual HTTP errors with their message and
 field location; generic validation errors retain their available details.
 Relationship validation/access failures follow their actual typed classification,
@@ -2197,15 +2430,14 @@ before owned commit; borrowed transactions remain the owner's responsibility.
 See the [callback migration guide](GUIDE/33-migrating-to-v2.md#setter-getter-and-computed-field-failures)
 for examples and intentional fallback handling.
 
-Resource, relationship, bulk and canonical registry write failures use the root
+Resource, relationship, many-row and canonical registry write failures use the root
 export `RestApiWriteError`. Its immutable `transactionOutcome` is `none`,
 `pending`, `committed`, `rolledBack` or `unknown`. Its `cause` preserves the
 original thrown value, including frozen errors, while classification fields
 such as `code`, `subtype` and `details` remain directly readable. Read errors
 retain their existing contract.
 
-HTTP JSON:API write errors include `meta.transactionOutcome`; non-atomic bulk
-entries include `error.transactionOutcome`. A failed call can represent a
+HTTP JSON:API write errors include `meta.transactionOutcome`. A failed call can represent a
 committed write when a later hook rejects. Retrying that call can duplicate its
 effects; neither an HTTP status nor an unknown outcome authorizes automatic
 replay. See the [transaction migration guide](GUIDE/33-migrating-to-v2.md#transactions-and-errors)
@@ -2346,44 +2578,20 @@ For full examples and dialect notes, see [Knex Schema and Migrations](GUIDE/21-s
 
 ### Batch Operations
 
-Process multiple operations efficiently:
-
-```javascript
-// Batch create with transaction
-const createArticles = async (articlesData) => {
-  return api.transaction(async transaction => {
-    const results = [];
-    for (const data of articlesData) {
-      const result = await api.resources.articles.post({
-        data,
-        transaction,
-        format: 'plain',
-        returning: 'minimal'
-      });
-      results.push(result);
-    }
-    
-    return results;
-  });
-};
-
-// Batch update
-const updateArticles = async (updates) => {
-  return api.transaction(async transaction => {
-    for (const { id, data } of updates) {
-      await api.resources.articles.patch({
-        id,
-        data,
-        transaction,
-        format: 'plain',
-        returning: 'none'
-      });
-    }
-    
-  });
-};
+Write many records with the [many-row methods](#many-row-writes): one statement
+per chunk, all-or-nothing, with the same validation and permissions as single
+writes. Group them with other calls in `api.transaction`:
+
+```javascript
+await api.transaction(async transaction => {
+  await api.resources.articles.postMany({ data: articlesData, transaction })
+  await api.resources.articles.patchWhereIds({ ids: staleIds, data: { status: 'archived' }, transaction })
+})
 ```
 
+When each record needs its own hooks (or the resource refuses many-row writes),
+call the single-record methods in a loop inside one `api.transaction`.
+
 ### Computed Fields
 
 Declare computed fields in `schema`, with `computed: true`, `dependencies` and

package/docs/GUIDE/01-getting-started.md

@@ -12,7 +12,7 @@ related resources. The [quickstart](../QUICKSTART.md) provides a complete
 Express server with related publishers and authors.
 
 Use Node 24 or newer; development verification runs on Node 24. These examples
-use the revised contract in the [migration guide](33-migrating-to-v2.md). Until
+use the v3 contract; see the [migration guide](35-migrating-to-v3.md). Until
 its release is published, install the intended library tarball instead of the
 registry package.
 

package/docs/GUIDE/07-polymorphic-relationships.md

@@ -98,8 +98,10 @@ const authorReviewDocument = await api.resources.reviews.post({
 
 Plain polymorphic input uses `{ _type, id }` under the relationship alias.
 JSON:API uses `{ type, id }` under `data.relationships.reviewable.data`.
-Do not write `reviewable_type` or `reviewable_id` as public attributes. Those
-logical fields describe storage; the public relationship represents them together.
+Writes refuse `reviewable_type` and `reviewable_id` in attributes (rule
+`foreign_key_in_attributes`), as they refuse a belongs-to foreign key: those
+logical fields describe storage, and the public relationship sets them together,
+after checking that the caller can see the target.
 Plain output uses `_type` to identify the related resource type as well.
 
 ## Include either direction

package/docs/GUIDE/09-pagination-and-sorting.md

@@ -65,8 +65,10 @@ enabled, metadata is:
 ```
 
 Page 10 returns an empty array. `enablePaginationCounts: false` suppresses the
-count query and count-derived metadata; do not assume every collection response
-contains totals. Every mode respects `queryMaxLimit`.
+count query and count-derived metadata (`total`, `pageCount` and the `last`
+link); do not assume every collection response contains totals. The page then
+reads one extra row, so `hasMore` and the `next` link remain, and a numbered
+page costs one statement. Every mode respects `queryMaxLimit`.
 
 Server code that reads every row, for example an export or a nightly job, can
 raise the cap for one call with `pageSizeLimit`, a parameter beside

package/docs/GUIDE/13-hooks-and-lifecycle.md

@@ -342,7 +342,7 @@ Built-in nested operations use separate context objects with shallow inheritance
 | --- | --- | --- |
 | Full write-response GET | Application properties and referenced cache/auth objects; the active transaction is passed explicitly. Write input is available for virtual-field response enrichment. | GET sets its own method, ID, schema, query selection and read result. Replacing a child top-level property does not replace the parent's property. |
 | Relationship PATCH and reverse relationship child writes | Application properties and referenced objects; the active transaction is passed explicitly. | Child writes set their own method, input, schema and stored records. The parent retains its own operation identity and finish context. |
-| Bulk children | Application properties and referenced objects; atomic children share the batch transaction. | Each child has its own context with `bulkOperation` and `bulkIndex`. Child cleanup diagnostics are collected by the batch. |
+| Many-row writes | One context for the whole call, with `inputRecords` and `ids`. | Each row's permission check gets its own wrapper, with the row's position in `originalContext.bulkIndex`. |
 | Ordinary CRUD permission checks and attribute enrichment | A reference to the relevant operation through `originalContext` or `parentContext`. | A fresh wrapper for that permission/enrichment call. Adding a wrapper property does not add it to the originating context. Relationship permission hooks instead receive the relationship operation context directly. |
 | Included-resource and relationship visibility queries | Application context and the active connection/transaction. | The library sets the target resource/schema and query selection; parent filters are not blindly applied as target filters. |
 
@@ -393,7 +393,12 @@ a handler to these resource write stages.
 ## Read order and output enrichment
 
 GET authorizes through `checkPermissions`, then runs `beforeData` and
-`beforeDataGet`. After fetching, it runs `checkDataPermissions`,
+`beforeDataGet`. These see `context.minimalRecord`, the stored row read before
+the full read. A resource with none of these three hooks and no
+`checkDataPermissions` or `checkDataPermissionsGet` hook (registered for it or
+globally) reads its row once, with its scope and row policy in that read, and
+leaves `minimalRecord` unset; a missing or hidden row is still `not_found`, and
+answers before an invalid fieldset does. After fetching, it runs `checkDataPermissions`,
 `checkDataPermissionsGet` and `enrichRecord`. Field getters and computed output
 run during attribute enrichment, followed by `enrichAttributes`.
 `enrichRecordWithRelationships`, `finish` and `finishGet` follow. Final
@@ -412,7 +417,7 @@ undeclared output key does not establish a supported field or bypass final
 field filtering. Finish hooks are late observers; they are not a substitute
 for schema validation or query policy.
 
-## Relationship and bulk composition
+## Relationship and many-row composition
 
 Relationship POST and DELETE run `beforeDataCall`, followed by
 `beforeDataCallPostRelationship` or `beforeDataCallDeleteRelationship`, after
@@ -448,9 +453,32 @@ hooks. Reverse relationship mutations can run child PATCH lifecycles inside
 the parent's operation. Direct pivot/link changes do not synthesize
 pivot-resource hook calls.
 
-Bulk operations invoke child resource lifecycles. Atomic children share a
-transaction; non-atomic children complete separate transactions. Do not count
-hook invocations as independent user requests or assume one context per batch.
+Many-row writes (`postMany`, `patchMany`, `patchWhereIds`, `patchWhere`,
+`deleteMany`, `deleteWhere`) do not run the per-record write hooks. They run
+batch hooks once per call, with every row in `context.inputRecords` and the
+written ids in `context.ids`:
+
+| Method | Batch hooks |
+| --- | --- |
+| `postMany` | `beforeProcessingPostMany`, `beforeDataCallPostMany`, `afterDataCallPostMany` |
+| `patchMany`, `patchWhereIds`, `patchWhere` | `beforeProcessingPatchMany`, `beforeDataCallPatchMany`, `afterDataCallPatchMany` |
+| `deleteMany`, `deleteWhere` | `beforeDataCallDeleteMany`, `afterDataCallDeleteMany` |
+
+`checkPermissions`, `afterCommit` and `afterRollback` still run. A resource with
+a per-record write hook (`beforeProcessing*`, `beforeSchemaValidate*`,
+`afterSchemaValidate*`, `beforeDataCall*`, `afterDataCall*`, `finish*` for post,
+patch or delete) has its many-row writes refused, unless the hook was
+registered with `{ batch: true }`: a promise that a batch hook does its work, or
+that it does not apply to many-row writes.
+
+```js
+api.addHook('finishPost', 'notify-owner', { batch: true }, notifyOne)
+api.addHook('afterDataCallPostMany', 'notify-owners', {}, ({ context }) => notifyMany(context.ids))
+```
+
+Method and hook handlers receive `perRecordHooks(events, scope)`, which lists
+the `{ event, name }` of the handlers that would block a resource. See
+[many-row writes](27-many-row-writes.md#hooks-and-refusals).
 
 ## Completion and failure
 

package/docs/GUIDE/14-custom-resource-methods.md

@@ -108,8 +108,9 @@ The current implementation depends on more than individual CRUD helpers:
 - Writes need an actual transaction factory and the managed ownership contract,
   including acknowledged commit/rollback, uncertain completion, completion
   hooks and failure diagnostics. Remote side effects need their own semantics.
-- Bulk operations and schema changes must preserve their documented atomicity
-  and publication boundaries. Supporting a single-record happy path is not
+- Many-row writes and schema changes must preserve their documented atomicity
+  and publication boundaries. A backend without the many-row storage helpers
+  (`dataInsertMany` and the others) has its many-row writes refused. Supporting a single-record happy path is not
   sufficient evidence for the backend.
 
 The source checkout's `plugins/core/lib/storage/storage-types.d.ts` describes

package/docs/GUIDE/16-autofiltering.md

@@ -276,6 +276,58 @@ await api.addResource('system_settings', {
 
 If a resource has no `autofilter` setting, the plugin does nothing for that resource.
 
+## Shared Rows
+
+Reference data that every owner reads, such as default categories, can live in
+the same table as owned rows. Mark the filter `shared: true`; a NULL value in
+its field then marks a shared row. The field must be `nullable`.
+
+```js
+await api.use(AutoFilterPlugin, {
+  resolvers: { workspace: ({ context }) => context.session?.workspaceId },
+  presets: {
+    workspaceOrShared: { filters: [{ field: 'workspace_id', resolver: 'workspace', shared: true }] }
+  }
+})
+await api.addResource('categories', {
+  schema: {
+    name: { type: 'string', required: true },
+    workspace_id: { type: 'string', nullable: true }
+  },
+  autofilter: 'workspaceOrShared'
+})
+```
+
+- Reads (`query`, `get`, includes, `aggregate`, `scopedQuery`) see the owner's
+  rows and the shared rows.
+- Many-row writes, `lockByIds`, `lockWhere`, `claim` and `scopedQuery` with purpose
+  `'bulk-write'`, `'lock'` or `'claim'` see only the owner's rows.
+- Single `patch`, `put` and `delete` of a shared row fail as `forbidden`, and so
+  does a create whose owner value resolves to NULL.
+- Shared rows are created and changed with a system context (below).
+
+`shared` must be `true` or `false` (the default).
+
+## System Contexts
+
+Work that legitimately spans every owner, such as nightly reports or imports,
+uses a context from `createSystemContext(reason, values)`:
+
+```js
+import { createSystemContext } from 'json-rest-api'
+
+const context = createSystemContext('rebuild search index')
+const everyProject = await api.resources.projects.queryAll({}, context)
+await api.resources.categories.post({ data: { name: 'General', workspace_id: null } }, context)
+```
+
+For a system context the plugin applies no ownership filters, and creates
+must set every autofilter field explicitly (NULL creates a shared row on a
+`shared` filter; a missing value fails with `system_ownership_required`). The
+context carries a private marker that request input cannot produce. A context
+that sets `system: true` without it throws `REST_API_SYSTEM_CONTEXT_FORGED`.
+See [system contexts](34-scoped-reads-and-locks.md#system-contexts).
+
 ## Runtime Behavior
 
 ### Query Scoping
@@ -454,8 +506,8 @@ api.autofilter.getScopeConfig('projects')
 // {
 //   preset: 'workspace_user',
 //   filters: [
-//     { field: 'workspace_id', resolver: 'workspace', required: true },
-//     { field: 'user_id', resolver: 'user', required: true }
+//     { field: 'workspace_id', resolver: 'workspace', required: true, shared: false },
+//     { field: 'user_id', resolver: 'user', required: true, shared: false }
 //   ]
 // }
 ```