@jskit-ai/resource-runtime 0.2.12 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Depends on json-rest-api 3.1.0 exactly (from 3.0.1), from the registry with its published integrity: `lockMode: "noKeyUpdate"`, ON CONFLICT on the matching unique index's exact columns, the PostgreSQL merge race on an uncommitted insert, and the `xid8` field type the change horizon reads.
+- Tests pin three paths the guide now documents: a shared row of a `workspace_or_shared` table is written in the owner's root system context, naming `workspaceId: null`, also inside a request's transaction, and never from a request or a derived job context (`forUser` is refused 403); a job's `actorId` never moves its scope, while a row policy may hold a job done for a person to that person's rows; and a hand route's `request.callOptions()` scopes user, workspace and workspace_user tables as the same request's action does, with no user scope when no one is signed in.
+- A table resource reads an xid8 change stamp through an `xid8` field, json-rest-api 3.1.0's type for PostgreSQL's transaction id: decimal text below 2^64, which filters such as `changedSince: { type: "xid8", actualField: "changed", filterOperator: ">=" }` compare as transaction ids in SQL. A malformed cursor is refused as `REST_API_VALIDATION` before any statement, where a string field sent it to PostgreSQL (22P02), and the field is refused at registration on MySQL, MariaDB and SQLite. With `changeHorizon()`, a read of what changed since goes through the handle, where it was a hand-written scoped query; the data-access guide's "What changed since" gives the migration (an xid8 column a trigger stamps on every insert and update), the field, the filters and the read.
+- Every handle has `changeHorizon(options)`: PostgreSQL's snapshot horizon, `pg_snapshot_xmin(pg_current_snapshot())`, as decimal text, read in the caller's transaction when there is one, with the call's context checked as for every call. Every transaction below it had finished when it was read, so a read of what changed starts there: a later read of the rows whose xid8 change stamp is at or above it finds what an open transaction wrote, a row whose id was taken before its transaction committed and a changed older row included, which "past the highest id seen" misses. It reads no row, where it was a hand-written `knex.raw` beside the handle. MySQL, MariaDB and SQLite stamp no row with its transaction: there it throws `UnsupportedDatabaseError` (code `RESOURCE_DATABASE_UNSUPPORTED`, exported from `./server`) before any statement. `changes.postgres.test.js` proves the catch-up with a writer still open at the horizon.
+- **Security.** A table resource with ownership `system` (rows of no workspace or user, such as an agent's runs or a server's leases) answers only a system context. Every call with a request's context, a job context derived with `forWorkspace`, `forUser` or `forWorkspaceUser`, or none throws `SystemContextRequiredError` (code `RESOURCE_SYSTEM_CONTEXT_REQUIRED`, exported from `./server`) before any statement: such a table has no ownership predicate, so that context reached every workspace's rows. The table gets no autofilter preset; the owner's own methods decide what a request may see.
+- `lock`, `lockMany`, `lockWhere`, `claim`, `lockOrCreate` and `patchWhere` take `lockMode: "update"` (the default, `FOR UPDATE`) or `"noKeyUpdate"`, passed on to json-rest-api: on PostgreSQL `FOR NO KEY UPDATE`, which still keeps every other lock and write of the row out but lets another transaction insert a row that references it; MySQL, MariaDB and SQLite lock as for `"update"`. Another value throws a TypeError naming the resource and the method before anything runs (`notes.lock() lockMode is "update" (the default) or "noKeyUpdate". Received: "share"`).
+- `./test` re-exports database-runtime's `createPackageTestKnex(t, { environment })`. The package's own data tests run on it, so a `DB_CLIENT=pg` run proves their paths on PostgreSQL, each test in a schema of its own; `locks.postgres.test.js` adds PostgreSQL's concurrent cases with real transactions: two `patchWhere` calls racing for one row, `deleteWhere` against `patchWhere`, a `patchWhere` that waited writing only rows that still match, two `claim` workers taking different rows, `lockMany` and `lockWhere` waiting for a holder, upserts of one key behind an uncommitted insert, a deadlock victim running again, `retryLostInsertRace`, `findOrCreate` and `lockOrCreate` first uses at once, and `lockMode: "noKeyUpdate"`. CI runs them, and the data tests of this package and crud-core, on PostgreSQL 17.
+- Tests pin how a whole number stored in a BIGINT column that is not an id (a counter, a read position) reads through a handle, on MariaDB/MySQL and PostgreSQL (`storedIntegers.mysql.test.js` and `storedIntegers.postgres.test.js`, the latter in CI's PostgreSQL job). Both drivers read BIGINT as text, and a field of type `integer` answers a number on create, get, query, queryAll, patch, createMany, patchMany, lockMany, claim, aggregate and a hidden-field read, while an id field answers text. Past 2^53 − 1 the digits stay text, never a rounded number, and a `scopedQuery` row is the driver's text. No behaviour changes.
+- `./server` exports `checkForeignKeys({ knex, resources, tables })`, which compares the table resources' declared `foreignKeys` (each field mapped to its column as json-rest-api stores it) with the keys the database holds: `missing` lists a declared key the database lacks, `undeclared` a key of one of `tables` that nothing declares. `jskit test --databases` runs it once per run on the prepared test database; it never runs at boot. A declared `foreignKeys` reaches the json-rest-api resource unchanged; json-rest-api 3.0.1 only keeps it for its table helpers.
+- **Security.** A handle answers `joinSource({ alias, filters }, options)`: `{ query, column }`, the caller's scoped rows under the alias (ownership, the row policy and the filters applied) with the stored columns a read answers, never a hidden one, and `column(field)`, which refuses a hidden field. `withoutHiddenFields` hands another feature no other query builder: a method answering one, at once or inside its answer, is refused outside a system context with a TypeError naming the method and pointing at `joinSource`. A join source an owner built on `scopedQuery()` selected every column, so `source.query.select(source.column("publicToken"))` read another feature's hidden values; such a source becomes the handle's `joinSource({ alias }, options)`.
+- **Security.** `withoutHiddenFields` refuses a call whose `fields`, in any record it takes (a list, names separated by commas or a sparse fieldset), names a hidden field of the tables its owner owns, whatever the method. Only the seven standard reads refused one: a method `decorateRepository` adds that forwards the caller's `fields` answered the field stripped, as undefined, which a caller used as a value (a token in an email link). A system context, or one it derived, counts in whichever record the call takes, where only the last one counted.
+- `withoutHiddenFields` refuses owned tables of which one hides a field and another shows a field of the same name, with a TypeError naming both, when the feature's repository is built: it strips hidden fields by name, so the visible field never reached another feature. Hide it in both, or rename one.
 - Runs on json-rest-api 3.0.1 (from 3.0.0), exactly. A handle's `createMany` with `onConflict: { action: "merge" }` inside a transaction that read before another transaction committed the same key no longer fails as forbidden ("the record these conflict keys match cannot be changed by the caller") on MySQL and MariaDB, so two first registrations of one email at once both land; and a merge whose late matched row it left unchanged answers that row instead of empty data. PostgreSQL and SQLite behave as before.
 - `expectScoped` compares the other owner's stored rows, every column read through the system context's scoped query, where it compared the records a handle answers. A path that changed only a hidden or `defaultExclude` field of another owner's row (a `patchWhere` under a system context with `returning: "none"`), or a column outside the table resource's schema, passed.
 - `@jskit-ai/database-runtime` is a required peer dependency at the same version, where it was a dependency: the application holds one copy of the table runtime, since a nested copy brings its own error classes and transactions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/resource-runtime",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "type": "module",
   "engines": {
     "node": ">=24.0.0"
@@ -15,9 +15,9 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/resource-core": "0.1.205",
-    "@jskit-ai/resource-crud-core": "0.1.205",
-    "json-rest-api": "3.0.1"
+    "@jskit-ai/resource-core": "0.1.206",
+    "@jskit-ai/resource-crud-core": "0.1.206",
+    "json-rest-api": "3.1.0"
   },
   "description": "The resource runtime: features own their tables through it and read and write them with scoped handles on json-rest-api.",
   "jskit": {
@@ -57,14 +57,14 @@
           },
           {
             "subpath": "./test",
-            "summary": "Data test helpers on a real test database: createTestResourceRuntime, startTestFeatures, expectScoped, expectFlatQueries, expectEveryTableOwned, requireTestDatabase and TestDatabaseMissingError."
+            "summary": "Data test helpers on a real test database: createTestResourceRuntime, startTestFeatures, expectScoped, expectFlatQueries, expectEveryTableOwned, createPackageTestKnex, requireTestDatabase and TestDatabaseMissingError."
           }
         ]
       }
     }
   },
   "peerDependencies": {
-    "@jskit-ai/database-runtime": "0.1.263",
-    "@jskit-ai/kernel": "0.2.14"
+    "@jskit-ai/database-runtime": "0.1.264",
+    "@jskit-ai/kernel": "0.2.15"
   }
 }

