@jskit-ai/resource-runtime 0.0.0-stage → 0.2.13

package/src/server/resourceRuntime.js

@@ -0,0 +1,300 @@
+import { readOnlyQueryBuilder } from "json-rest-api";
+import { toDatabaseDateTimeUtc } from "@jskit-ai/database-runtime/shared";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { isTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { callerOf, createSystemContext } from "./contexts.js";
+import { DuplicateOwnerError } from "./errors.js";
+import { createResourceHandle } from "./resourceHandle.js";
+import { resourceScopeOptions } from "./resourceHost.js";
+
+const DEFAULT_REQUEST_ROW_LIMIT = 10000;
+const DEFAULT_SERVER_PAGE_SIZE = 1000;
+const ENTRY_KEYS = Object.freeze(["resource", "rowPolicy", "hooks", "acceptsContributions", "normalizeId", "queryFields", "searchSchema"]);
+// Every table resource's datetime-utc fields are written as UTC database date-times.
+const WRITE_SERIALIZERS = Object.freeze({ "datetime-utc": toDatabaseDateTimeUtc });
+
+/**
+ * One `owns` entry as `{ resource, ...serverOnlyExtras }`.
+ * @param {unknown} entry
+ * @param {string} featureId
+ */
+function ownedEntry(entry, featureId) {
+  const normalized = isTableResource(entry) ? { resource: entry } : entry;
+  if (!isRecord(normalized) || !isTableResource(normalized.resource)) {
+    throw new TypeError(`Feature "${featureId}" owns entries must be table resources or { resource, ...extras } with a table resource.`);
+  }
+  for (const key of Object.keys(normalized)) {
+    if (!ENTRY_KEYS.includes(key)) {
+      throw new TypeError(`Feature "${featureId}" owns entry for "${normalized.resource.name}" does not take "${key}"; it takes ${ENTRY_KEYS.join(", ")}.`);
+    }
+  }
+  const hooks = normalized.hooks === undefined ? {} : normalized.hooks;
+  if (!isRecord(hooks) || Object.keys(hooks).some((key) => key !== "afterWrite")) {
+    throw new TypeError(`Feature "${featureId}" hooks for "${normalized.resource.name}" take only afterWrite.`);
+  }
+  // readable-check: allow method-probe - input validation: a row policy is the owner's optional function
+  if (normalized.rowPolicy !== undefined && typeof normalized.rowPolicy !== "function") {
+    throw new TypeError(`Feature "${featureId}" rowPolicy for "${normalized.resource.name}" must be a function.`);
+  }
+  return Object.freeze({
+    ...normalized,
+    hooks: Object.freeze({ ...hooks })
+  });
+}
+
+/**
+ * The filters of a resource's search that read another table: each `actualField` or `oneOf` path
+ * "resource.field" (or "a.b.field", whose last resource holds the field), as { filter, target, field }.
+ * @param {Record<string, any>} scopeOptions The resource's json-rest-api scope options.
+ */
+function crossTableFilters(scopeOptions) {
+  const declared = [
+    ...Object.entries(scopeOptions.searchSchema || {}),
+    ...Object.entries(scopeOptions.schema || {}).filter(([, field]) => isRecord(field?.search)).map(([name, field]) => [name, field.search])
+  ];
+  return declared.flatMap(([filter, entry]) => [entry?.actualField, ...(Array.isArray(entry?.oneOf) ? entry.oneOf : [])]
+    .filter((path) => typeof path === "string" && path.includes("."))
+    .map((path) => {
+      const segments = path.split(".");
+      return { filter, target: segments.at(-2), field: segments.at(-1) };
+    }));
+}
+
+/**
+ * Applies one row policy, the owner's or a contribution, inside its own
+ * parenthesised group, so whatever it writes (an orWhere among it) only narrows
+ * the rows ownership and the other policies left.
+ * The policy writes to a recorder; its calls replay inside `query.where(...)`.
+ * @param {Function} policy
+ * @param {Record<string, any>} args
+ */
+async function applyGrouped(policy, args) {
+  const calls = [];
+  const recorder = new Proxy({}, {
+    get(_target, method) {
+      if (method === "then") {
+        return undefined;
+      }
+      return (...callArgs) => {
+        calls.push([method, callArgs]);
+        return recorder;
+      };
+    }
+  });
+  const result = await policy({ ...args, query: recorder });
+  if (result === true && calls.length > 0) {
+    args.query.where(function contributedPredicates() {
+      for (const [method, callArgs] of calls) {
+        this[method](...callArgs);
+      }
+    });
+  }
+  return result;
+}
+
+/**
+ * The resource runtime behind `runtime.resources`: features own their tables
+ * through it (`own`), and a feature that declares a system scope gets its
+ * system context factory from it (`declareSystemScope`).
+ * @param {object} dependencies
+ * @param {import("./types.js").RuntimeJsonRestApi} dependencies.api The host from createResourceHost.
+ * @param {number} [dependencies.requestRowLimit] Rows queryAll() may read in a request context.
+ * @param {number} [dependencies.serverPageSize] Page size of queryAll()'s reads.
+ */
+function createResourceRuntime({ api, requestRowLimit = DEFAULT_REQUEST_ROW_LIMIT, serverPageSize = DEFAULT_SERVER_PAGE_SIZE }) {
+  const settings = Object.freeze({ requestRowLimit, serverPageSize });
+  /** @type {Map<string, { featureId: string, resource: object, acceptsContributions: boolean, contributions: Function[] }>} */
+  const ownedByName = new Map();
+  /** @type {Map<string, string>} */
+  const ownerByTable = new Map();
+  // Cross-table filters whose target table no feature owns yet: they are checked when its owner owns it.
+  const pendingCrossTableFilters = [];
+  /** @type {Map<string, string>} The system scope each feature declared. */
+  const scopeByFeature = new Map();
+
+  function claim(featureId, resource) {
+    const tableOwner = ownerByTable.get(resource.tableName);
+    if (tableOwner) {
+      throw new DuplicateOwnerError(`Feature "${featureId}" owns table "${resource.tableName}", which feature "${tableOwner}" already owns. One table has one owner.`);
+    }
+    if (ownedByName.has(resource.name) || api.resources[resource.name]) {
+      throw new DuplicateOwnerError(`Feature "${featureId}" owns resource "${resource.name}", a name another feature already registered.`);
+    }
+  }
+
+  // An owned table resource by name, or null: a handle shapes included records with it.
+  function resourceNamed(name) {
+    return ownedByName.get(name)?.resource ?? null;
+  }
+
+  // A SELECT-only builder over one of the feature's own tables, for a row policy's subqueries.
+  function ownTableReader(featureId, db) {
+    return function ownTable(name) {
+      const owned = ownedByName.get(name);
+      if (!owned || owned.featureId !== featureId) {
+        throw new TypeError(`ownTable("${name}"): a row policy reads only its own feature's tables, which are ${[...ownedByName].filter(([, entry]) => entry.featureId === featureId).map(([ownedName]) => ownedName).join(", ")}.`);
+      }
+      return readOnlyQueryBuilder(db(owned.resource.tableName), { resourceType: name });
+    };
+  }
+
+  // The owner's policy, then every contribution, each in its own group ANDed with ownership: a policy only narrows.
+  // Each gets who the call runs for as `caller` (see callerOf), its one way to tell: json-rest-api's own `system` flag
+  // is left out.
+  function composedRowPolicy(featureId, entry, contributions) {
+    if (!entry.rowPolicy && !entry.acceptsContributions) {
+      return undefined;
+    }
+    return async function ownedRowPolicy(jsonRestArgs) {
+      const args = { ...jsonRestArgs };
+      delete args.system;
+      const caller = callerOf(args.context);
+      if (entry.rowPolicy) {
+        const result = await applyGrouped(entry.rowPolicy, { ...args, caller, ownTable: ownTableReader(featureId, args.db) });
+        if (result !== true) {
+          return result;
+        }
+      }
+      for (const contribution of contributions) {
+        const result = await applyGrouped(contribution.policy, { ...args, caller, ownTable: ownTableReader(contribution.featureId, args.db) });
+        if (result !== true) {
+          return result;
+        }
+      }
+      return true;
+    };
+  }
+
+  function contributeRowPolicy(featureId, name, policy) {
+    const owned = ownedByName.get(name);
+    if (!owned) {
+      throw new TypeError(`Feature "${featureId}" contributes a row policy to "${name}", which no feature owns.`);
+    }
+    if (!owned.acceptsContributions) {
+      throw new TypeError(`Feature "${featureId}" contributes a row policy to "${name}", whose owner "${owned.featureId}" does not accept contributions.`);
+    }
+    if (typeof policy !== "function") {
+      throw new TypeError(`Feature "${featureId}" row policy for "${name}" must be a function.`);
+    }
+    owned.contributions.push(Object.freeze({ featureId, policy }));
+  }
+
+  /**
+   * Refuses, at startup, a cross-table filter on a field json-rest-api cannot search: one its target resource does
+   * not declare `indexed: true`, which json-rest-api otherwise refuses only at the first query. A filter whose
+   * target no feature owns yet waits for it.
+   * @param {ReadonlyArray<{ resource: Record<string, any> }>} entries The resources being owned now.
+   * @param {ReadonlyArray<Record<string, any>>} scopes Their json-rest-api scope options, in the same order.
+   */
+  function checkCrossTableFilters(entries, scopes) {
+    const owning = new Map(entries.map(({ resource }) => [resource.name, resource]));
+    const targetNamed = (name) => owning.get(name) || ownedByName.get(name)?.resource;
+    const filters = [
+      ...pendingCrossTableFilters.splice(0),
+      ...entries.flatMap(({ resource }, index) => crossTableFilters(scopes[index]).map((filter) => ({ ...filter, source: resource.name })))
+    ];
+    for (const filter of filters) {
+      const target = targetNamed(filter.target);
+      if (!target) {
+        pendingCrossTableFilters.push(filter);
+        continue;
+      }
+      if (target.schema?.[filter.field]?.indexed !== true) {
+        throw new TypeError(
+          `Table resource "${filter.source}" filters "${filter.filter}" on ${filter.target}.${filter.field}, which ` +
+          `"${filter.target}" does not declare indexed: true. A cross-table filter reads another table by that field: ` +
+          `give the field indexed: true and its column a database index, or filter on a field of "${filter.source}".`
+        );
+      }
+    }
+  }
+
+  /**
+   * Registers the feature as the one owner of each resource and answers their
+   * handles, by resource name. The answer's contributeRowPolicy(name, policy)
+   * narrows another feature's resource whose owner accepts contributions.
+   * @param {string} featureId
+   * @param {ReadonlyArray<object>} owns
+   */
+  async function own(featureId, owns) {
+    const entries = owns.map((entry) => ownedEntry(entry, featureId));
+    const names = new Set();
+    for (const { resource } of entries) {
+      if (names.has(resource.name)) {
+        throw new DuplicateOwnerError(`Feature "${featureId}" lists resource "${resource.name}" twice.`);
+      }
+      names.add(resource.name);
+      claim(featureId, resource);
+    }
+    const contributions = entries.map(() => []);
+    const scopes = entries.map((entry, index) => resourceScopeOptions(entry.resource, {
+      writeSerializers: WRITE_SERIALIZERS,
+      normalizeId: entry.normalizeId,
+      rowPolicy: composedRowPolicy(featureId, entry, contributions[index]),
+      searchSchema: entry.searchSchema,
+      queryFields: entry.queryFields
+    }));
+    checkCrossTableFilters(entries, scopes);
+    const handles = {};
+    for (const [index, entry] of entries.entries()) {
+      const { resource } = entry;
+      ownedByName.set(resource.name, {
+        featureId,
+        resource,
+        acceptsContributions: entry.acceptsContributions === true,
+        contributions: contributions[index]
+      });
+      ownerByTable.set(resource.tableName, featureId);
+      await api.addResource(resource.name, scopes[index]);
+      handles[resource.name] = createResourceHandle({ api, resource, hooks: entry.hooks, settings, resourceNamed });
+    }
+    Object.defineProperty(handles, "contributeRowPolicy", {
+      value: (name, policy) => contributeRowPolicy(featureId, name, policy),
+      enumerable: false
+    });
+    return Object.freeze(handles);
+  }
+
+  /** Every owned table, with its resource name and owning feature. */
+  function ownedTables() {
+    return [...ownedByName].map(([name, { featureId, resource }]) => Object.freeze({ name, tableName: resource.tableName, featureId }));
+  }
+
+  /**
+   * Records that the feature works across every workspace and user, and answers its system context factory, the only
+   * way to a system context: each call names its reason, so every place that skips the ownership scope says why. A
+   * feature declares one scope; declaring it again answers another factory for it.
+   * @param {string} featureId
+   * @param {string} systemScope Why the feature works across every workspace and user.
+   */
+  function declareSystemScope(featureId, systemScope) {
+    const scope = typeof systemScope === "string" ? systemScope.trim() : "";
+    if (!scope) {
+      throw new TypeError(`Feature "${featureId}" systemScope must say why it works across every workspace and user.`);
+    }
+    if (scopeByFeature.has(featureId) && scopeByFeature.get(featureId) !== scope) {
+      throw new TypeError(`Feature "${featureId}" declares one system scope, and it already declared "${scopeByFeature.get(featureId)}".`);
+    }
+    scopeByFeature.set(featureId, scope);
+    return function systemContext(reason) {
+      if (typeof reason !== "string" || !reason.trim()) {
+        throw new TypeError(`Feature "${featureId}" systemContext(reason) needs the reason this work reads or writes every workspace's rows.`);
+      }
+      return createSystemContext({ feature: featureId, systemScope: scope, reason: reason.trim() });
+    };
+  }
+
+  /** Every feature that declared a system scope, with the scope. */
+  function systemScopes() {
+    return [...scopeByFeature].map(([featureId, systemScope]) => Object.freeze({ featureId, systemScope }));
+  }
+
+  return Object.freeze({
+    own,
+    ownedTables,
+    declareSystemScope,
+    systemScopes
+  });
+}
+
+export { DEFAULT_REQUEST_ROW_LIMIT, DEFAULT_SERVER_PAGE_SIZE, createResourceRuntime };

package/src/server/standaloneResources.js

@@ -0,0 +1,49 @@
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { DuplicateOwnerError } from "./errors.js";
+import { createResourceHost } from "./resourceHost.js";
+import { createResourceRuntime } from "./resourceRuntime.js";
+
+// The resource runtime a JSKIT server built on each Knex client, so standalone resources never own one of its tables.
+const serverRuntimes = new WeakMap();
+
+/**
+ * Records the resource runtime a JSKIT server built on its Knex client.
+ * @param {object} knex
+ * @param {import("./types.js").ResourceRuntime} runtime
+ */
+// readable-check: allow module-registry - safety invariant: each table has one owner; standalone resources run outside any container, so they find the server's runtime by the Knex client both use, held weakly
+function registerServerRuntime(knex, runtime) {
+  serverRuntimes.set(knex, runtime);
+}
+
+/**
+ * Tables owned outside a JSKIT server, for code such as a command-line script: a resource runtime of its own on the
+ * application's Knex, with the handles of the tables it owns and, when it declares a system scope, its system
+ * context factory. A JSKIT application owns its tables through a feature instead, so each table has one owner: on
+ * the Knex client of a JSKIT server, a table one of its features owns is refused here. (A second Knex client on the
+ * same database is not recognised; code inside a server uses its features' handles.)
+ * @param {object} options
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} options.knex The application's Knex client.
+ * @param {string} options.feature The owner's name, as a feature's id.
+ * @param {ReadonlyArray<object>} options.owns The table resources it owns, as a feature's `owns`.
+ * @param {string} [options.systemScope] Why it works across every workspace and user.
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [options.logger]
+ */
+async function createStandaloneResources({ knex, feature, owns, systemScope, logger = silentLogger }) {
+  const runtime = createResourceRuntime({ api: await createResourceHost({ knex, logger }) });
+  const resources = await runtime.own(feature, owns);
+  const served = new Map((serverRuntimes.get(knex)?.ownedTables() ?? []).map(({ tableName, featureId }) => [tableName, featureId]));
+  const taken = runtime.ownedTables().find(({ tableName }) => served.has(tableName));
+  if (taken) {
+    throw new DuplicateOwnerError(
+      `Standalone resources "${feature}" own table "${taken.tableName}", which feature "${served.get(taken.tableName)}" of ` +
+      "this server already owns. One table has one owner: inside a server, use that feature's handles."
+    );
+  }
+  return Object.freeze({
+    resources,
+    ...(systemScope === undefined ? {} : { systemContext: runtime.declareSystemScope(feature, systemScope) })
+  });
+}
+
+export { createStandaloneResources, registerServerRuntime };

package/src/server/types.js

@@ -0,0 +1,49 @@
+// The types of the resource runtime: `runtime.resources`, its handles and contexts.
+
+/**
+ * The json-rest-api host createResourceHost builds. Its Knex plugin adds
+ * `knex.helpers.getStorageAdapter(scopeName)`: a registered resource's table
+ * query, id column and field columns.
+ * @typedef {Awaited<ReturnType<typeof import("./resourceHost.js").createResourceHost>> & {
+ *   knex: { instance: import("knex").Knex, helpers: { getStorageAdapter(scopeName: string): NonNullable<import("json-rest-api").HookContext["storageAdapter"]> } }
+ * }} RuntimeJsonRestApi
+ */
+
+/**
+ * One of `api.resources`: json-rest-api's resource and its methods. query()
+ * and delete() take any params, because the transitional readers pass params
+ * json-rest-api does not declare.
+ * @typedef {import("json-rest-api").RuntimeResource
+ *   & Omit<import("json-rest-api").ResourceCoreMethods, "query" | "delete">
+ *   & {
+ *     query(params?: object, context?: object): Promise<any>,
+ *     delete(params: object, context?: object): Promise<void>
+ *   }} JsonRestResource
+ */
+
+/**
+ * The `runtime.resources` capability.
+ * @typedef {ReturnType<typeof import("./resourceRuntime.js").createResourceRuntime>} ResourceRuntime
+ */
+
+/**
+ * One owned table's handle: its reads, writes, locks and read-only escape hatch,
+ * each scoped by the call's `options.context`.
+ * @typedef {ReturnType<typeof import("./resourceHandle.js").createResourceHandle>} ResourceHandle
+ */
+
+/**
+ * The options every handle call takes last: the caller's context (an action's,
+ * or a system context) and the transaction to join.
+ * @typedef {{ context?: object | null, trx?: object | null }} ResourceCallOptions
+ */
+
+/**
+ * A context for work across every workspace and user, from `systemContext(reason)`.
+ * `forWorkspace(id)`, `forUser(id)` and `forWorkspaceUser(workspaceId, userId)` derive the
+ * context of one workspace, one user, or one user in one workspace; each takes `{ actorId }` last for work done
+ * for one person, whom audit fields then record (`resolveAuditActorId`); it signs no one in.
+ * @typedef {ReturnType<typeof import("./contexts.js").createSystemContext>} SystemContext
+ */
+
+export {};

package/src/test/expectFlatQueries.js

@@ -0,0 +1,117 @@
+import { AssertionError } from "node:assert";
+import diagnosticsChannel from "node:diagnostics_channel";
+import {
+  countQueries,
+  countRuntimeQueries,
+  requireTestDatabase
+} from "@jskit-ai/database-runtime/server/testDatabases";
+import { MANY_ROW_CHANNEL } from "../server/resourceHandle.js";
+
+const REPEATED_STATEMENTS_SHOWN = 5;
+// A quoted SQL string, written as a string so that source scanners that skip quoted text keep their place.
+const SQL_STRING_LITERAL = new RegExp("'(?:[^']|'')*'", "gu");
+
+/** A statement with its values taken out, so the same statement for another row reads the same. */
+function normalizedStatement(sql) {
+  return sql
+    .replace(SQL_STRING_LITERAL, "?")
+    .replace(/\$\d+/gu, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/gu, "?")
+    .replace(/\(\s*\?(?:\s*,\s*\?)+\s*\)/gu, "(?, ...)");
+}
+
+function mostRepeated(queries) {
+  const counts = new Map();
+  for (const query of queries) {
+    const statement = normalizedStatement(query);
+    counts.set(statement, (counts.get(statement) || 0) + 1);
+  }
+  return [...counts].sort((left, right) => right[1] - left[1]).slice(0, REPEATED_STATEMENTS_SHOWN);
+}
+
+function requireSizes(sizes) {
+  const valid = Array.isArray(sizes) && sizes.length >= 2 &&
+    sizes.every((size, index) => Number.isInteger(size) && size > 0 && (index === 0 || size > sizes[index - 1]));
+  if (!valid) {
+    throw new TypeError("expectFlatQueries sizes must be at least two growing whole numbers of rows, such as [10, 200].");
+  }
+}
+
+/**
+ * Counts the statements `work` sends, and the extra statements the many-row
+ * calls among them report for their chunks after the first.
+ * @param {import("knex").Knex | import("knex").Knex.Transaction | null} knex
+ * @param {() => unknown} work
+ */
+async function measure(knex, work) {
+  const calls = [];
+  const listen = (message) => {
+    calls.push(message);
+  };
+  diagnosticsChannel.subscribe(MANY_ROW_CHANNEL, listen);
+  try {
+    const { count, queries } = knex ? await countQueries(knex, work) : await countRuntimeQueries(work);
+    const chunkStatements = calls.reduce((total, { rows, chunkSize }) => total + Math.max(0, Math.ceil(rows / chunkSize) - 1), 0);
+    return { count, chunkStatements, queries };
+  } finally {
+    diagnosticsChannel.unsubscribe(MANY_ROW_CHANNEL, listen);
+  }
+}
+
+/**
+ * Fails when a path's statements grow with its rows. For each size, smallest first, it seeds that many rows with
+ * `seed(size)`, then runs `run(seeded, size)` and counts the statements sent meanwhile: through `knex` when given (its
+ * transactions' included), else through the runtime of a server the test booted, as countRuntimeQueries() does. The
+ * extra statements of a many-row write's later chunks, which its handle reports, are allowed, so no number is
+ * hand-picked. A flat path then sends as many statements at every size; a path that reads or writes row by row sends
+ * more at each, and one that sends none at every size was counted on the wrong channel and fails too. On failure the message gives every count and the statements repeated most at the largest size. Its seed
+ * keeps the sizes apart (a workspace or user of their own, or a fresh database).
+ * @template S
+ * @param {object} options
+ * @param {number[]} [options.sizes] Growing row counts; 10 and 200 when absent.
+ * @param {(size: number) => S | Promise<S>} options.seed
+ * @param {(seeded: S, size: number) => unknown} options.run
+ * @param {import("knex").Knex | import("knex").Knex.Transaction | null} [options.knex]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The test's environment, such as `process.env`.
+ * @returns {Promise<Array<{ size: number, count: number, chunkStatements: number }>>} The count at each size, and how
+ *   many of its statements were later chunks of many-row writes.
+ */
+async function expectFlatQueries({ sizes = [10, 200], seed, run, knex = null, environment }) {
+  requireTestDatabase(environment);
+  requireSizes(sizes);
+  // readable-check: allow method-probe - input validation: seed and run are the caller's own functions
+  if (typeof seed !== "function" || typeof run !== "function") {
+    throw new TypeError("expectFlatQueries requires seed(size) and run(seeded, size) functions.");
+  }
+  const measured = [];
+  for (const size of sizes) {
+    const seeded = await seed(size);
+    measured.push({ size, ...await measure(knex, () => run(seeded, size)) });
+  }
+  const counts = measured.map(({ size, count, chunkStatements }) => ({ size, count, chunkStatements }));
+  const [smallest] = measured;
+  const largest = measured.at(-1);
+  // A data path that sends nothing at every size was counted on the wrong channel, so it would pass unmeasured.
+  if (measured.every(({ count }) => count === 0)) {
+    throw new AssertionError({
+      message: "The path sent no statement at any size, so nothing was measured: pass the test's knex when its features " +
+        "run on it (startTestFeatures, createTestResourceRuntime), or the path never reached the database."
+    });
+  }
+  const growing = ({ count, chunkStatements }) => count - chunkStatements > smallest.count - smallest.chunkStatements;
+  if (measured.some(growing)) {
+    const described = counts.map(({ size, count, chunkStatements }) =>
+      `${count} at ${size} rows${chunkStatements > 0 ? ` (${chunkStatements} of them later chunks)` : ""}`);
+    const repeated = mostRepeated(largest.queries).map(([statement, times]) => `  ${times} x ${statement}`);
+    throw new AssertionError({
+      message: [
+        `The statements grow with the rows: ${described.join(", ")}.`,
+        `Repeated most at ${largest.size} rows:`,
+        ...repeated
+      ].join("\n")
+    });
+  }
+  return counts;
+}
+
+export { expectFlatQueries };

package/src/test/expectScoped.js

@@ -0,0 +1,111 @@
+import { AssertionError, deepStrictEqual } from "node:assert";
+import { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+
+// The other owner's rows are read back by id, this many ids per read.
+const IDS_PER_READ = 1000;
+
+// The ids each handle's table holds, read through the system context in one statement per table however many rows
+// it has (queryAll would refuse a table past its row limit).
+async function idsOf(handles, systemContext) {
+  const ids = new Map();
+  for (const handle of handles) {
+    const { query } = await handle.scopedQuery({}, { context: systemContext });
+    ids.set(handle, new Set((await query.pluck(handle.column("id"))).map(String)));
+  }
+  return ids;
+}
+
+// Every column of the handle's table, as its scoped query names the table.
+function everyColumn(handle) {
+  const id = handle.column("id");
+  return `${id.slice(0, id.length - handle.column("id", "").length - 1)}.*`;
+}
+
+// The rows with these ids of each handle's table, read through the system context, by `${resource}:${id}`. They are
+// the stored rows, not records, so a hidden or defaultExclude field, or a column outside the schema, is compared too.
+async function rowsOf(idsByHandle, systemContext) {
+  const rows = new Map();
+  for (const [handle, ids] of idsByHandle) {
+    const list = [...ids];
+    for (let start = 0; start < list.length; start += IDS_PER_READ) {
+      const { query } = await handle.scopedQuery({ filters: { id: list.slice(start, start + IDS_PER_READ) } }, { context: systemContext });
+      for (const { __id: id, ...row } of await query.select({ __id: handle.column("id") }, everyColumn(handle))) {
+        rows.set(`${handle.name}:${id}`, row);
+      }
+    }
+  }
+  return rows;
+}
+
+/**
+ * Fails when a path reaches another owner's rows. It seeds owner A and runs the
+ * path as A; then it seeds owner B and runs the path as A again. It fails when
+ * the path removed or changed a row seeded for B, and when its second answer
+ * differs from its first, so it catches a report that sums, counts or joins B's
+ * rows, not only one that returns them. B's rows are read by id through the
+ * system context, from the handles of the tables the path touches, as stored:
+ * every column, hidden and defaultExclude fields included. The path
+ * runs twice, so it answers the same for the same rows: a write answers what
+ * repeats, such as the ids it changed or each refusal, not a fresh id or time.
+ * @template T
+ * @param {object} options
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The test's environment, such as `process.env`.
+ * @param {ReadonlyArray<import("../server/types.js").ResourceHandle>} options.handles
+ * @param {object} options.systemContext A system context, for reading every owner's rows.
+ * @param {[T, T]} options.owners What seed and run receive for owners A and B, such as `{ context }` of each.
+ * @param {(owner: T) => unknown} options.seed Seeds one owner's rows.
+ * @param {(owner: T) => unknown} options.run The path, run as owner A.
+ * @returns {Promise<unknown>} The path's answer.
+ */
+async function expectScoped({ environment, handles, systemContext, owners, seed, run }) {
+  requireTestDatabase(environment);
+  if (!Array.isArray(handles) || handles.length < 1) {
+    throw new TypeError("expectScoped needs the handles of the tables the path touches.");
+  }
+  if (!Array.isArray(owners) || owners.length !== 2) {
+    throw new TypeError("expectScoped needs two owners, [ownerA, ownerB].");
+  }
+  // readable-check: allow method-probe - input validation: seed and run are the caller's own functions
+  if (typeof seed !== "function" || typeof run !== "function") {
+    throw new TypeError("expectScoped requires seed(owner) and run(owner) functions.");
+  }
+  const [ownerA, ownerB] = owners;
+  await seed(ownerA);
+  const alone = await run(ownerA);
+
+  const before = await idsOf(handles, systemContext);
+  await seed(ownerB);
+  const added = new Map();
+  for (const [handle, ids] of await idsOf(handles, systemContext)) {
+    added.set(handle, new Set([...ids].filter((id) => !before.get(handle).has(id))));
+  }
+  const otherRows = await rowsOf(added, systemContext);
+  if (otherRows.size < 1) {
+    throw new TypeError("expectScoped: seeding owner B added no rows to the handles' tables, so there is nothing to protect.");
+  }
+  const result = await run(ownerA);
+
+  const after = await rowsOf(added, systemContext);
+  for (const [key, row] of otherRows) {
+    if (!after.has(key)) {
+      throw new AssertionError({ message: `The path removed ${key}, a row of the other owner.` });
+    }
+    try {
+      deepStrictEqual(after.get(key), row);
+    } catch {
+      throw new AssertionError({ message: `The path changed ${key}, a row of the other owner.`, actual: after.get(key), expected: row });
+    }
+  }
+  try {
+    deepStrictEqual(result, alone);
+  } catch {
+    throw new AssertionError({
+      message: "The path answered differently once the other owner's rows were seeded, so it reads them.",
+      actual: result,
+      expected: alone
+    });
+  }
+  return result;
+}
+
+export { expectScoped };