@jskit-ai/resource-runtime 0.2.12 → 0.2.14

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 };

package/src/server/index.js

@@ -1,6 +1,7 @@
 export { ResourceRuntimeProvider } from "./ResourceRuntimeProvider.js";
 export { DEFAULT_REQUEST_ROW_LIMIT, DEFAULT_SERVER_PAGE_SIZE } from "./resourceRuntime.js";
 export { buildJsonRestQueryParams, resolveUserScopeValue, resolveWorkspaceScopeValue } from "./resourceHost.js";
+export { checkForeignKeys } from "./foreignKeyCheck.js";
 export { createStandaloneResources } from "./standaloneResources.js";
 export { isSystemContext } from "./contexts.js";
 export { withoutHiddenFields } from "./handleHidden.js";
@@ -11,5 +12,7 @@ export {
   PageSizeError,
   RowLimitError,
   StaleRecordError,
-  UnpagedQueryError
+  SystemContextRequiredError,
+  UnpagedQueryError,
+  UnsupportedDatabaseError
 } from "./errors.js";

package/src/server/lockOrCreate.js

@@ -1,6 +1,7 @@
 import { isDeadlockError, isDuplicateEntryError, isLostDuplicateInsertRace } from "@jskit-ai/database-runtime/shared";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { passedOn } from "./handleGuards.js";
+import { lockModeOf } from "./handleLocks.js";
 
 // First uses of one id at once can collide on its insert before any work runs (on MySQL and MariaDB, first uses of
 // neighbouring ids too, through their gap locks): each collision runs the loser again after a short random wait.
@@ -19,7 +20,8 @@ const CREATE_IF_MISSING = Object.freeze({ keys: ["id"], action: "ignore" });
  * @template T
  * @param {Pick<import("./types.js").ResourceHandle, "name" | "withTransaction" | "lock" | "createMany">} handle
  * @param {{ id: unknown } & Record<string, unknown>} row
- * @param {{ context?: object | null, trx?: object | null }} options
+ * @param {{ context?: object | null, trx?: object | null, lockMode?: "update" | "noKeyUpdate" }} options `lockMode` is the
+ *   record's lock, as lock() takes it.
  * @param {(record: Record<string, any>, txOptions: Readonly<Record<string, any>>) => Promise<T> | T} work
  * @returns {Promise<T>}
  */