package/src/server/changeHorizon.js

@@ -0,0 +1,26 @@
+import { detectDialectFromClient } from "@jskit-ai/database-runtime/shared";
+import { UnsupportedDatabaseError } from "./errors.js";
+
+/**
+ * PostgreSQL's snapshot horizon, `pg_snapshot_xmin(pg_current_snapshot())`, as decimal text: every transaction below it
+ * had finished when it was read. A cursor of what changed starts there: taken before a read, a later read of the rows
+ * whose xid8 change stamp is at or above it finds every row a transaction that read could not see wrote, a row whose
+ * id was taken before its transaction committed and a changed older row included (see the data-access guide, "What
+ * changed since"). It reads no row. MySQL, MariaDB and SQLite have no transaction stamps: it throws
+ * UnsupportedDatabaseError there, before anything runs.
+ * @param {string} name The resource's name, for the message.
+ * @param {import("knex").Knex | import("knex").Knex.Transaction} db The caller's transaction, or the runtime's Knex.
+ * @returns {Promise<string>}
+ */
+async function readChangeHorizon(name, db) {
+  if (detectDialectFromClient(db) !== "postgres") {
+    throw new UnsupportedDatabaseError(
+      `${name}.changeHorizon()`,
+      "reads PostgreSQL's snapshot horizon (pg_snapshot_xmin), which MySQL, MariaDB and SQLite do not have."
+    );
+  }
+  const { rows: [{ horizon }] } = await db.raw("select pg_snapshot_xmin(pg_current_snapshot())::text as horizon");
+  return horizon;
+}
+
+export { readChangeHorizon };

