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

package/test/storedIntegers.mysql.test.js

@@ -0,0 +1,4 @@
+import { storedIntegerCases } from "./support/storedIntegerCases.js";
+
+// Non-id BIGINT columns read through a handle on MariaDB/MySQL.
+storedIntegerCases("mysql");

package/test/storedIntegers.postgres.test.js

@@ -0,0 +1,5 @@
+import { storedIntegerCases } from "./support/storedIntegerCases.js";
+
+// Non-id BIGINT columns read through a handle on PostgreSQL: run with TEST_DB_NAME (and the usual DB_HOST, DB_PORT,
+// DB_USER and DB_PASSWORD) naming a PostgreSQL database, and DB_CLIENT unset or pg.
+storedIntegerCases("postgres");

package/test/support/storedIntegerCases.js

@@ -0,0 +1,152 @@
+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 { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createTestResourceRuntime } from "../../src/test/index.js";
+
+// Whole numbers stored in BIGINT columns that are not ids (a counter, a byte count, a read position), read through a
+// handle on MariaDB/MySQL and on PostgreSQL alike. Both drivers answer BIGINT as text (mysql2 with the runtime's
+// bigNumberStrings, pg for every int8); a field of type "integer" reads back as a number on every handle read, and an
+// id field as text.
+
+const WORKSPACE = Object.freeze({ workspace: { id: "1" } });
+const RUNTIME_MYSQL = Object.freeze({ supportBigNumbers: true, bigNumberStrings: true, dateStrings: ["DATE"], timezone: "Z" });
+// The largest whole number a JavaScript number holds exactly (2^53 - 1), and the next odd one past it.
+const LARGEST_SAFE = "9007199254740991";
+const PAST_SAFE = "9007199254740993";
+
+// A PostgreSQL test on a run for another database, such as CI's MariaDB run, is left to the PostgreSQL run.
+const POSTGRES_ELSEWHERE = process.env.DB_CLIENT && process.env.DB_CLIENT !== "pg"
+  ? `a PostgreSQL test, on a ${process.env.DB_CLIENT} run`
+  : false;
+
+const counterResource = defineTableResource({
+  name: "counters",
+  tableName: "counters",
+  ownership: "workspace",
+  defaultSort: ["id"],
+  schema: {
+    id: { type: "id", primary: true },
+    workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+    total: { type: "integer", search: true },
+    readUpTo: { type: "integer", nullable: true, storage: { column: "read_up_to" } },
+    hiddenCount: { type: "integer", nullable: true, hidden: true, storage: { column: "hidden_count" } },
+    lastMessageId: { type: "id", nullable: true, storage: { column: "last_message_id" } }
+  }
+});
+const FIELDS = Object.freeze(["workspaceId", "total", "readUpTo", "hiddenCount", "lastMessageId"]);
+
+/** A MariaDB/MySQL database of the test's own beside TEST_DB_NAME, dropped after it. */
+async function mysqlKnex(context, suffix) {
+  const name = `${requireTestDatabase(process.env)}_${suffix}`;
+  const server = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 3306, user: process.env.DB_USER, password: process.env.DB_PASSWORD };
+  const admin = knexLib({ client: "mysql2", connection: server, pool: { min: 0, max: 1 } });
+  await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+  await admin.raw("CREATE DATABASE ??", [name]);
+  const knex = knexLib({ client: "mysql2", connection: { ...server, database: name, ...RUNTIME_MYSQL }, pool: { min: 0, max: 2 } });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+    await admin.destroy();
+  });
+  return knex;
+}
+
+/** A PostgreSQL schema of the test's own in TEST_DB_NAME, dropped after it. */
+async function postgresKnex(context, suffix) {
+  const database = requireTestDatabase(process.env);
+  const schema = `${database}_${suffix}_${process.pid}`;
+  const connection = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 5432, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database };
+  const admin = knexLib({ client: "pg", connection, pool: { min: 0, max: 1 } });
+  await admin.raw("DROP SCHEMA IF EXISTS ?? CASCADE", [schema]);
+  await admin.raw("CREATE SCHEMA ??", [schema]);
+  const knex = knexLib({ client: "pg", connection, searchPath: [schema], pool: { min: 0, max: 2 } });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP SCHEMA IF EXISTS ?? CASCADE", [schema]);
+    await admin.destroy();
+  });
+  return knex;
+}
+
+// The record fields a test compares: their values with their types.
+const typed = (record) => Object.fromEntries(
+  ["id", ...FIELDS].filter((field) => Object.hasOwn(record, field)).map((field) => [field, record[field]])
+);
+
+/**
+ * Registers the stored-integer tests on one database.
+ * @param {"mysql" | "postgres"} dialect
+ */
+function storedIntegerCases(dialect) {
+  const skip = dialect === "postgres" ? POSTGRES_ELSEWHERE : false;
+  const openKnex = dialect === "postgres" ? postgresKnex : mysqlKnex;
+
+  async function counters(context) {
+    const knex = await openKnex(context, "stored_ints");
+    await knex.schema.createTable("counters", (table) => {
+      table.bigIncrements("id");
+      table.bigInteger("workspace_id").nullable();
+      table.bigInteger("total").notNullable();
+      table.bigInteger("read_up_to").nullable();
+      table.bigInteger("hidden_count").nullable();
+      table.bigInteger("last_message_id").nullable();
+    });
+    const runtime = await createTestResourceRuntime({ knex });
+    const { counters: handle } = await runtime.own("counters.feature", [counterResource]);
+    return { knex, counters: handle };
+  }
+
+  test(`${dialect}: a non-id BIGINT field of type integer reads back as a number on every handle read; an id as text`, { skip }, async (context) => {
+    const { counters: handle } = await counters(context);
+    const options = { context: WORKSPACE };
+    const expected = { id: "1", workspaceId: "1", total: 5, readUpTo: Number(LARGEST_SAFE), hiddenCount: 3, lastMessageId: "11" };
+
+    const created = await handle.create({ workspaceId: "1", total: 5, readUpTo: Number(LARGEST_SAFE), hiddenCount: 3, lastMessageId: "11" }, options);
+    const { hiddenCount, ...visible } = expected;
+    assert.equal(hiddenCount, 3);
+    assert.deepEqual(typed(created), visible, "create answers the stored record without its hidden field");
+    assert.deepEqual(typed(await handle.get(created.id, { fields: FIELDS }, options)), expected);
+    assert.deepEqual((await handle.query({ fields: FIELDS, page: { size: 10 } }, options)).records.map(typed), [expected]);
+    assert.deepEqual((await handle.queryAll({ fields: FIELDS }, options)).map(typed), [expected]);
+    assert.deepEqual(typed(await handle.patch(created.id, { total: 6 }, options)), { ...visible, total: 6 });
+    assert.deepEqual(
+      (await handle.patchMany([{ id: created.id, total: 7 }], { ...options, returning: "records" })).map(typed),
+      [{ ...visible, total: 7 }]
+    );
+    assert.deepEqual(
+      (await handle.createMany([{ workspaceId: "1", total: 8 }], { ...options, returning: "records" })).map(typed),
+      [{ id: "2", workspaceId: "1", total: 8, readUpTo: null, lastMessageId: null }]
+    );
+    const locked = await handle.withTransaction(options, async (txOptions) => ({
+      lockMany: await handle.lockMany([created.id], { ...txOptions, fields: FIELDS }),
+      claim: await handle.claim({ filters: { total: 7 }, take: 1 }, { ...txOptions, fields: FIELDS })
+    }));
+    assert.deepEqual(locked.lockMany.map(typed), [{ ...expected, total: 7 }]);
+    assert.deepEqual(locked.claim.map(typed), [{ ...expected, total: 7 }]);
+    const totals = await handle.aggregate({
+      measures: { total: { sum: "total" }, highest: { max: "readUpTo" }, lowest: { min: "total" }, rows: { count: "*" } }
+    }, options);
+    assert.deepEqual(totals.map((row) => ({ ...row })), [{ total: 15, highest: Number(LARGEST_SAFE), lowest: 7, rows: 2 }]);
+  });
+
+  test(`${dialect}: past 2^53 a stored integer keeps its digits as text, never a rounded number; scopedQuery rows are the driver's text`, { skip }, async (context) => {
+    const { knex, counters: handle } = await counters(context);
+    const options = { context: WORKSPACE };
+    await knex("counters").insert({ workspace_id: 1, total: PAST_SAFE, read_up_to: LARGEST_SAFE, hidden_count: PAST_SAFE });
+
+    const [record] = await handle.queryAll({ fields: FIELDS }, options);
+    assert.deepEqual(typed(record), { id: "1", workspaceId: "1", total: PAST_SAFE, readUpTo: Number(LARGEST_SAFE), hiddenCount: PAST_SAFE, lastMessageId: null });
+
+    // A report's own builder answers what the driver read: BIGINT as text on both drivers, ids and counters alike,
+    // and a COUNT too, which both databases answer as a BIGINT.
+    const { query } = await handle.scopedQuery({ filters: {} }, options);
+    const rows = await query.select("id", "total", "read_up_to");
+    assert.deepEqual(rows.map((row) => ({ ...row })), [{ id: "1", total: PAST_SAFE, read_up_to: LARGEST_SAFE }]);
+    const { query: counting } = await handle.scopedQuery({ filters: {} }, options);
+    assert.deepEqual((await counting.count({ rows: "*" })).map((row) => ({ ...row })), [{ rows: "1" }]);
+  });
+}
+
+export { storedIntegerCases };