@@ -27,13 +29,15 @@ async function lockOrCreate(handle, row, options, work) {
   if (!isRecord(row) || row.id == null) {
     throw new TypeError(`${handle.name}.lockOrCreate() takes (row, options, work), the row to create holding its id.`);
   }
+  // The lock mode the caller names, for both locks of the record, refused before any transaction opens.
+  const mode = lockModeOf(handle.name, "lockOrCreate", options.lockMode);
   const locked = async (txOptions) => {
-    const existing = await handle.lock(row.id, { ...txOptions, missing: "skip" });
+    const existing = await handle.lock(row.id, { ...txOptions, ...mode, missing: "skip" });
     if (existing) {
       return existing;
     }
     await handle.createMany([row], { ...txOptions, onConflict: CREATE_IF_MISSING, returning: "none" });
-    return handle.lock(row.id, txOptions);
+    return handle.lock(row.id, { ...txOptions, ...mode });
   };
   if (options.trx) {
     const txOptions = passedOn(options);

package/src/server/resourceHandle.js

@@ -2,12 +2,13 @@ import diagnosticsChannel from "node:diagnostics_channel";
 import { RestApiRowLimitError } from "json-rest-api";
 import { retryDeadlocks } from "@jskit-ai/database-runtime/shared";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { readChangeHorizon } from "./changeHorizon.js";
 import { createJsonRestContext, isJobContext } from "./contexts.js";
-import { createHiddenFieldReads, markHandleFunctions } from "./handleHidden.js";
-import { createLockReads } from "./handleLocks.js";
+import { createHiddenFieldReads, createJoinSource, markHandleFunctions } from "./handleHidden.js";
+import { createLockReads, lockModeOf } from "./handleLocks.js";
 import { findOrCreateRecord, lockOrCreate } from "./lockOrCreate.js";
 import { valueOnlyRaw } from "./rawExpression.js";
-import { MissingScopeError, PageSizeError, RowLimitError, StaleRecordError, UnpagedQueryError } from "./errors.js";
+import { PageSizeError, RowLimitError, StaleRecordError, UnpagedQueryError } from "./errors.js";
 import {
   formatOf, matchesNoRow, missingOf, passedOn, refuseConditions, requireConditionValues, requireDefinedFilters, requireOwners, requirePatchConditions,
   requireReadParams, requireUpsertRows, whereSelection
@@ -154,9 +155,6 @@ function createResourceHandle({ api, resource, hooks, settings, resourceNamed })
   /** @param {{ context?: object | null }} options */
   function contextOf(options) {
     requireHandleTransaction(name, options);
-    if (!options.context && resource.ownership !== "public") {
-      throw new MissingScopeError(name);
-    }
     requireOwners(name, resource.ownership, options.context);
     return createJsonRestContext(options.context);
   }
@@ -165,6 +163,8 @@ function createResourceHandle({ api, resource, hooks, settings, resourceNamed })
   const readFields = (params, kind) => requestedFields(params, quiet[kind], () => jsonRest().vars.schemaInfo);
   // The hidden fields a plain read names, which json-rest-api leaves out (see handleHidden.js).
   const hiddenFields = createHiddenFieldReads({ resource, scopedQuery, column });
+  // The table as a join source, with its visible columns only (see handleHidden.js).
+  const joinSource = createJoinSource({ api, resource, jsonRest, scopedQuery, column });
   // lock, lockMany, lockWhere and claim (see handleLocks.js).
   const { lock, lockMany, lockWhere, claim } = createLockReads({ name, resource, jsonRest, readFields, contextOf, hiddenFields });
 
@@ -590,17 +590,19 @@ function createResourceHandle({ api, resource, hooks, settings, resourceNamed })
    * The same changes to every record the filters select (the caller's own rows only), in one statement
    * that carries the scope and filters, so a row gone meanwhile is skipped. Empty filters change every
    * row the caller owns, so they need `all: true`. `returning: "count"` answers how many changed. lockVersion is
-   * refused (see ONE_VERSION).
+   * refused (see ONE_VERSION). `lockMode` is the row lock its selection takes before the write, as the locks take it
+   * (see handleLocks.js).
    * @param {object} filters
    * @param {Record<string, unknown>} attributes
-   * @param {{ context?: object | null, trx?: object | null, returning?: "none" | "ids" | "records" | "count", onlyIf?: object, all?: boolean, chunkSize?: number }} [options]
+   * @param {{ context?: object | null, trx?: object | null, returning?: "none" | "ids" | "records" | "count", onlyIf?: object, all?: boolean, chunkSize?: number, lockMode?: "update" | "noKeyUpdate" }} [options]
    */
   async function patchWhere(filters, attributes, options = {}) {
     refuseConditions(name, "patchWhere", options, ["lockVersion"], ONE_VERSION);
     requireConditionValues(name, "patchWhere", options, ["onlyIf"]);
     const selection = whereSelection(name, "patchWhere", filters, options);
+    const mode = lockModeOf(name, "patchWhere", options.lockMode);
     return manyRowWrite("patchWhere", 0, options, (params, context) => jsonRest().patchWhere(
-      { ...params, ...selection, data: inputData(resource, attributes, "update", options.context),
+      { ...params, ...selection, ...mode, data: inputData(resource, attributes, "update", options.context),
         ...(options.onlyIf ? { onlyIf: options.onlyIf } : {}) },
       context
     ));
@@ -693,6 +695,15 @@ function createResourceHandle({ api, resource, hooks, settings, resourceNamed })
     return valueOnlyRaw(`${name}.raw()`, api.knex.instance, [sql, bindings, ...rest]);
   }
 
+  /**
+   * PostgreSQL's snapshot horizon, as decimal text, in the caller's transaction when there is one (see readChangeHorizon).
+   * @param {{ context?: object | null, trx?: object | null }} [options]
+   */
+  async function changeHorizon(options = {}) {
+    contextOf(options);
+    return readChangeHorizon(name, options.trx || api.knex.instance);
+  }
+
   markHandleFunctions({ scopedQuery, withTransaction, lockOrCreate: lockOrCreateRecord });
   return Object.freeze({
     name,
@@ -715,7 +726,9 @@ function createResourceHandle({ api, resource, hooks, settings, resourceNamed })
     lockWhere,
     lockOrCreate: lockOrCreateRecord,
     claim,
+    changeHorizon,
     scopedQuery,
+    joinSource,
     column,
     raw
   });

package/src/server/resourceHost.js

@@ -432,7 +432,8 @@ function primaryField(scopeOptions) {
 
 /**
  * json-rest-api's options for a table resource: its own keys, with `ownership`
- * as json-rest-api's autofilter preset (none for a public table),
+ * as json-rest-api's autofilter preset (none for a public or a system table,
+ * which have no owner columns),
  * `defaultExclude` as normally hidden fields, symbolic write serializers
  * resolved and collection relations derived. The owner's server-only extras
  * (row policy, id normalizer, query fields) are added here, never in the
@@ -463,7 +464,7 @@ function resourceScopeOptions(
   const scopeOptions = cloneJsonRestResourceValue(tableOptions, {
     writeSerializers: normalizeObject(writeSerializers)
   });
-  if (ownership !== "public") {
+  if (ownership !== "public" && ownership !== "system") {
     scopeOptions.autofilter = ownership;
   }
   if (isPlainJsonRestObject(searchSchema)) {

package/src/test/index.js

@@ -3,7 +3,7 @@ import { ActionProvider } from "@jskit-ai/kernel/server/actions";
 import { EventProvider } from "@jskit-ai/kernel/server/runtime";
 import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
-import { requireTestDatabase, tableNames, TestDatabaseMissingError } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createPackageTestKnex, requireTestDatabase, tableNames, TestDatabaseMissingError } from "@jskit-ai/database-runtime/server/testDatabases";
 import { createResourceHost } from "../server/resourceHost.js";
 import { createResourceRuntime } from "../server/resourceRuntime.js";
 import { expectFlatQueries } from "./expectFlatQueries.js";
@@ -113,6 +113,7 @@ async function expectEveryTableOwned({ knex, runtime, infrastructureTables = [],
 
 export {
   TestDatabaseMissingError,
+  createPackageTestKnex,
   createTestResourceRuntime,
   expectEveryTableOwned,
   expectFlatQueries,

package/test/callSettings.test.js

@@ -1,9 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import knexLib from "knex";
 import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
 import { passedOn } from "../src/server/index.js";
-import { createTestResourceRuntime } from "../src/test/index.js";
+import { createPackageTestKnex, createTestResourceRuntime } from "../src/test/index.js";
+
+// SQLite in memory, or a PostgreSQL schema of its own on a DB_CLIENT=pg run (see createPackageTestKnex).
+const testKnex = (t) => createPackageTestKnex(t, { environment: process.env });
 
 // A call's settings (returning, missing, format, lockVersion...) are for that one call. What it hands on, to the work
 // of a transaction, to an afterWrite hook or to the handle's own nested calls, is its context and transaction only.
@@ -14,8 +16,7 @@ const SETTINGS = Object.freeze({ returning: "none", missing: "skip", format: "js
 const notFound = (error) => error.code === "REST_API_RESOURCE" && error.subtype === "not_found";
 
 async function createNotes(t, hooks) {
-  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
-  t.after(() => knex.destroy());
+  const knex = await testKnex(t);
   await knex.schema.createTable("notes", (table) => {
     table.increments("id");
     table.integer("workspace_id").nullable();

package/test/changes.postgres.test.js

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { createPackageTestKnex, createTestResourceRuntime } from "../src/test/index.js";
+
+// What changed since a horizon, on PostgreSQL, with real concurrent transactions. Each row carries the transaction
+// that last wrote it, an xid8 change stamp that a trigger sets on every insert and update, whatever the write sent, read
+// through an xid8 field with changedSince (>=) and changedBefore (<) filters. A reader takes
+// changeHorizon() before it reads; every transaction below the horizon had finished, so a later read of the rows
+// stamped at or above it finds everything the first read could not see. Each test works in a schema of its own in
+// TEST_DB_NAME (createPackageTestKnex); other sessions on the server may hold the horizon lower, never higher, so the
+// tests check what a read must include and what it must leave out.
+
+const skip = process.env.DB_CLIENT === "pg" ? false : "a PostgreSQL test: it runs on a DB_CLIENT=pg run, with TEST_DB_NAME";
+const WORKSPACE = Object.freeze({ context: Object.freeze({ workspace: Object.freeze({ id: "1" }) }) });
+
+const messageResource = defineTableResource({
+  name: "messages",
+  tableName: "messages",
+  ownership: "workspace",
+  defaultSort: ["id"],
+  schema: {
+    id: { type: "id", primary: true },
+    workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+    body: { type: "string", required: true, search: true },
+    // The database stamps it; nothing writes it.
+    changed: { type: "xid8", nullable: true }
+  },
+  searchSchema: {
+    changedSince: { type: "xid8", actualField: "changed", filterOperator: ">=" },
+    changedBefore: { type: "xid8", actualField: "changed", filterOperator: "<" }
+  }
+});
+
+async function database(t) {
+  const knex = await createPackageTestKnex(t, { environment: process.env });
+  await knex.schema.createTable("messages", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.string("body").notNullable();
+    table.specificType("changed", "xid8").notNullable().defaultTo(knex.raw("pg_current_xact_id()"));
+  });
+  await knex.raw(
+    "create function messages_changed() returns trigger language plpgsql as $$ " +
+    "begin new.changed := pg_current_xact_id(); return new; end $$"
+  );
+  await knex.raw("create trigger messages_changed before insert or update on messages for each row execute function messages_changed()");
+  const runtime = await createTestResourceRuntime({ knex });
+  const { messages } = await runtime.own("messages.feature", [messageResource]);
+  return { knex, messages };
+}
+
+const bodies = (records) => new Map(records.map(({ id, body }) => [String(id), body]));
+
+test("a read from the change horizon finds what a transaction still open at the horizon wrote, which the highest id seen misses", { skip }, async (t) => {
+  const { knex, messages } = await database(t);
+  const [first] = (await messages.createMany([{ body: "first" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  // A writer still open when the reader reads: it changes the first message and adds one, taking its id now.
+  const writer = await knex.transaction();
+  t.after(() => (writer.isCompleted() ? undefined : writer.rollback()));
+  await writer("messages").where({ id: first }).update({ body: "first, edited" });
+  const [{ id: added }] = await writer("messages").insert({ workspace_id: 1, body: "added by the open writer" }, ["id"]);
+  const [{ id: theirs }] = await writer("messages").insert({ workspace_id: 2, body: "another workspace's" }, ["id"]);
+  const { rows: [{ xid: writerXid }] } = await writer.raw("select pg_current_xact_id()::text as xid");
+  // A later writer adds one and commits at once, so its id is above the open writer's.
+  const [later] = (await messages.createMany([{ body: "added later" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  const horizon = await messages.changeHorizon(WORKSPACE);
+  const page = await messages.queryAll({}, WORKSPACE);
+  assert.deepEqual([...bodies(page)], [[first, "first"], [later, "added later"]]);
+  assert.match(horizon, /^\d{1,20}$/u);
+  assert.ok(BigInt(horizon) <= BigInt(writerXid), `the open writer's transaction ${writerXid} is at or above the horizon ${horizon}`);
+
+  await writer.commit();
+  const caughtUp = bodies(await messages.queryAll({ filters: { changedSince: horizon } }, WORKSPACE));
+  assert.equal(caughtUp.get(first), "first, edited", "the change of an older message");
+  assert.equal(caughtUp.get(String(added)), "added by the open writer", "the message whose id was taken before it committed");
+  assert.equal(caughtUp.has(String(theirs)), false, "another workspace's message stays out");
+  // "Past the highest id seen" misses both: the edit kept its id, and the added message's id is below the later one's.
+  const highestSeen = Math.max(...page.map(({ id }) => Number(id)));
+  assert.deepEqual([Number(first) < highestSeen, Number(added) < highestSeen], [true, true]);
+});
+
+test("changedSince and changedBefore read the window between two horizons; what the window leaves out, the next read from its end finds", { skip }, async (t) => {
+  const { messages } = await database(t);
+  const start = await messages.changeHorizon(WORKSPACE);
+  const [a] = (await messages.createMany([{ body: "a" }], { ...WORKSPACE, returning: "ids" })).map(String);
+  const end = await messages.changeHorizon(WORKSPACE);
+  const [b] = (await messages.createMany([{ body: "b" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  const window = bodies(await messages.queryAll({ filters: { changedSince: start, changedBefore: end } }, WORKSPACE));
+  const next = bodies(await messages.queryAll({ filters: { changedSince: end } }, WORKSPACE));
+  // b was written after the end horizon was read, so its transaction is at or above it: never in the window.
+  assert.equal(window.has(b), false);
+  assert.equal(next.get(b), "b");
+  // a is in the window or, while another session held the end horizon below a's transaction, in the next read.
+  assert.equal(window.get(a) ?? next.get(a), "a");
+  assert.ok(BigInt(start) <= BigInt(end), "the horizon never moves back");
+});
+
+test("a stamp compares as a transaction id: from a row's own stamp it is found, from the next one not, a malformed cursor is refused, and a patch moves the stamp on", { skip }, async (t) => {
+  const { knex, messages } = await database(t);
+  // The trigger stamps the writing transaction whatever the write sends.
+  const [created] = await messages.createMany([{ body: "one", changed: "1" }], { ...WORKSPACE, returning: "records" });
+  const stamp = BigInt(created.changed);
+  assert.ok(stamp > 1n, `stamped ${created.changed}`);
+  const found = async (filters) => (await messages.queryAll({ filters }, WORKSPACE)).map(({ body }) => body);
+  const next = String(stamp + 1n);
+  assert.deepEqual(
+    [await found({ changedSince: created.changed }), await found({ changedSince: next }), await found({ changedBefore: created.changed }), await found({ changedBefore: next })],
+    [["one"], [], [], ["one"]]
+  );
+  // They compare as numbers, not as text, where "9" would sort above a stamp starting with a lower digit.
+  assert.deepEqual([await found({ changedSince: "9" }), await found({ changedBefore: "9" })], [["one"], []]);
+  assert.deepEqual(await found({ changedSince: "18446744073709551615" }), []);
+  // A cursor is decimal text below 2^64, leading zeros allowed; anything else is refused before any statement.
+  assert.deepEqual(await found({ changedSince: `000${created.changed}` }), ["one"]);
+  const statements = [];
+  const counted = ({ sql }) => statements.push(sql);
+  knex.on("query", counted);
+  for (const cursor of ["not a position", "-1", "18446744073709551616", "1.5"]) {
+    await assert.rejects(found({ changedSince: cursor }), { code: "REST_API_VALIDATION" }, cursor);
+  }
+  knex.off("query", counted);
+  assert.deepEqual(statements, []);
+  await messages.patch(created.id, { body: "one, edited" }, { ...WORKSPACE, returning: "none" });
+  const [{ changed: moved }] = await knex("messages").where({ id: created.id }).select(knex.raw("changed::text as changed"));
+  assert.ok(BigInt(moved) > stamp, "a patch stamps its own transaction");
+  assert.deepEqual(await found({ changedSince: next }), ["one, edited"]);
+});
+
+test("changeHorizon() reads in the caller's transaction and checks the call's context, as every handle call does", { skip }, async (t) => {
+  const { messages } = await database(t);
+  const inside = await messages.withTransaction(WORKSPACE, async (txOptions) => {
+    await messages.create({ body: "x" }, { ...txOptions, returning: "none" });
+    return messages.changeHorizon(txOptions);
+  });
+  assert.match(inside, /^\d{1,20}$/u);
+  await assert.rejects(messages.changeHorizon({}), { code: "RESOURCE_MISSING_SCOPE" });
+});

package/test/foreignKeys.test.js

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexLib from "knex";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { checkForeignKeys } from "../src/server/index.js";
+import { createResourceHost } from "../src/server/resourceHost.js";
+import { createResourceRuntime } from "../src/server/resourceRuntime.js";
+
+const owners = defineTableResource({
+  name: "owners",
+  tableName: "owners",
+  ownership: "public",
+  schema: { name: { type: "string", required: true } }
+});
+
+function petsResource(foreignKeys) {
+  return defineTableResource({
+    name: "pets",
+    tableName: "pets",
+    ownership: "public",
+    schema: {
+      name: { type: "string", required: true },
+      ownerId: { type: "id", nullable: true, belongsTo: "owners", as: "owner" },
+      vetId: { type: "id", nullable: true, storage: { column: "clinic_vet" } }
+    },
+    ...(foreignKeys ? { foreignKeys } : {})
+  });
+}
+
+async function petsDatabase(t) {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("owners", (table) => {
+    table.increments("id");
+    table.string("name").notNullable();
+  });
+  await knex.schema.createTable("vets", (table) => table.increments("id"));
+  await knex.schema.createTable("pets", (table) => {
+    table.increments("id");
+    table.string("name").notNullable();
+    table.integer("owner_id").references("id").inTable("owners");
+    table.integer("clinic_vet");
+  });
+  return knex;
+}
+
+test("a declared foreignKeys reaches the json-rest-api resource, and a table without one declares none", async (t) => {
+  const knex = await petsDatabase(t);
+  const api = await createResourceHost({ knex, logger: silentLogger });
+  const declared = [{ columns: ["ownerId"], referencedTableName: "owners", deleteRule: "SET NULL" }];
+  const runtime = createResourceRuntime({ api });
+  const { pets } = await runtime.own("app.pets", [owners, petsResource(declared)]);
+  const context = runtime.declareSystemScope("app.pets", "The test seeds every owner's pets.")("seed a pet");
+
+  assert.deepEqual(api.resources.pets.vars.schemaInfo.foreignKeys, declared);
+  assert.deepEqual(api.resources.owners.vars.schemaInfo.foreignKeys, []);
+  const [ownerId] = await knex("owners").insert({ name: "Ada" });
+  const created = await pets.create({ name: "Rex", ownerId: String(ownerId) }, { context });
+  assert.equal(created.ownerId, String(ownerId));
+  assert.equal((await pets.get(created.id, {}, { context })).ownerId, String(ownerId));
+});
+
+test("checkForeignKeys finds a declared key the database lacks, and reports a real key nothing declares", async (t) => {
+  const knex = await petsDatabase(t);
+
+  const exact = await checkForeignKeys({
+    knex,
+    resources: [owners, petsResource([{ columns: ["ownerId"], referencedTableName: "owners" }])],
+    tables: ["owners", "pets"]
+  });
+  assert.deepEqual(exact, { missing: [], undeclared: [] });
+
+  const wrong = await checkForeignKeys({
+    knex,
+    resources: [petsResource([
+      { columns: ["ownerId"], referencedTableName: "owners", referencedColumns: ["id"] },
+      { name: "pets_vet", columns: ["vetId"], referencedTableName: "vets" }
+    ])],
+    tables: ["pets"]
+  });
+  assert.deepEqual(wrong.missing.map(({ resource, tableName, columns, referencedTableName, referencedColumns, declared }) =>
+    ({ resource, tableName, columns, referencedTableName, referencedColumns, name: declared.name })), [
+    { resource: "pets", tableName: "pets", columns: ["clinic_vet"], referencedTableName: "vets", referencedColumns: ["id"], name: "pets_vet" }
+  ]);
+  assert.deepEqual(wrong.undeclared, []);
+
+  const undeclared = await checkForeignKeys({ knex, resources: [owners, petsResource()], tables: ["pets"] });
+  assert.deepEqual(undeclared, {
+    missing: [],
+    undeclared: [{ name: "", tableName: "pets", columns: ["owner_id"], referencedTableName: "owners", referencedColumns: ["id"] }]
+  });
+  assert.deepEqual((await checkForeignKeys({ knex, resources: [petsResource()], tables: [] })).undeclared, []);
+});