package/src/server/errors.js

@@ -23,6 +23,40 @@ class MissingScopeError extends TypeError {
   }
 }
 
+/**
+ * A handle call on a `system` table in a context that is not a system context: its rows belong to no workspace or user,
+ * so a request's context, or one derived for a workspace or a user, would reach every workspace's rows. Nothing runs.
+ */
+class SystemContextRequiredError extends TypeError {
+  /** @param {string} resourceName */
+  constructor(resourceName) {
+    super(
+      `${resourceName} rows belong to no workspace or user (ownership "system"), so only a system context reaches them: ` +
+        "the background work of the feature that owns the table, with systemContext(reason). A request's context, or one " +
+        "forWorkspace, forUser or forWorkspaceUser derived, would reach every workspace's rows. Call the owner's own methods, " +
+        "which run in its system context."
+    );
+    this.name = "SystemContextRequiredError";
+    this.code = "RESOURCE_SYSTEM_CONTEXT_REQUIRED";
+  }
+}
+
+/**
+ * A handle call that reads something only some databases have, on one that lacks it, such as changeHorizon() outside
+ * PostgreSQL. Nothing runs.
+ */
+class UnsupportedDatabaseError extends Error {
+  /**
+   * @param {string} call The call, as `notes.changeHorizon()`.
+   * @param {string} reason What the call reads and which databases have it.
+   */
+  constructor(call, reason) {
+    super(`${call} ${reason}`);
+    this.name = "UnsupportedDatabaseError";
+    this.code = "RESOURCE_DATABASE_UNSUPPORTED";
+  }
+}
+
 /** query() without page.size: every list is paged, and every-row reads say so with queryAll(). */
 class UnpagedQueryError extends TypeError {
   /** @param {string} resourceName */
@@ -91,4 +125,13 @@ class DuplicateOwnerError extends Error {
   }
 }
 
-export { DuplicateOwnerError, MissingScopeError, PageSizeError, RowLimitError, StaleRecordError, UnpagedQueryError };
+export {
+  DuplicateOwnerError,
+  MissingScopeError,
+  PageSizeError,
+  RowLimitError,
+  StaleRecordError,
+  SystemContextRequiredError,
+  UnpagedQueryError,
+  UnsupportedDatabaseError
+};

package/src/server/foreignKeyCheck.js

@@ -0,0 +1,58 @@
+import { listForeignKeys } from "@jskit-ai/database-runtime/server/foreignKeyMigrations";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { createResourceHost } from "./resourceHost.js";
+import { createResourceRuntime } from "./resourceRuntime.js";
+
+/** @typedef {{ tableName: string, columns: string[], referencedTableName: string, referencedColumns: string[] }} ForeignKeyColumns */
+
+const sameNames = (left, right) => left.length === right.length && left.every((name, index) => name === right[index]);
+const sameKey = (left, right) => left.tableName === right.tableName && left.referencedTableName === right.referencedTableName &&
+  sameNames(left.columns, right.columns) && sameNames(left.referencedColumns, right.referencedColumns);
+
+/**
+ * Each resource's declared foreignKeys in database columns, its fields mapped as json-rest-api stores them.
+ * @param {import("knex").Knex} knex
+ * @param {ReadonlyArray<Record<string, any>>} resources
+ */
+async function declaredForeignKeys(knex, resources) {
+  const declaring = resources.filter((resource) => resource.foreignKeys);
+  if (declaring.length < 1) {
+    return [];
+  }
+  const api = await createResourceHost({ knex, logger: silentLogger });
+  await createResourceRuntime({ api }).own("jskit.foreign-key-check", declaring);
+  return declaring.flatMap((resource) => {
+    const adapter = api.knex.helpers.getStorageAdapter(resource.name);
+    const column = (field) => (field === "id" ? adapter.getIdColumn() : adapter.translateColumn(field));
+    return resource.foreignKeys.map((declared) => Object.freeze({
+      resource: resource.name,
+      declared,
+      tableName: resource.tableName,
+      columns: declared.columns.map(column),
+      referencedTableName: declared.referencedTableName,
+      referencedColumns: declared.referencedColumns ?? ["id"]
+    }));
+  });
+}
+
+/**
+ * Compares the table resources' declared foreignKeys with the keys the connected database holds. json-rest-api relies
+ * on a declared key to skip work, so a declared key the database lacks changes results: it is `missing`, and the
+ * check fails on it. A database key on one of `tables` that nothing declares is `undeclared`: only work json-rest-api
+ * could have skipped. It reads the database, so it runs where one already exists, as `jskit test --databases` does,
+ * never at boot.
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex
+ * @param {ReadonlyArray<Record<string, any>>} options.resources Table resources; those declaring foreignKeys are checked.
+ * @param {ReadonlyArray<string>} [options.tables] The tables whose undeclared keys are reported.
+ */
+async function checkForeignKeys({ knex, resources, tables = [] }) {
+  const [declared, databaseKeys] = await Promise.all([declaredForeignKeys(knex, resources), listForeignKeys(knex)]);
+  const reported = new Set(tables);
+  return Object.freeze({
+    missing: declared.filter((key) => !databaseKeys.some((real) => sameKey(key, real))),
+    undeclared: databaseKeys.filter((real) => reported.has(real.tableName) && !declared.some((key) => sameKey(key, real)))
+  });
+}
+
+export { checkForeignKeys };