package/test/testHelpers.test.js

@@ -0,0 +1,290 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexFactory from "knex";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createPackageTestKnex, createTestResourceRuntime, expectEveryTableOwned, expectFlatQueries, expectScoped, startTestFeatures, TestDatabaseMissingError } 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 });
+
+const environment = Object.freeze({ TEST_DB_NAME: "catalogue_test" });
+
+test("expectFlatQueries() passes a path that reads its rows at once and fails one that reads them row by row", async () => {
+  const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  try {
+    await knex.schema.createTable("books", (table) => { table.increments("id"); table.integer("shelf"); table.string("title"); });
+    let shelf = 0;
+    // Each size gets a shelf of its own, so the sizes stay apart.
+    const seed = async (size) => {
+      shelf += 1;
+      await knex("books").insert(Array.from({ length: size }, (_, index) => ({ shelf, title: `Book ${index + 1}` })));
+      return shelf;
+    };
+    const atOnce = (seeded) => knex("books").where({ shelf: seeded }).orderBy("id").pluck("title");
+    assert.deepEqual(
+      await expectFlatQueries({ knex, environment, sizes: [3, 30], seed, run: atOnce }),
+      [{ size: 3, count: 1, chunkStatements: 0 }, { size: 30, count: 1, chunkStatements: 0 }]
+    );
+
+    const rowByRow = async (seeded) => {
+      const ids = await knex("books").where({ shelf: seeded }).pluck("id");
+      for (const id of ids) await knex("books").where({ id }).first("title");
+    };
+    await assert.rejects(expectFlatQueries({ knex, environment, sizes: [3, 30], seed, run: rowByRow }), (error) => {
+      assert.equal(error.name, "AssertionError");
+      assert.equal(error.message, [
+        "The statements grow with the rows: 4 at 3 rows, 31 at 30 rows.",
+        "Repeated most at 30 rows:",
+        "  30 x select `title` from `books` where `id` = ? limit ?",
+        "  1 x select `id` from `books` where `shelf` = ?"
+      ].join("\n"));
+      return true;
+    });
+
+    let seeded = false;
+    await assert.rejects(
+      expectFlatQueries({ knex, environment: {}, seed: () => { seeded = true; }, run: atOnce }),
+      TestDatabaseMissingError
+    );
+    assert.equal(seeded, false);
+    for (const sizes of [[10], [200, 10], [10, 10], [0, 10], [10, 20.5]]) {
+      await assert.rejects(expectFlatQueries({ knex, environment, sizes, seed, run: atOnce }), /at least two growing whole numbers/u);
+    }
+    await assert.rejects(expectFlatQueries({ knex, environment, seed }), /requires seed\(size\) and run\(seeded, size\)/u);
+    // Counted on a channel the path does not use (another Knex client than its own), it measures nothing.
+    const elsewhere = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+    try {
+      await assert.rejects(expectFlatQueries({ knex: elsewhere, environment, sizes: [3, 30], seed, run: atOnce }), /sent no statement at any size/u);
+    } finally {
+      await elsewhere.destroy();
+    }
+  } finally {
+    await knex.destroy();
+  }
+});
+
+async function createShelfFixture(t) {
+  const knex = await testKnex(t);
+  await knex.schema.createTable("books", (table) => {
+    table.increments("id");
+    table.integer("workspace_id");
+    table.string("title");
+  });
+  const books = defineTableResource({
+    name: "books",
+    tableName: "books",
+    ownership: "workspace",
+    schema: {
+      id: { type: "id", primary: true },
+      workspaceId: { type: "id", search: true, storage: { column: "workspace_id" } },
+      title: { type: "string", search: true }
+    }
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { books: handle } = await runtime.own("books.feature", [books]);
+  const systemContext = runtime.declareSystemScope("books.feature", "tests")("check scope");
+  return { knex, runtime, books: handle, systemContext };
+}
+
+test("expectFlatQueries() allows the later chunks a many-row write reports, and nothing else", async (t) => {
+  const { knex, books } = await createShelfFixture(t);
+  let workspace = 0;
+  const seed = () => {
+    workspace += 1;
+    return { context: { workspace: { id: String(workspace) } } };
+  };
+  const createInChunks = (options, size) => books.createMany(
+    Array.from({ length: size }, (_, index) => ({ title: `Book ${index}` })),
+    { ...options, chunkSize: 5 }
+  );
+  const counts = await expectFlatQueries({ knex, environment, sizes: [3, 30], seed, run: createInChunks });
+  assert.deepEqual(counts.map(({ size, chunkStatements }) => [size, chunkStatements]), [[3, 0], [30, 5]]);
+
+  const oneByOne = async (options, size) => {
+    for (let index = 0; index < size; index += 1) {
+      await books.create({ title: `Book ${index}` }, { ...options, returning: "none" });
+    }
+  };
+  await assert.rejects(expectFlatQueries({ knex, environment, sizes: [3, 30], seed, run: oneByOne }), /The statements grow with the rows/u);
+});
+
+test("expectScoped() passes a path that keeps to its workspace and fails one that reaches another", async (t) => {
+  const { books, systemContext } = await createShelfFixture(t);
+  const owners = [{ context: { workspace: { id: "1" } } }, { context: { workspace: { id: "2" } } }];
+  const seed = (owner) => books.createMany([{ title: "a" }, { title: "b" }], owner);
+  const handles = [books];
+
+  const result = await expectScoped({
+    environment,
+    handles,
+    systemContext,
+    owners,
+    seed,
+    run: (owner) => books.queryAll({}, owner)
+  });
+  assert.equal(result.length, 2);
+
+  await assert.rejects(
+    expectScoped({ environment, handles, systemContext, owners, seed, run: () => books.queryAll({}, { context: systemContext }) }),
+    /answered differently once the other owner's rows were seeded/u
+  );
+  await assert.rejects(
+    expectScoped({ environment, handles, systemContext, owners, seed, run: () => books.patchWhere({}, { title: "every" }, { context: systemContext, all: true }) }),
+    /changed books:\d+, a row of the other owner/u
+  );
+  await assert.rejects(
+    expectScoped({ environment, handles, systemContext, owners, seed, run: () => books.deleteWhere({ title: "b" }, { context: systemContext }) }),
+    /removed books:\d+, a row of the other owner/u
+  );
+  await assert.rejects(expectScoped({ environment: {}, handles, systemContext, owners, seed, run: seed }), TestDatabaseMissingError);
+});
+
+test("expectScoped() fails a report that joins another owner's table by name, though no row of it is in the answer", async (t) => {
+  const knex = await testKnex(t);
+  await knex.schema.createTable("visits", (table) => { table.increments("id"); table.integer("workspace_id"); table.string("person"); });
+  await knex.schema.createTable("people", (table) => { table.increments("id"); table.integer("workspace_id"); table.string("name"); table.string("business"); });
+  const owned = (name, schema) => defineTableResource({
+    name,
+    tableName: name,
+    ownership: "workspace",
+    schema: { id: { type: "id", primary: true }, workspaceId: { type: "id", search: true, storage: { column: "workspace_id" } }, ...schema }
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { visits } = await runtime.own("visits.feature", [owned("visits", { person: { type: "string" } })]);
+  const { people } = await runtime.own("people.feature", [owned("people", { name: { type: "string" }, business: { type: "string" } })]);
+  const systemContext = runtime.declareSystemScope("visits.feature", "tests")("check scope");
+  const owners = [{ context: { workspace: { id: "1" } }, business: "business A" }, { context: { workspace: { id: "2" } }, business: "business B" }];
+  const seed = async ({ context, business }) => {
+    await visits.create({ person: "Pat" }, { context, returning: "none" });
+    await people.create({ name: "Pat", business }, { context, returning: "none" });
+  };
+
+  // Knex: report - each visit with where its person works, joining the people table by name: it reads every owner's people
+  async function visitLabels(options) {
+    const { query } = await visits.scopedQuery({ alias: "v" }, options);
+    const rows = await query.join("people", "people.name", visits.column("person", "v")).select("people.name", "people.business").orderBy("people.id");
+    return rows.map((row) => `${row.name} at ${row.business}`);
+  }
+
+  // Each answer is text, so no row of the other owner's is in it by id; the second answer gained one.
+  await assert.rejects(
+    expectScoped({ environment, handles: [visits, people], systemContext, owners, seed, run: (owner) => visitLabels(owner) }),
+    (error) => {
+      assert.equal(error.name, "AssertionError");
+      assert.match(error.message, /answered differently once the other owner's rows were seeded/u);
+      assert.deepEqual(error.expected, ["Pat at business A"]);
+      assert.deepEqual(error.actual, ["Pat at business A", "Pat at business B"]);
+      return true;
+    }
+  );
+});
+
+test("expectScoped() compares the other owner's stored rows, so a changed hidden column or one outside the schema fails", async (t) => {
+  const knex = await testKnex(t);
+  await knex.schema.createTable("keys", (table) => {
+    table.increments("id");
+    table.integer("workspace_id");
+    table.string("label");
+    table.string("secret");
+    table.string("note");
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { keys } = await runtime.own("keys.feature", [defineTableResource({
+    name: "keys",
+    tableName: "keys",
+    ownership: "workspace",
+    schema: {
+      id: { type: "id", primary: true },
+      workspaceId: { type: "id", search: true, hidden: true, storage: { column: "workspace_id" } },
+      label: { type: "string", search: true },
+      secret: { type: "string", hidden: true }
+    }
+  })]);
+  const systemContext = runtime.declareSystemScope("keys.feature", "tests")("check scope");
+  const owners = [{ context: { workspace: { id: "1" } } }, { context: { workspace: { id: "2" } } }];
+  const seed = (owner) => keys.createMany([{ label: "a", secret: "s" }, { label: "b", secret: "s" }], { ...owner, returning: "none" });
+  const scoped = (run) => expectScoped({ environment, handles: [keys], systemContext, owners, seed, run });
+
+  const result = await scoped((owner) => keys.queryAll({}, owner));
+  assert.deepEqual(result.map(({ label }) => label).sort(), ["a", "b"]);
+  await assert.rejects(
+    scoped(() => keys.patchWhere({ label: "b" }, { secret: "rewritten" }, { context: systemContext, returning: "none" })),
+    /changed keys:\d+, a row of the other owner/u
+  );
+  // Knex: write - a column outside the table resource's schema, changed for every workspace
+  await assert.rejects(scoped(() => knex("keys").update({ note: "everyone's" })), /changed keys:\d+, a row of the other owner/u);
+});
+
+test("expectScoped() reads back only the other owner's rows, so a table past queryAll's row limit is checked too", async (t) => {
+  const { knex, books, systemContext } = await createShelfFixture(t);
+  await knex.batchInsert("books", Array.from({ length: 10_001 }, (_, index) => ({ workspace_id: 3, title: `Old ${index}` })), 500);
+  const owners = [{ context: { workspace: { id: "1" } } }, { context: { workspace: { id: "2" } } }];
+  const result = await expectScoped({
+    environment,
+    handles: [books],
+    systemContext,
+    owners,
+    seed: (owner) => books.createMany([{ title: "a" }, { title: "b" }], owner),
+    run: (owner) => books.queryAll({}, owner)
+  });
+  assert.deepEqual(result.map(({ title }) => title).sort(), ["a", "b"]);
+});
+
+test("expectEveryTableOwned() names each table no feature owns", async (t) => {
+  const { knex, runtime } = await createShelfFixture(t);
+  await expectEveryTableOwned({ knex, runtime, environment });
+  await knex.schema.createTable("loose_notes", (table) => table.increments("id"));
+  await assert.rejects(expectEveryTableOwned({ knex, runtime, environment }), /Tables no feature owns: loose_notes\./u);
+  await expectEveryTableOwned({ knex, runtime, infrastructureTables: ["loose_notes"], environment });
+});
+
+test("startTestFeatures() starts features in the order their requires give, on tables it creates, and boots them", async (t) => {
+  const knex = await testKnex(t);
+  const shelves = defineTableResource({
+    name: "shelves",
+    tableName: "shelves",
+    ownership: "workspace",
+    schema: { workspaceId: { type: "id", nullable: true, storage: { column: "workspace_id" } }, label: { type: "string", required: true } }
+  });
+  const order = [];
+  const ShelvesFeature = defineFeature({
+    id: "shelves",
+    owns: [shelves],
+    systemScope: "count every workspace's shelves",
+    provides: { shelfRecords: "shelves.records" },
+    setup: ({ resources, systemContext }) => {
+      order.push("shelves");
+      return {
+        shelfRecords: Object.freeze({
+          add: (label, options) => resources.shelves.create({ label }, options),
+          countAll: () => resources.shelves.aggregate({ measures: { shelves: { count: "id" } } }, { context: systemContext("count every shelf") })
+        })
+      };
+    }
+  });
+  // Listed first, it still starts after the feature whose records it requires, and its boot runs after every setup.
+  const ReportsFeature = defineFeature({
+    id: "reports",
+    requires: { shelfRecords: "shelves.records" },
+    provides: { reports: "reports" },
+    setup: ({ shelfRecords }) => {
+      order.push("reports");
+      return { reports: Object.freeze({ shelfCount: async () => (await shelfRecords.countAll())[0].shelves }) };
+    }
+  });
+  const Sealer = defineProvider({ id: "test.sealer", setup: () => ({}), boot: () => { order.push("boot"); } });
+  const { capabilities, resources, stop } = await startTestFeatures({
+    knex,
+    features: [ReportsFeature, Sealer, ShelvesFeature],
+    requires: { reports: "reports", shelfRecords: "shelves.records" },
+    createTables: true
+  });
+  t.after(stop);
+  await capabilities.shelfRecords.add("fiction", { context: { workspace: { id: "1" } } });
+  await capabilities.shelfRecords.add("poetry", { context: { workspace: { id: "2" } } });
+  assert.equal(await capabilities.reports.shelfCount(), 2);
+  assert.deepEqual(order, ["shelves", "reports", "boot"]);
+  assert.deepEqual(resources.ownedTables(), [{ name: "shelves", tableName: "shelves", featureId: "shelves" }]);
+});

package/test/workspaceScopeValue.test.js

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveWorkspaceScopeValue } from "../src/server/resourceHost.js";
+
+test("resolveWorkspaceScopeValue reads one workspace id from any of its sources", () => {
+  const all = {
+    workspace: { id: "1" },
+    requestMeta: {
+      resolvedWorkspaceContext: { workspace: { id: "1" } },
+      request: { workspace: { id: 1 } }
+    },
+    visibilityContext: { scopeOwnerId: "1" },
+    scopeValues: { workspaceId: 1 }
+  };
+  assert.equal(resolveWorkspaceScopeValue(all), "1");
+  assert.equal(resolveWorkspaceScopeValue({ workspace: { id: "2" } }), "2");
+  assert.equal(resolveWorkspaceScopeValue({ requestMeta: { resolvedWorkspaceContext: { workspace: { id: "3" } } } }), "3");
+  assert.equal(resolveWorkspaceScopeValue({ requestMeta: { request: { workspace: { id: "4" } } } }), "4");
+  assert.equal(resolveWorkspaceScopeValue({ scopeValues: { workspaceId: 5 } }), "5");
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: { visibility: "workspace_user", scopeKind: "workspace_user", scopeOwnerId: "6" } }), "6");
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } }), "7");
+  assert.equal(resolveWorkspaceScopeValue({}), null);
+  assert.equal(resolveWorkspaceScopeValue(), null);
+});
+
+test("resolveWorkspaceScopeValue ignores the owner of a visibility scope that is not a workspace's", () => {
+  const scopeValues = { workspaceId: "4" };
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: { visibility: "user", scopeOwnerId: "9" }, scopeValues }), "4");
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: { visibility: "public", scopeOwnerId: "9" } }), null);
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: { visibility: "workspace", scopeKind: "team", scopeOwnerId: "9" } }), null);
+  assert.equal(resolveWorkspaceScopeValue({ visibilityContext: null, scopeValues }), "4");
+});
+
+test("resolveWorkspaceScopeValue refuses a context that names two workspaces", () => {
+  assert.throws(
+    () => resolveWorkspaceScopeValue({
+      workspace: { id: "1" },
+      requestMeta: { resolvedWorkspaceContext: { workspace: { id: "2" } } }
+    }),
+    { message: "safety invariant: a context names two workspaces (1, 2); one execution acts on one workspace." }
+  );
+  assert.throws(
+    () => resolveWorkspaceScopeValue({
+      visibilityContext: { visibility: "workspace", scopeOwnerId: "3" },
+      scopeValues: { workspaceId: "4" }
+    }),
+    { message: "safety invariant: a context names two workspaces (3, 4); one execution acts on one workspace." }
+  );
+});

package/test/writeValues.mysql.test.js

@@ -0,0 +1,111 @@
+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 { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createTestResourceRuntime } from "../src/test/index.js";
+
+// Values a handle writes and compares on MySQL or MariaDB: timestamps a job sets itself, with milliseconds, on a
+// table that stores whole seconds, and a patch's onlyIf with no changes, compared in SQL.
+
+const WORKSPACE = Object.freeze({ workspace: { id: "1" } });
+const RUNTIME_MYSQL = Object.freeze({ supportBigNumbers: true, bigNumberStrings: true, dateStrings: ["DATE"], timezone: "Z" });
+
+const eventResource = defineTableResource({
+  name: "events",
+  tableName: "events",
+  ownership: "workspace",
+  defaultSort: ["id"],
+  schema: {
+    id: { type: "id", primary: true },
+    workspaceId: { type: "id", nullable: true, storage: { column: "workspace_id" } },
+    ownerUserId: { type: "id", nullable: true, storage: { column: "owner_user_id" } },
+    title: { type: "string", required: true },
+    secret: { type: "string", nullable: true, hidden: true },
+    createdAt: { type: "dateTime", temporalPrecision: 0, readOnly: true, storage: { column: "created_at" } },
+    updatedAt: { type: "dateTime", temporalPrecision: 0, readOnly: true, storage: { column: "updated_at" } }
+  }
+});
+
+/** A database of the test's own beside TEST_DB_NAME, with one events table storing whole seconds, dropped after it. */
+async function ownDatabase(context, suffix) {
+  const name = `${requireTestDatabase(process.env)}_${suffix}`;
+  const server = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 3306, user: process.env.DB_USER, password: process.env.DB_PASSWORD };
+  const admin = knexLib({ client: "mysql2", connection: server, pool: { min: 0, max: 1 } });
+  await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+  await admin.raw("CREATE DATABASE ??", [name]);
+  const knex = knexLib({ client: "mysql2", connection: { ...server, database: name, ...RUNTIME_MYSQL }, pool: { min: 0, max: 2 } });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+    await admin.destroy();
+  });
+  await knex.schema.createTable("events", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.integer("owner_user_id").nullable();
+    table.string("title").notNullable();
+    table.string("secret").nullable();
+    table.datetime("created_at", { precision: 0 }).notNullable();
+    table.datetime("updated_at", { precision: 0 }).notNullable();
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { events } = await runtime.own("events.feature", [eventResource]);
+  const job = runtime.declareSystemScope("events.feature", "import past events")("import the events");
+  return { knex, events, job };
+}
+
+// The stored timestamps of a row, as UTC text.
+async function storedTimes(knex, id) {
+  const row = await knex("events").where({ id }).first("created_at", "updated_at");
+  return [row.created_at.toISOString(), row.updated_at.toISOString()];
+}
+
+test("a job's own timestamps with milliseconds are stored to the whole second on a temporalPrecision 0 table", async (t) => {
+  const { knex, events, job } = await ownDatabase(t, "job_stamps");
+  const options = { context: job };
+  // A job's Date#toISOString(): its milliseconds are cut, as the handle cuts its own stamps, never rounded up.
+  const created = await events.create(
+    { workspaceId: "1", title: "imported", createdAt: "2026-01-02T03:04:05.956Z", updatedAt: "2026-01-02T03:04:06.250Z" },
+    options
+  );
+  assert.deepEqual(await storedTimes(knex, created.id), ["2026-01-02T03:04:05.000Z", "2026-01-02T03:04:06.000Z"]);
+  await events.patch(created.id, { title: "renamed", updatedAt: "2026-02-03T04:05:06.999Z" }, options);
+  assert.deepEqual(await storedTimes(knex, created.id), ["2026-01-02T03:04:05.000Z", "2026-02-03T04:05:06.000Z"]);
+
+  const ids = await events.createMany([
+    { workspaceId: "1", title: "a", createdAt: "2026-03-04T05:06:07.123Z", updatedAt: "2026-03-04T05:06:07.123Z" },
+    { workspaceId: "1", title: "b", createdAt: "2026-03-04T05:06:08.987Z", updatedAt: "2026-03-04T05:06:08.987Z" }
+  ], { ...options, returning: "ids" });
+  assert.deepEqual(await storedTimes(knex, ids[1]), ["2026-03-04T05:06:08.000Z", "2026-03-04T05:06:08.000Z"]);
+  await events.patchMany([{ id: ids[0], updatedAt: "2026-04-05T06:07:08.765Z" }], options);
+  assert.deepEqual(await storedTimes(knex, ids[0]), ["2026-03-04T05:06:07.000Z", "2026-04-05T06:07:08.000Z"]);
+  await events.patchWhere({ id: ids[1] }, { updatedAt: "2026-05-06T07:08:09.5Z" }, options);
+  assert.deepEqual(await storedTimes(knex, ids[1]), ["2026-03-04T05:06:08.000Z", "2026-05-06T07:08:09.000Z"]);
+
+  // A request's timestamps are the handle's, whole seconds too.
+  const requested = await events.create({ workspaceId: "1", title: "asked" }, { context: WORKSPACE });
+  const [requestCreated] = await storedTimes(knex, requested.id);
+  assert.match(requestCreated, /\.000Z$/u);
+});
+
+test("a patch with onlyIf and no changes compares in SQL: an id given as a number or as text, and a hidden field, match", async (t) => {
+  const { events } = await ownDatabase(t, "only_if");
+  const options = { context: WORKSPACE };
+  const event = await events.create({ title: "talk", ownerUserId: "7", secret: "s1" }, options);
+  // A record never answers the hidden secret, so only SQL can compare it.
+  assert.equal(Object.hasOwn(event, "secret"), false);
+  for (const missing of ["throw", "skip"]) {
+    const call = { ...options, missing };
+    // The id compares whether the caller gives it as a number or as text, however the record answers it.
+    assert.equal((await events.patch(event.id, {}, { ...call, onlyIf: { ownerUserId: 7 } }))?.id, event.id, missing);
+    assert.equal((await events.patch(event.id, {}, { ...call, onlyIf: { ownerUserId: "7" } }))?.id, event.id, missing);
+    assert.equal((await events.patch(event.id, {}, { ...call, onlyIf: { ownerUserId: "7", secret: "s1" } }))?.id, event.id, missing);
+    assert.equal(await events.patch(event.id, {}, { ...call, onlyIf: { ownerUserId: 8 } }), null, missing);
+    assert.equal(await events.patch(event.id, {}, { ...call, onlyIf: { secret: "other" } }), null, missing);
+    assert.equal(await events.patch(event.id, {}, { ...call, onlyIf: { secret: null } }), null, missing);
+    assert.equal(await events.patch(event.id, {}, { ...call, onlyIf: { title: "talk" }, returning: "id" }), event.id, missing);
+  }
+  // Another workspace's caller does not see the record, whatever onlyIf holds.
+  assert.equal(await events.patch(event.id, {}, { context: { workspace: { id: "2" } }, missing: "skip", onlyIf: { ownerUserId: 7 } }), null);
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.