package/src/server/handleGuards.js

@@ -1,7 +1,7 @@
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { passedOn } from "@jskit-ai/resource-core/shared/callOptions";
 import { isSystemContext } from "./contexts.js";
-import { MissingScopeError } from "./errors.js";
+import { MissingScopeError, SystemContextRequiredError } from "./errors.js";
 import { resolveUserScopeValue, resolveWorkspaceScopeValue } from "./resourceHost.js";
 
 // The checks that keep a handle's calls inside their scope: a call never reaches rows beyond
@@ -19,7 +19,8 @@ const REQUIRED_OWNERS = Object.freeze({
 const OWNER_RESOLVERS = Object.freeze({ workspace: resolveWorkspaceScopeValue, user: resolveUserScopeValue });
 
 /**
- * Refuses a context, other than a system context, that names no owner the table's ownership needs.
+ * Refuses a context, other than a system context, that names no owner the table's ownership needs: none at all on an
+ * owned table, and any on a `system` table, which only a system context reaches.
  * @param {string} name The resource's name.
  * @param {string} ownership
  * @param {object | null | undefined} context
@@ -28,6 +29,12 @@ function requireOwners(name, ownership, context) {
   if (isSystemContext(context)) {
     return;
   }
+  if (ownership === "system") {
+    throw new SystemContextRequiredError(name);
+  }
+  if (!context && ownership !== "public") {
+    throw new MissingScopeError(name);
+  }
   const missing = REQUIRED_OWNERS[ownership].find((owner) => !OWNER_RESOLVERS[owner](context));
   if (missing) {
     throw new MissingScopeError(name, missing);

package/src/server/handleHidden.js

@@ -1,4 +1,4 @@
-import { RestApiResourceError } from "json-rest-api";
+import { RestApiResourceError, readOnlyQueryBuilder } from "json-rest-api";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { isJobContext } from "./contexts.js";
 import { namedFields } from "./handleRecords.js";
@@ -11,16 +11,6 @@ import { namedFields } from "./handleRecords.js";
 const READABLE_TYPES = Object.freeze(new Set(["id", "string", "integer", "number", "boolean"]));
 // The records each statement of the hidden fields' read covers.
 const RECORDS_PER_READ = 1000;
-// Where each read takes `fields` and where its options, by argument position.
-const FIELD_READS = Object.freeze({
-  get: Object.freeze({ fieldsAt: 1, optionsAt: 2 }),
-  query: Object.freeze({ fieldsAt: 0, optionsAt: 1 }),
-  queryAll: Object.freeze({ fieldsAt: 0, optionsAt: 1 }),
-  lock: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
-  lockMany: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
-  lockWhere: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
-  claim: Object.freeze({ fieldsAt: 1, optionsAt: 1 })
-});
 
 /**
  * The resource's hidden fields a read's `fields` names.
@@ -144,6 +134,9 @@ const HANDLE_SCOPED_QUERIES = new WeakSet();
 const HANDLE_WORK_RUNNERS = new WeakSet();
 // The names an owner's own wrappers of those runners keep.
 const WORK_RUNNER_NAMES = Object.freeze(new Set(["withTransaction", "lockOrCreate"]));
+// The builders a handle's joinSource() answers, which carry the table's visible columns only: the one query builder
+// withoutHiddenFields hands another feature.
+const JOIN_SOURCES = new WeakSet();
 
 /**
  * Records a new handle's scopedQuery, withTransaction and lockOrCreate for withoutHiddenFields.
@@ -156,8 +149,74 @@ function markHandleFunctions({ scopedQuery, withTransaction, lockOrCreate }) {
 }
 
 /**
- * Whether a function answered a Knex value (a raw expression, a column's builder, a query builder an owner's join
- * source answers) rather than rows: a value for the caller's own query, which it builds on and never awaits.
+ * A handle's joinSource(): the table as a join source for another owner's report, which joins it in its own
+ * statement. It answers `{ query, column }`: the rows scopedQuery() gives under `alias` (the caller's ownership, the
+ * row policy and `filters` applied) with the stored columns a read answers only, never a hidden one, and
+ * `column(field)` naming each under that alias. A CRUD feature's repository answers it to any feature, where it
+ * refuses scopedQuery(). The builder comes wrapped, since a builder is thenable.
+ * @param {object} dependencies
+ * @param {{ knex: { instance: any } }} dependencies.api
+ * @param {{ name: string, schema: Record<string, any> }} dependencies.resource
+ * @param {() => { vars: { schemaInfo: { schemaStructure: Record<string, any> } } }} dependencies.jsonRest
+ * @param {(params: { alias: string, filters?: object }, options: object) => Promise<{ query: any }>} dependencies.scopedQuery
+ * @param {(field: string, alias?: string) => string} dependencies.column
+ */
+function createJoinSource({ api, resource, jsonRest, scopedQuery, column }) {
+  const { name } = resource;
+  /**
+   * @param {{ alias: string, filters?: object }} params
+   * @param {{ context?: object | null, trx?: object | null }} [options]
+   * @returns {Promise<Readonly<{ query: any, column: (field: string) => string }>>}
+   */
+  return async function joinSource({ alias, filters } = {}, options = {}) {
+    if (typeof alias !== "string" || !alias) {
+      throw new TypeError(`${name}.joinSource() needs the alias the report joins the ${name} under.`);
+    }
+    const { query } = await scopedQuery({ alias, ...(filters === undefined ? {} : { filters }) }, options);
+    const { schemaStructure } = jsonRest().vars.schemaInfo;
+    const visible = Object.keys(schemaStructure).filter((field) => {
+      const definition = schemaStructure[field];
+      return field !== "id" && definition.hidden !== true && definition.virtual !== true && !definition.belongsToPolymorphic;
+    });
+    // The scoped rows' visible columns, as a derived table under the alias: nothing a caller adds reaches the others.
+    const source = readOnlyQueryBuilder(
+      (options.trx || api.knex.instance).from(query.select(["id", ...visible].map((field) => column(field, alias))).as(alias)),
+      { resourceType: name }
+    );
+    JOIN_SOURCES.add(source);
+    return Object.freeze({
+      query: source,
+      column(field) {
+        if (resource.schema[field]?.hidden === true) {
+          throw new TypeError(`${name}.joinSource() carries no hidden field, so it has no column for "${field}".`);
+        }
+        return column(field, alias);
+      }
+    });
+  };
+}
+
+/**
+ * The field names a call's `fields` names: a list of names, names separated by commas, or a sparse fieldset (each
+ * resource type's names, separated by commas).
+ * @param {unknown} fields
+ * @returns {string[]}
+ */
+function fieldNames(fields) {
+  if (typeof fields === "string") {
+    return fields.split(",").map((field) => field.trim());
+  }
+  if (Array.isArray(fields)) {
+    return fields.filter((field) => typeof field === "string");
+  }
+  return isRecord(fields)
+    ? Object.values(fields).flatMap((names) => (typeof names === "string" || Array.isArray(names) ? fieldNames(names) : []))
+    : [];
+}
+
+/**
+ * Whether a function answered a Knex value (a raw expression, a column's builder, a joinSource()'s query builder)
+ * rather than rows: a value for the caller's own query, which it builds on and never awaits.
  * @param {unknown} value
  */
 function isKnexValue(value) {
@@ -165,6 +224,25 @@ function isKnexValue(value) {
   return isRecord(value) && typeof value.toSQL === "function";
 }
 
+/**
+ * A Knex value another feature may build on, as it is: a raw expression or a column's reference, or a joinSource()'s
+ * builder. Any other query builder (a scopedQuery()'s, or one the owner built) can select every column of its table,
+ * the hidden ones too, so it is refused.
+ * @param {any} value A Knex value (see isKnexValue).
+ * @param {string} label
+ */
+function withoutFullBuilder(value, label) {
+  // readable-check: allow method-probe - data: a Knex query builder, unlike a raw expression, takes where()
+  if (typeof value.where === "function" && !JOIN_SOURCES.has(value)) {
+    throw new TypeError(
+      `${label} answers a query builder, which can select every column, the hidden fields too, which only the table's ` +
+        "owner, or a system context, reads: answer the table's joinSource({ alias }, options), which carries its visible " +
+        "columns only."
+    );
+  }
+  return value;
+}
+
 /** @param {unknown} value */
 function isPlainRecord(value) {
   if (!isRecord(value)) {
@@ -176,23 +254,27 @@ function isPlainRecord(value) {
 
 /**
  * The value without the hidden fields, wherever a plain record in it, or in its arrays and maps, carries one: a copy
- * of what changed (frozen when the original was), the value itself when nothing did. Builders, dates and other
- * instances are left as they are.
+ * of what changed (frozen when the original was), the value itself when nothing did. A query builder in it that is no
+ * joinSource()'s is refused (see withoutFullBuilder); raw expressions, dates and other instances are left as they are.
  * @param {unknown} value
  * @param {Set<string>} hidden
+ * @param {string} label
  * @param {WeakMap<object, unknown>} [seen]
  */
-function withoutHiddenValues(value, hidden, seen = new WeakMap()) {
+function withoutHiddenValues(value, hidden, label, seen = new WeakMap()) {
   if (!value || typeof value !== "object") {
     return value;
   }
+  if (isKnexValue(value)) {
+    return withoutFullBuilder(value, label);
+  }
   if (seen.has(value)) {
     return seen.get(value);
   }
   seen.set(value, value);
   let changed = false;
   const strip = (entry) => {
-    const next = withoutHiddenValues(entry, hidden, seen);
+    const next = withoutHiddenValues(entry, hidden, label, seen);
     changed ||= next !== entry;
     return next;
   };
@@ -220,13 +302,15 @@ function withoutHiddenValues(value, hidden, seen = new WeakMap()) {
 
 /**
  * The repository an owner gives other features (a CRUD feature's `resourceApi.repository`): every function it holds,
- * its sub-repositories' included, answers without the hidden fields of the tables the owner owns, and a read whose
- * `fields` names a hidden field of the resource, or any scopedQuery() (its builder carries every column, hidden ones
- * too), is refused, unless the call runs in a system context or one it derived (its options, the last record it
- * takes). So a read the owner adds in decorateRepository cannot hand a hidden field out either; the owner's own
- * code, its join sources included, reads with the repository itself. withTransaction and lockOrCreate answer the
- * caller's own work as it is, and a function answering a Knex value (raw(), a join source's builder) answers it as
- * it is, unawaited. A repository whose tables have no hidden fields stays as it is.
+ * its sub-repositories' included, answers without the hidden fields of the tables the owner owns. A call whose
+ * `fields` (in any record it takes) names one of those hidden fields is refused before it runs, whatever the method,
+ * so a read the owner adds in decorateRepository that forwards the caller's `fields` fails loudly rather than answer
+ * the field as undefined; so is any scopedQuery(), and an answer holding a query builder other than a joinSource()'s
+ * (either can select every column, hidden ones too). A call in a system context or one it derived, in any record it
+ * takes, runs as it is. The owner's own code reads with the repository itself. withTransaction and lockOrCreate answer
+ * the caller's own work as it is, and a function answering a Knex value (raw(), a joinSource()'s builder) answers it
+ * as it is, unawaited. A repository whose tables have no hidden fields stays as it is. Hidden fields are told by
+ * name, so a field one owned table hides and another shows is refused here, when the feature's repository is built.
  * @template {object} T
  * @param {T} repository
  * @param {{ name: string, schema: Record<string, any> } | ReadonlyArray<{ name: string, schema: Record<string, any> }>} resources
@@ -239,12 +323,24 @@ function withoutHiddenFields(repository, resources) {
   if (!isRecord(repository) || hidden.size < 1) {
     return repository;
   }
+  for (const { name, schema } of owned) {
+    const shown = Object.keys(schema).find((field) => hidden.has(field) && schema[field]?.hidden !== true);
+    if (shown) {
+      const hiders = owned.filter((other) => other.schema[shown]?.hidden === true).map((other) => other.name);
+      throw new TypeError(
+        `${name}.${shown} is a visible field, but ${hiders.join(", ")}, which the same feature owns, hides a field of that ` +
+          `name; its repository strips hidden fields by name from every answer, so ${name}.${shown} would never reach ` +
+          "another feature: hide it in both tables, or rename one of them."
+      );
+    }
+  }
   return guardedRepository(repository, owned[0], hidden, new WeakSet());
 }
 
 /**
  * @param {object} repository
- * @param {{ name: string, schema: Record<string, any> } | null} resource The resource whose reads it refuses by name; none for a sub-repository.
+ * @param {{ name: string, schema: Record<string, any> } | null} resource The resource it serves, which names its methods
+ *   in errors and whose scopedQuery it refuses under that name too; none for a sub-repository.
  * @param {Set<string>} hidden
  * @param {WeakSet<object>} guarded
  */
@@ -272,21 +368,22 @@ function guardedRepository(repository, resource, hidden, guarded) {
  */
 function guardedFunction(repository, key, call, resource, hidden) {
   const label = `${resource?.name ?? "repository"}.${key}()`;
-  const fieldRead = resource && Object.hasOwn(FIELD_READS, key) ? FIELD_READS[key] : null;
   const builder = HANDLE_SCOPED_QUERIES.has(call) || (resource !== null && key === "scopedQuery");
   const work = HANDLE_WORK_RUNNERS.has(call) || WORK_RUNNER_NAMES.has(key);
   return function callWithoutHiddenFields(...args) {
-    const options = fieldRead ? args[fieldRead.optionsAt] : args.findLast(isRecord);
-    if (isJobContext(options?.context)) {
+    // A system context, or one it derived, in whichever record the method takes its options.
+    if (args.some((arg) => isRecord(arg) && isJobContext(arg.context))) {
       return call.apply(repository, args);
     }
     if (builder) {
       return Promise.reject(new TypeError(
         `${label} answers every column, its hidden fields too, which only the table's owner, or a system context, ` +
-          "reads: ask the owner for a method answering the rows or a join source."
+          "reads: read the rows through the repository's reads, or join its joinSource({ alias }, options), which " +
+          "carries the visible columns only."
       ));
     }
-    const named = fieldRead ? namedHiddenFields(resource, args[fieldRead.fieldsAt]?.fields) : [];
+    const named = [...new Set(args.flatMap((arg) => (isRecord(arg) ? fieldNames(arg.fields) : [])))]
+      .filter((field) => hidden.has(field));
     if (named.length > 0) {
       return Promise.reject(new TypeError(
         `${label} fields names the hidden field ${named.map((field) => `"${field}"`).join(", ")}, ` +
@@ -294,16 +391,20 @@ function guardedFunction(repository, key, call, resource, hidden) {
       ));
     }
     const answer = call.apply(repository, args);
-    // A runner's answer is the caller's own work, and a Knex value (raw(), or an owner's join source answering a
-    // builder) carries no rows: both pass as they are, unawaited, so a builder never runs here.
-    if (work || isKnexValue(answer)) {
+    // A runner's answer is the caller's own work: it passes as it is.
+    if (work) {
       return answer;
     }
+    // A Knex value (raw(), a joinSource()'s builder) carries no rows: it passes as it is, unawaited, so a builder
+    // never runs here.
+    if (isKnexValue(answer)) {
+      return withoutFullBuilder(answer, label);
+    }
     // readable-check: allow method-probe - data: a repository's method may answer at once or with a promise
     return typeof answer?.then === "function"
-      ? answer.then((value) => withoutHiddenValues(value, hidden))
-      : withoutHiddenValues(answer, hidden);
+      ? answer.then((value) => withoutHiddenValues(value, hidden, label))
+      : withoutHiddenValues(answer, hidden, label);
   };
 }
 
-export { createHiddenFieldReads, markHandleFunctions, withoutHiddenFields };
+export { createHiddenFieldReads, createJoinSource, markHandleFunctions, withoutHiddenFields };

package/src/server/handleLocks.js

@@ -1,6 +1,29 @@
 import { missingOf, requireDefinedFilters } from "./handleGuards.js";
 import { handleRecords, sparseFieldset, textList } from "./handleRecords.js";
 
+// The row lock a locking read takes. "update" (the default) is FOR UPDATE. "noKeyUpdate" is PostgreSQL's FOR NO KEY
+// UPDATE, which still keeps every other lock and write of the row out but lets other transactions insert rows that
+// reference it (a foreign key's check takes FOR KEY SHARE); MySQL, MariaDB and SQLite have no weaker exclusive lock and
+// lock as for "update".
+const LOCK_MODES = Object.freeze(["update", "noKeyUpdate"]);
+
+/**
+ * json-rest-api's lock mode for a locking read: none when the call names none, so json-rest-api takes its default.
+ * Another value is a TypeError naming the handle method, before anything runs.
+ * @param {string} name The resource's name.
+ * @param {string} caller The handle method, for the message.
+ * @param {unknown} lockMode
+ */
+function lockModeOf(name, caller, lockMode) {
+  if (lockMode === undefined) {
+    return {};
+  }
+  if (!LOCK_MODES.includes(/** @type {string} */ (lockMode))) {
+    throw new TypeError(`${name}.${caller}() lockMode is "update" (the default) or "noKeyUpdate". Received: ${JSON.stringify(lockMode)}`);
+  }
+  return { lockMode };
+}
+
 /**
  * A handle's locking reads: lock, lockMany, lockWhere and claim. Each needs the
  * caller's transaction (`options.trx`), locks only rows the caller may see, and
@@ -18,12 +41,15 @@ import { handleRecords, sparseFieldset, textList } from "./handleRecords.js";
  *   fields `options.fields` names, read after the lock.
  */
 function createLockReads({ name, resource, jsonRest, readFields, contextOf, hiddenFields }) {
-  // A locking read (json-rest-api's lockByIds, lockWhere or claim) of the fields options.fields names, as records.
-  async function lockRead(method, read, options) {
+  // A locking read (json-rest-api's lockByIds, lockWhere or claim) of the fields options.fields names, as records, in the
+  // lock mode options.lockMode names. `caller` is the handle method, for the messages.
+  async function lockRead(caller, method, read, options) {
+    const mode = lockModeOf(name, caller, options.lockMode);
     const hidden = hiddenFields.named(options.fields, "plain");
     const fields = readFields({ fields: options.fields }, "view");
     const { data } = await jsonRest()[method]({
       ...read,
+      ...mode,
       transaction: options.trx,
       format: "plain",
       ...(fields ? { queryParams: { fields: sparseFieldset(resource, fields) } } : {})
@@ -35,25 +61,31 @@ function createLockReads({ name, resource, jsonRest, readFields, contextOf, hidd
    * Locks the visible rows among the ids, in id order, and answers them; hidden or missing ids throw, or are
    * left out with `missing: "skip"`. MySQL locks every listed id, a hidden one too: take ids from scoped reads.
    * `fields` names the fields the lock reads, so a belongs-to field left out costs no check that its related
-   * record is visible; without it every field is read.
+   * record is visible; without it every field is read. `lockMode: "noKeyUpdate"` takes PostgreSQL's FOR NO KEY
+   * UPDATE, so other transactions may still insert rows that reference the locked ones (see LOCK_MODES).
    * @param {unknown[]} ids
-   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[] }} options
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
    */
   async function lockMany(ids, options) {
-    return lockRead("lockByIds", { ids, ...(options.missing ? { missing: options.missing } : {}) }, options);
+    return lockRead("lockMany", "lockByIds", { ids, ...(options.missing ? { missing: options.missing } : {}) }, options);
+  }
+
+  // lockMany for lock(): its messages name lock().
+  function lockOne(id, options) {
+    return lockRead("lock", "lockByIds", { ids: [id], ...(options.missing ? { missing: options.missing } : {}) }, options);
   }
 
   /**
    * Locks the record's row until the transaction ends and answers it as the
    * lock saw it. Needs options.trx. A missing or hidden record throws
    * json-rest-api's not-found error, or answers null with `missing: "skip"`.
-   * `fields` reads only the fields the work needs (see lockMany).
+   * `fields` reads only the fields the work needs, and `lockMode` picks the lock (see lockMany).
    * @param {unknown} id
-   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[] }} options
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
    */
   async function lock(id, options) {
     missingOf(name, "lock", options.missing);
-    const [record] = await lockMany([id], options);
+    const [record] = await lockOne(id, options);
     return record ?? null;
   }
 
@@ -64,28 +96,28 @@ function createLockReads({ name, resource, jsonRest, readFields, contextOf, hidd
    * past that). It does not lock rows inserted later: unique numbers take a unique
    * index, or a counter row taken with lock(). On MySQL it needs an index starting
    * with the ownership columns (no owners: with a filtered column), or it refuses.
-   * `fields` reads only the fields the work needs (see lockMany).
+   * `fields` reads only the fields the work needs, and `lockMode` picks the lock (see lockMany).
    * @param {object} filters
-   * @param {{ context?: object | null, trx: object, fields?: string[] }} options
+   * @param {{ context?: object | null, trx: object, fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
    */
   async function lockWhere(filters, options) {
     requireDefinedFilters(name, "lockWhere", filters);
-    return lockRead("lockWhere", { filters }, options);
+    return lockRead("lockWhere", "lockWhere", { filters }, options);
   }
 
   /**
    * Takes up to `take` (default 1) of the rows the filters select that no
    * other transaction holds, in `sort` order, locked until the transaction ends.
-   * `fields` reads only the fields the work needs (see lockMany).
+   * `fields` reads only the fields the work needs, and `lockMode` picks the lock (see lockMany).
    * @param {{ filters: object, sort?: string | string[], take?: number }} params
-   * @param {{ context?: object | null, trx: object, fields?: string[] }} options
+   * @param {{ context?: object | null, trx: object, fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
    */
   async function claim({ filters, sort, take } = {}, options, ...rest) {
     if (rest.length > 0) {
       throw new TypeError(`${name}.claim() takes ({ filters, sort, take }, options).`);
     }
     requireDefinedFilters(name, "claim", filters);
-    return lockRead("claim", {
+    return lockRead("claim", "claim", {
       filters,
       ...(take === undefined ? {} : { limit: take }),
       ...(sort === undefined ? {} : { sort: textList(sort) })
@@ -100,4 +132,4 @@ function createLockReads({ name, resource, jsonRest, readFields, contextOf, hidd
   });
 }
 
-export { createLockReads };
+export { createLockReads, lockModeOf };