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

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## Unreleased
+
+- Depends on json-rest-api 3.1.0 exactly (from 3.0.1), from the registry with its published integrity: `lockMode: "noKeyUpdate"`, ON CONFLICT on the matching unique index's exact columns, the PostgreSQL merge race on an uncommitted insert, and the `xid8` field type the change horizon reads.
+- Tests pin three paths the guide now documents: a shared row of a `workspace_or_shared` table is written in the owner's root system context, naming `workspaceId: null`, also inside a request's transaction, and never from a request or a derived job context (`forUser` is refused 403); a job's `actorId` never moves its scope, while a row policy may hold a job done for a person to that person's rows; and a hand route's `request.callOptions()` scopes user, workspace and workspace_user tables as the same request's action does, with no user scope when no one is signed in.
+- A table resource reads an xid8 change stamp through an `xid8` field, json-rest-api 3.1.0's type for PostgreSQL's transaction id: decimal text below 2^64, which filters such as `changedSince: { type: "xid8", actualField: "changed", filterOperator: ">=" }` compare as transaction ids in SQL. A malformed cursor is refused as `REST_API_VALIDATION` before any statement, where a string field sent it to PostgreSQL (22P02), and the field is refused at registration on MySQL, MariaDB and SQLite. With `changeHorizon()`, a read of what changed since goes through the handle, where it was a hand-written scoped query; the data-access guide's "What changed since" gives the migration (an xid8 column a trigger stamps on every insert and update), the field, the filters and the read.
+- Every handle has `changeHorizon(options)`: PostgreSQL's snapshot horizon, `pg_snapshot_xmin(pg_current_snapshot())`, as decimal text, read in the caller's transaction when there is one, with the call's context checked as for every call. Every transaction below it had finished when it was read, so a read of what changed starts there: a later read of the rows whose xid8 change stamp is at or above it finds what an open transaction wrote, a row whose id was taken before its transaction committed and a changed older row included, which "past the highest id seen" misses. It reads no row, where it was a hand-written `knex.raw` beside the handle. MySQL, MariaDB and SQLite stamp no row with its transaction: there it throws `UnsupportedDatabaseError` (code `RESOURCE_DATABASE_UNSUPPORTED`, exported from `./server`) before any statement. `changes.postgres.test.js` proves the catch-up with a writer still open at the horizon.
+- **Security.** A table resource with ownership `system` (rows of no workspace or user, such as an agent's runs or a server's leases) answers only a system context. Every call with a request's context, a job context derived with `forWorkspace`, `forUser` or `forWorkspaceUser`, or none throws `SystemContextRequiredError` (code `RESOURCE_SYSTEM_CONTEXT_REQUIRED`, exported from `./server`) before any statement: such a table has no ownership predicate, so that context reached every workspace's rows. The table gets no autofilter preset; the owner's own methods decide what a request may see.
+- `lock`, `lockMany`, `lockWhere`, `claim`, `lockOrCreate` and `patchWhere` take `lockMode: "update"` (the default, `FOR UPDATE`) or `"noKeyUpdate"`, passed on to json-rest-api: on PostgreSQL `FOR NO KEY UPDATE`, which still keeps every other lock and write of the row out but lets another transaction insert a row that references it; MySQL, MariaDB and SQLite lock as for `"update"`. Another value throws a TypeError naming the resource and the method before anything runs (`notes.lock() lockMode is "update" (the default) or "noKeyUpdate". Received: "share"`).
+- `./test` re-exports database-runtime's `createPackageTestKnex(t, { environment })`. The package's own data tests run on it, so a `DB_CLIENT=pg` run proves their paths on PostgreSQL, each test in a schema of its own; `locks.postgres.test.js` adds PostgreSQL's concurrent cases with real transactions: two `patchWhere` calls racing for one row, `deleteWhere` against `patchWhere`, a `patchWhere` that waited writing only rows that still match, two `claim` workers taking different rows, `lockMany` and `lockWhere` waiting for a holder, upserts of one key behind an uncommitted insert, a deadlock victim running again, `retryLostInsertRace`, `findOrCreate` and `lockOrCreate` first uses at once, and `lockMode: "noKeyUpdate"`. CI runs them, and the data tests of this package and crud-core, on PostgreSQL 17.
+- Tests pin how a whole number stored in a BIGINT column that is not an id (a counter, a read position) reads through a handle, on MariaDB/MySQL and PostgreSQL (`storedIntegers.mysql.test.js` and `storedIntegers.postgres.test.js`, the latter in CI's PostgreSQL job). Both drivers read BIGINT as text, and a field of type `integer` answers a number on create, get, query, queryAll, patch, createMany, patchMany, lockMany, claim, aggregate and a hidden-field read, while an id field answers text. Past 2^53 − 1 the digits stay text, never a rounded number, and a `scopedQuery` row is the driver's text. No behaviour changes.
+- `./server` exports `checkForeignKeys({ knex, resources, tables })`, which compares the table resources' declared `foreignKeys` (each field mapped to its column as json-rest-api stores it) with the keys the database holds: `missing` lists a declared key the database lacks, `undeclared` a key of one of `tables` that nothing declares. `jskit test --databases` runs it once per run on the prepared test database; it never runs at boot. A declared `foreignKeys` reaches the json-rest-api resource unchanged; json-rest-api 3.0.1 only keeps it for its table helpers.
+- **Security.** A handle answers `joinSource({ alias, filters }, options)`: `{ query, column }`, the caller's scoped rows under the alias (ownership, the row policy and the filters applied) with the stored columns a read answers, never a hidden one, and `column(field)`, which refuses a hidden field. `withoutHiddenFields` hands another feature no other query builder: a method answering one, at once or inside its answer, is refused outside a system context with a TypeError naming the method and pointing at `joinSource`. A join source an owner built on `scopedQuery()` selected every column, so `source.query.select(source.column("publicToken"))` read another feature's hidden values; such a source becomes the handle's `joinSource({ alias }, options)`.
+- **Security.** `withoutHiddenFields` refuses a call whose `fields`, in any record it takes (a list, names separated by commas or a sparse fieldset), names a hidden field of the tables its owner owns, whatever the method. Only the seven standard reads refused one: a method `decorateRepository` adds that forwards the caller's `fields` answered the field stripped, as undefined, which a caller used as a value (a token in an email link). A system context, or one it derived, counts in whichever record the call takes, where only the last one counted.
+- `withoutHiddenFields` refuses owned tables of which one hides a field and another shows a field of the same name, with a TypeError naming both, when the feature's repository is built: it strips hidden fields by name, so the visible field never reached another feature. Hide it in both, or rename one.
+- Runs on json-rest-api 3.0.1 (from 3.0.0), exactly. A handle's `createMany` with `onConflict: { action: "merge" }` inside a transaction that read before another transaction committed the same key no longer fails as forbidden ("the record these conflict keys match cannot be changed by the caller") on MySQL and MariaDB, so two first registrations of one email at once both land; and a merge whose late matched row it left unchanged answers that row instead of empty data. PostgreSQL and SQLite behave as before.
+- `expectScoped` compares the other owner's stored rows, every column read through the system context's scoped query, where it compared the records a handle answers. A path that changed only a hidden or `defaultExclude` field of another owner's row (a `patchWhere` under a system context with `returning: "none"`), or a column outside the table resource's schema, passed.
+- `@jskit-ai/database-runtime` is a required peer dependency at the same version, where it was a dependency: the application holds one copy of the table runtime, since a nested copy brings its own error classes and transactions.
+- `./server` also exports `isSystemContext(context)` and the runtime's defaults, `DEFAULT_REQUEST_ROW_LIMIT` and `DEFAULT_SERVER_PAGE_SIZE`; `./test` re-exports database-runtime's `TestDatabaseMissingError` beside `requireTestDatabase`; `./server/types` holds the types of `runtime.resources`, its handles, call options and system contexts.
+- `delete`, `deleteWhere` and `createMany` refuse `lockVersion` and `onlyIf`, and `patchMany` and `patchWhere` refuse `lockVersion`, with a TypeError naming the resource, the method and the key and saying what to do instead (`notes.delete() cannot compare lockVersion, so it refuses rather than write without them. …`). They ignored them, so a delete meant to apply only to an unchanged record deleted it whatever it held. A delete compares in a transaction (`lock()`, compare, delete), `deleteWhere` in its filters, and a many-row patch with `onlyIf` on the lock version field.
+- A `patch` with `onlyIf` and no changes compares onlyIf in SQL, on the table as `scopedQuery` gives it, as the UPDATE of a patch with changes does: it compared the record a read answered, with strict equality, so an id given as a number never matched the text the record answers, and a hidden field, which no read answers, never matched at all. It refuses an onlyIf field that is the id or not stored, and a value other than a scalar, a Date or null, as that UPDATE does. A `patch` with `lockVersion` or `onlyIf` locks only the lock version, since onlyIf is compared in SQL.
+- `createdAt` and `updatedAt` a caller sets itself (in a system context or one it derived) are cut to the field's `temporalPrecision`, as the handle's own stamps are: a job's `Date#toISOString()`, with milliseconds, was refused (REST_API_VALIDATION) on a table whose timestamps declare `temporalPrecision: 0`. The fraction is cut, never rounded; a value with no fraction, or that is no date-time, is left for validation to judge.
+- `./server` exports `passedOn(options)`, what a call hands on (its context and transaction), from `@jskit-ai/resource-core/shared/callOptions`. Code that must load without the table runtime and the database (an assistant on file storage, where `@jskit-ai/resource-runtime` is an optional peer and not installed) imports it from resource-core, a dependency it has.
+- **Security.** `withoutHiddenFields` guards every function the repository holds, not only the seven standard reads: whatever a method answers (its records, in arrays, maps and nested plain records, and those of its sub-repositories) leaves without the hidden fields of the tables its owner owns, unless the call's options (its last record argument) carry a system or derived job context. A read an owner added in `decorateRepository`, such as one forwarding the caller's `fields` to its handle's `queryAll`, handed hidden values to any caller. A handle's `scopedQuery` is refused under any name, and `withTransaction` and `lockOrCreate` answer the caller's own work as it is. `withoutHiddenFields(repository, resources)` takes the served resource, or a list of it first and the owner's other tables. A function that answers a Knex value rather than rows (`raw()`, `column()`, or an owner's join source answering a builder) answers it as it is, unawaited, so another feature still builds its scoped query or subquery on it.
+- **Security.** `withoutHiddenFields`, the repository a CRUD feature gives other features and its own actions, refuses `scopedQuery()` on a table with hidden fields unless it runs in a system context or one it derived: its builder selects every column, so `(await repository.scopedQuery({}, options)).query.select(repository.column("tokenHash"))` read another feature's hidden values. The owner's own methods, its join sources among them, build on the handle as before.
+- `expectFlatQueries` fails when the path sent no statement at any size. That is a test counting on a channel the path does not use, such as no `knex` in a test whose features run on one and that booted no server, which measured 0 at every size and passed.
+- A call's settings stay on that call. `withTransaction` hands its work only `{ context, trx }`, and so does a handle to its `afterWrite` hooks, to `lockOrCreate`'s work and to its own nested calls, instead of every option the caller passed: an outer `returning: "none"` made a create inside, or `findOrCreate`, answer nothing, and an outer `missing: "skip"` made a get inside answer null for a missing record. A handle's own write and read still take its `format`. `passedOn(options)`, exported from `./server`, gives the same `{ context, trx }` to code that calls another table.
+- The `createdAt` and `updatedAt` a handle stamps are cut to the field's `temporalPrecision` (whole seconds for 0): they always carried milliseconds, so every create on a table whose timestamps declare `temporalPrecision: 0` failed with TYPE_CAST_FAILED.
+- A row policy (an owner's or a contribution) is told who the call runs for only as `caller`: json-rest-api's own `system` flag is no longer handed on beside it, so a policy has one way to tell a system context, a job, a user and no one apart. No JSKIT policy read the flag.
+- `expectScoped` compares the path's answers: it seeds owner A and runs the path as A, then seeds owner B and runs it as A again, and fails when the second answer differs from the first, as well as when the path changed or removed a row of B's. It used to fail only when the answer held one of B's rows by id with the same fields, so a report that joined, summed or counted B's rows (an answer like "Pat at business B") passed. The path runs twice, so a write answers what repeats. B's rows are read back by id, a thousand per read, and the tables' ids in one statement each, instead of whole tables through `queryAll`, which refused a table past its row limit.
+- A handle's plain read answers the hidden fields (`hidden: true`) its `fields` names: `get`, `query` and `queryAll` in their params, and `lock`, `lockMany`, `lockWhere` and `claim` in their options. json-rest-api never selects a hidden field, so the handle reads them in one more statement per 1,000 records, on the table as `scopedQuery` gives it (the caller's ownership and the row policy applied), in the call's transaction, and answers them as json-rest-api reads their type. A hidden field may be an id, string, integer, number or boolean; naming one of any other type refuses the read before it runs. A read without `fields`, and any JSON:API read (`format: "jsonapi"`), still never answers one. Before, an owner read its own bearer token or storage key with a `scopedQuery` report, and a job that had to learn each row's owner across workspaces had to unhide the ownership field.
+- `withoutHiddenFields(repository, resource)` (`@jskit-ai/resource-runtime/server`) answers the repository an owner gives other features: the same, except that a read whose `fields` names a hidden field of the resource is refused, with a TypeError naming the method and fields, unless it runs in a system context or one it derived. A resource without hidden fields keeps its repository as it is.
+- **Breaking.** A query field's `select` (an `owns` entry's `queryFields`) receives `{ raw, column, filters }` instead of json-rest-api's `{ knex, db, column, context, ... }`. `raw(sql, bindings)` builds one SQL expression from a string and its bindings as an array, and is a value only: it is no promise (its `then` is undefined, so awaiting it answers the expression itself, unrun), and running it as a statement (`catch`, `finally`, `asCallback`, `stream`, `pipe`) throws. `column(field)` names a field's column, and `filters` is the read's filters, frozen. A select could run any statement on the Knex it was handed, with no ownership scope; now it writes the field's value and nothing else: `select({ raw, column }) { return raw("?? - coalesce(??, 0)", [column("receivedWeight"), column("processedWeight")]); }`. A handle's `raw()` refuses the same way bindings that are not an array, or a third argument. jskit/sql-literal holds a destructured `raw(...)` to the rules it holds `handle.raw(...)` to (one literal, bindings for its placeholders, no statement words).
+- `lockWhere` and `claim` take `fields` in their options, as `lock` and `lockMany` do (`{ ...txOptions, fields: ["stage"] }`), and read only those, so a belongs-to field left out costs no check that its related record is visible: a claim of a job that links to two tables was a locking read and two checks, and is the locking read alone. Without `fields` they read what `lockMany` reads, so a collection with `hydrateOnView: false` is no longer loaded unless `fields` names it.
+- A handle write refuses a condition its options name with no value: `patch` with `lockVersion: undefined` or `onlyIf: undefined`, and `patchMany` or `patchWhere` with `onlyIf: undefined`, throw a TypeError naming the resource, the method and the key (`notes.patch() options.lockVersion is undefined`). They used to run without the condition, so a version read under the wrong field name made a version advance only read. A call without the condition leaves the key out.
+- An error a transaction's work throws itself reaches the caller of `withTransaction` (or of a handle call that opened its own transaction) reporting `transactionOutcome: "rolledBack"`, not enumerable, with its status and code unchanged, so `isLostDuplicateInsertRace` and a caller's retry tell a rolled-back duplicate the work turned into its own 409 from one inside a joined transaction. A frozen error is rethrown as it is.
+- A handle's `query`, `queryAll` and `aggregate` whose filters give an empty list to a list filter (the id filter, or a filter with `filterOperator: "in"`) answer without a statement what a read matching no row answers: no records (`hasMore: false`), and for `aggregate` no groups, or one row of totals whose counts are 0 and other measures null. The context, page size and filter guards still run first; a JSON:API (`format: "jsonapi"`) query still reads.
+- **Security.** `createStandaloneResources` refuses, on the Knex client of a JSKIT server, a table one of the server's features owns, saying which: standalone resources (for a command-line script) built a runtime of their own, with its own table owners and any system scope, so code inside a server could own an app table a second time and read it past its owner. A second Knex client on the same database is not recognised; code inside a server uses its features' handles.
+- A job context from `forWorkspace`, `forUser` or `forWorkspaceUser` carries the event scope of its workspace, user or both (`{ kind: "workspace", id }`, `{ kind: "user", id }`, `{ kind: "workspace_user", id, scopeId, userId }`, as a request there does), so an action event it publishes reaches that audience, where it was scoped global.
+- **Security.** A context that names no workspace or no user is refused wherever a table owned by it is read, not only on that table's own handle: an `include`, a link's visibility check and a link write into a workspace- or user-owned table now fail with json-rest-api's `REST_API_AUTOFILTER_CONTEXT`, where they read or linked the rows whose owner is NULL. The workspace and user owner resolvers answer nothing (undefined) when the context names no owner; only `workspace_or_shared` keeps its own resolver, which answers null, so a context with no workspace still reads only the shared rows.
+- `own()` refuses at startup a cross-table filter (a `searchSchema` or field `search` entry whose `actualField` or `oneOf` names "resource.field") whose target field is not declared `indexed: true`, naming the filter, the target and the fix. json-rest-api refuses that filter only at the first query that uses it. A filter whose target table no feature owns yet is checked when its owner owns it.
+- Runs on json-rest-api 3.0.0's release candidate (a17b722). A record written back as it was read keeps a link to a target the writer cannot see: the null it read counts as unchanged, while linking or clearing a visible target applies. A read that includes a link's target no longer checks that link's visibility again (one statement fewer per included type). A system context may group by and count distinct a hidden ownership field, so a job finds its units through its handle; a request is still refused. Stored integer and number values over BIGINT columns read as numbers when exact; ids stay strings, and getter, computed and virtual fields keep their own values.
+- A system context's `forWorkspace`, `forUser` and `forWorkspaceUser` take `{ actorId }` last, for work a job does for one person (a request it carries out later). The derived context carries it as `onBehalfOf`, which audit fields read with the kernel's `resolveAuditActorId(context)`, and a row policy sees it as `caller.actorId` beside `kind: "job"`. It is attribution only: it never changes which rows the job reaches, and it signs no one in, so `resolveActorId`, `requireAuth` and an action's `authenticated` permission still see no one. Any other last argument is refused.
+- `@jskit-ai/resource-runtime/test` exports `startTestFeatures({ knex, features, requires, inputs, createTables, logger })`: it starts features and providers as an application's server does, without HTTP, on a test resource runtime over the test's Knex, with the kernel's events and actions. The kernel orders them by their requires, each owner gets its handles and system context, every boot runs (so `crud.contracts` is sealed), and it answers `{ capabilities, resources, stop }`, where `capabilities` holds what `requires` names.
+- `patch(id, changes, { ...options, onlyIf })` compares a `hidden` field: the UPDATE compares the onlyIf values itself, after the lock that tells a missing record from a changed one, where the handle compared them with the locked record, which no read gives a hidden field, so such a patch never applied unless it also said `missing: "skip"`.
+- A row policy (and each contribution) receives `caller`, who the call runs for: `{ kind: "system", reason }` for a system context, `{ kind: "job", reason }` for a context `forWorkspace`, `forUser` or `forWorkspaceUser` derived from one, `{ kind: "user", userId }` for a signed-in request and `{ kind: "anonymous" }` otherwise. A derived job context names no user, so a policy that keyed on the actor treated it as an anonymous request; it now tells them apart by `caller.kind`. `system` is still passed.
+- A table whose primary key is a `uuid` or a `string` takes its ids as text without a `normalizeId` on its `owns` entry; json-rest-api's default normalizer takes numeric ids only and answered "Resource document id is invalid". An owner's own `normalizeId` still wins.
+- `createMany` with `onConflict: { action: "merge" }` and no `merge` list works on a table that stores `createdAt`: the merge list the handle builds from the rows' fields leaves out the conflict keys, the ownership fields and the lock version, which json-rest-api refused to merge ("onConflict.merge cannot change …"), as well as the id and `createdAt`.
+- `aggregate` counts `id` (`{ count: "id" }` or `{ countDistinct: "id" }`) as the count of rows, on a schema that declares no id field too; json-rest-api refused it as an unknown field.
+- A handle's included records read as a read of their own resource answers them, at every depth and in an included collection: a belongs-to field carries its id under its own key (`pet.contactId`) and the related record stays nested only when the include names it (`include: "pet.contact"`), where an included record kept json-rest-api's shape (`pet.contact: { id }`, no `contactId`). An included record leaves out a collection it does not include itself, which json-rest-api does not read for it and would answer as empty.
+- `lock` and `lockMany` take `fields` in their options (`{ ...txOptions, fields: ["stage"] }`) and read only those, so a belongs-to field left out costs no check that its related record is visible: a lock of a record with two relations was a locking read and two checks, and is the locking read alone. A `patch` with `lockVersion` or `onlyIf` locks only the fields it compares, so its own locking read checks no relation, and `onlyIf` may now compare a field reads hide by default (it never matched before).
+- A sparse `fields` names a belongs-to field by its own key (`customerId`) as well as by its relationship (`customer`): the key used to select no relationship and answer `customerId: null` for every row. A sparse read leaves out a belongs-to field it does not name, where it answered `null`.
+- A collection relation with `hydrateOnList: false` (lists: `query`, `queryAll`) or `hydrateOnView: false` (`get`, `lock`, `lockMany`) no longer loads its rows on that kind of read unless the read includes it or names it in `fields`, as the CRUD runtime before the redesign did.
+- On a table with a lock version, a patch that changes no field still advances the version, and now stamps `updatedAt` as every other update does: `patch(id, {}, { lockVersion })` (which did not stamp before) and an empty `patchMany` row, so many records advance in one UPDATE (`patchMany(ids.map((id) => ({ id })), options)`). A table without a lock version still writes nothing for an empty change.
+- **Breaking.** Every handle owns the `id` filter, which takes one id or a list (`filters: { id }`), and registering a table resource that declares its own refuses: a `searchSchema` `id` entry (shared or the owner's) or `search: true` on the `id` field. A declared scalar `id` entry used to replace the handle's, so `filters: { id: ids }` failed on that table. **Upgrading:** delete the resource's `id: { type: "id", actualField: "id" }` search entry and any `search: true` on its `id` field; filters by one id or a list keep working.
+- **Breaking (security).** A system context comes only from a declared system scope. `runtime.resources` no longer has `createSystemContext`: `declareSystemScope(featureId, systemScope)` records the scope (one per feature; declaring another throws) and answers the feature's `systemContext(reason)` factory, which the kernel hands a feature's setup, and `systemScopes()` lists them. `createResourceRuntime` and the `./server/resourceHost` subpath are no longer exported, so no code outside the package builds a runtime or a host of its own: code outside a JSKIT server owns its tables with `createStandaloneResources({ knex, feature, owns, systemScope? })`, which answers `{ resources, systemContext? }`, and tests with `createTestResourceRuntime` from `./test`, which now takes `hostHooks` for json-rest-api hooks a test installs. `buildJsonRestQueryParams`, `resolveWorkspaceScopeValue` and `resolveUserScopeValue` are exported from `./server`. `resolveUserScopeValue` throws when a context's `scopeValues.userId` and `visibilityContext.userId` name two users, as the workspace resolver does for two workspaces, instead of the scope value winning.
+- A table resource whose schema stores `createdAt` and `updatedAt` as date-times has every handle write stamp them: `create` and `createMany` stamp both, `patch`, `patchMany`, `patchWhere` and an upsert merge stamp `updatedAt` (a merge keeps the stored `createdAt` of a record it updates), and a patch that changes nothing stamps nothing. The stamps replace what the caller sends, so a request can never forge them; only a system context, or a context it derived (an import, a migration, a seed), sets its own, and a timestamp it leaves out is stamped. A call without a context, which server code may make on a public table, is a request's: server code cannot pass a forged body through, and a feature that writes its own timestamps declares a `systemScope` and writes in its system context. Only the CRUD service stamped them before, so server code that wrote through a handle left them unchanged.
+- Handles gain `lockOrCreate(row, options, work)`: on a table with no owners it locks the record with `row.id`, creating it from `row` first when it is missing (an insert that ignores a clash on the id), and runs `work(record, txOptions)` in that transaction, so work that fails leaves no record behind. In the caller's transaction it runs there once; on its own it opens a transaction that runs work once, and when two first uses of one id collide on the insert (a deadlock, or a duplicate key) before work starts, the loser runs again, up to four runs in all.
+- **Breaking: the package is now `@jskit-ai/resource-runtime`** (was `@jskit-ai/json-rest-api-core`), on json-rest-api 3.0.0. Its provider is `ResourceRuntimeProvider`, which provides `runtime.resources`; the host it builds is `createResourceHost` (was `createJsonRestApiHost`), at `./server/resourceHost` (was `./server/jsonRestApiHost`). The `runtime.json-rest-api` capability and the host helpers `addResourceIfMissing`, `createJsonRestResourceScopeOptions`, `queryAllJsonRestCollectionRows`, `queryAllJsonRestCollectionDocument` and `extractJsonRestCollectionRows` are removed: a feature owns its tables with `defineFeature({ owns })` and reads every matching row with its handle's `queryAll`.
+- **`runtime.resources`.** The kernel calls `own(featureId, owns)` for a feature with `owns`: it registers each table resource (or `{ resource, rowPolicy, hooks: { afterWrite }, acceptsContributions, normalizeId, queryFields, searchSchema }`) under its name, throws `DuplicateOwnerError` when another feature owns the table or the name, and answers one handle per resource. `createSystemContext({ feature, systemScope, reason })` answers json-rest-api's system context, with `forWorkspace(id)` and `forUser(id)` for work scoped to one workspace or user.
+- **Handles.** Every method takes `options = { context, trx }` last and refuses an owned resource's call without a context (`MissingScopeError`). Reads: `query(params)` answers `{ records, page: { size, hasMore, next } }` and requires `page.size` (`UnpagedQueryError`) no larger than the resource's page limit (`PageSizeError`), with `page.after` (the previous page's `next`) for scrolling or `page.number` (from 1) for a numbered page, each one statement with no count; `queryAll` reads in 1,000-row pages and, in a request context, throws `RowLimitError` past 10,000 rows (a 400 coded `RESOURCE_ROW_LIMIT`, with the message code `resource.rowLimit` for the user's language) (system, workspace and user job contexts have no limit); `get(id, params, options)` answers a record; `aggregate` answers rows. Writes: `create`, `patch` (answers the record; `lockVersion` throws `StaleRecordError`, 409 `crud.document.lockVersionConflict`; `onlyIf` patches only matching rows and answers null otherwise) and `delete` (answers the id), and the many-row `createMany`, `patchMany`, `patchWhere` and `deleteWhere`, one statement per chunk. One missing-row rule: `get`, `patch`, `delete` and `lock` throw json-rest-api's not-found error (404) for a missing or hidden row, and answer null with `missing: "skip"`, which never fails the caller's transaction. Every filter takes `id`, one id or a list, so `patchWhere({ id: ids }, changes)` and `deleteWhere({ id: ids })` cover a list of ids. An upsert's rows carry no id, and `patchWhere` and `deleteWhere` with empty filters need `all: true`. Locks: `lock`, `lockMany`, `lockWhere`, `claim({ filters, sort, take }, options)`. Escape hatch: `scopedQuery` answers `{ query }`, a read-only builder with ownership and the row policy applied, with `column` and `raw`. Reads take `(params, options)` and writes `(data, options)`; settings ride in options, as `{ ...options, lockVersion }`. `withTransaction(options, work)` runs work in the caller's transaction or one it opens and retries a deadlock victim unless `{ ...options, retry: false }`; `{ ...options, outermost: true }` refuses a call inside a transaction. When work throws, the caller gets its own error; a failed write inside it or a failed commit arrives as json-rest-api's `RestApiWriteError` with the transaction's outcome. `findOrCreate({ id, ...attributes }, options)` reads the record with that id or creates it, and answers the winner's record when a concurrent creation wins outside a transaction. An id another scope's row holds answers a missing record, as `get` of it does, never `null` or that row, so it tells the caller no more than any id it cannot see. `afterWrite` hooks run once per write in its transaction and scope.
+- A system context also derives `forWorkspaceUser(workspaceId, userId)`: one user's context inside one workspace, so a `workspace_user` table reads that user's rows in that workspace, a `workspace` table the workspace's and a `user` table the user's. Both ids are required.
+- **Row policies** receive `ownTable(name)`, a SELECT-only builder over the owner's own tables, and a resource whose owner says `acceptsContributions` takes other features' `contributeRowPolicy(name, policy)`: each contribution is ANDed with the owner's policy inside its own group, so it only narrows.
+- **`workspace_or_shared`** ownership reads a workspace's rows and the rows whose workspace is null, and writes only its own.
+- **`./test`:** `expectScoped`, `expectFlatQueries` (moved from database-runtime; it now allows the later chunks a many-row write reports), `expectEveryTableOwned`, `requireTestDatabase` and `createTestResourceRuntime`.
+- json-rest-api 3.0.0 includes 2.2.0 to 2.4.0. A handle's `queryAll` reads in 1,000-row pages; writes skip the post-write refresh nothing observes (a created child: 9 statements and 5 policy runs instead of 11 and 7); linkage checks run one query per type; reads copy records for `originalRecord` only for hooks that can read it (a query of 100 rows of 38 KB: about a third of the CPU). Also from 2.2.0-2.3.1: `aggregate()`, `email` and `uuid` field types, `retired: true` fields, AnyAPI indexed slots, and relationship targets locked FOR SHARE instead of FOR UPDATE.
+
+## 0.2.0 - 2026-10-29
+
+- Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".
+
+### New message keys (2)
+
+All keys in `locales/en.json` (exported as `./locales/en.json`) are new in this version.
+
+<details><summary>Key list</summary>
+
+- `jskit.errors.REST_API_VERSION_CONFLICT`
+- `jskit.errors.REST_API_PRECONDITION_FAILED`
+
+</details>

package/locales/en.json

@@ -0,0 +1,16 @@
+{
+  "jskit": {
+    "errors": {
+      "REST_API_VERSION_CONFLICT": "Resource version condition failed",
+      "REST_API_PRECONDITION_FAILED": "HTTP representation precondition failed"
+    },
+    "crud": {
+      "document": {
+        "lockVersionConflict": "This record changed. Reload and try again."
+      }
+    },
+    "resource": {
+      "rowLimit": "This request would read more than {rowLimit} rows. Ask for fewer and try again."
+    }
+  }
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@jskit-ai/resource-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.13",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "test": "jskit test"
+  },
+  "exports": {
+    "./server": "./src/server/index.js",
+    "./server/types": "./src/server/types.js",
+    "./test": "./src/test/index.js",
+    "./locales/en.json": "./locales/en.json"
+  },
+  "dependencies": {
+    "@jskit-ai/resource-core": "0.1.206",
+    "@jskit-ai/resource-crud-core": "0.1.206",
+    "json-rest-api": "3.1.0"
+  },
+  "description": "The resource runtime: features own their tables through it and read and write them with scoped handles on json-rest-api.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "runtime.resources"
+      ],
+      "requires": [
+        "runtime.database",
+        "runtime.logger"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/ResourceRuntimeProvider.js",
+            "export": "ResourceRuntimeProvider"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server",
+            "summary": "Provides runtime.resources (ResourceRuntimeProvider): own(featureId, owns) registers a feature's tables and answers their scoped handles, and declareSystemScope(featureId, systemScope) answers the feature's systemContext(reason) for work across every workspace and user. Exports createStandaloneResources, passedOn, withoutHiddenFields, isSystemContext, buildJsonRestQueryParams, the workspace and user scope resolvers, the default row limit and page size, and the runtime's error classes."
+          },
+          {
+            "subpath": "./server/types",
+            "summary": "Types of runtime.resources, its handles, call options and system contexts."
+          },
+          {
+            "subpath": "./test",
+            "summary": "Data test helpers on a real test database: createTestResourceRuntime, startTestFeatures, expectScoped, expectFlatQueries, expectEveryTableOwned, createPackageTestKnex, requireTestDatabase and TestDatabaseMissingError."
+          }
+        ]
+      }
+    }
+  },
+  "peerDependencies": {
+    "@jskit-ai/database-runtime": "0.1.264",
+    "@jskit-ai/kernel": "0.2.15"
+  }
+}

package/src/server/ResourceRuntimeProvider.js

@@ -0,0 +1,30 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createResourceHost } from "./resourceHost.js";
+import { createResourceRuntime } from "./resourceRuntime.js";
+import { registerServerRuntime } from "./standaloneResources.js";
+
+const ResourceRuntimeProvider = defineProvider({
+  id: "runtime.resources",
+  requires: {
+    database: "runtime.database",
+    logger: "runtime.logger"
+  },
+  provides: {
+    resources: "runtime.resources"
+  },
+  /**
+   * `runtime.resources`, through which features own their tables, on one
+   * json-rest-api host.
+   * @param {object} dependencies
+   * @param {import("@jskit-ai/database-runtime/server/types").RuntimeDatabase} dependencies.database
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} dependencies.logger
+   */
+  async setup({ database, logger }) {
+    const api = await createResourceHost({ knex: database.knex, logger });
+    const resources = createResourceRuntime({ api });
+    registerServerRuntime(database.knex, resources);
+    return { resources };
+  }
+});
+
+export { ResourceRuntimeProvider };

package/src/server/changeHorizon.js

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

package/src/server/contexts.js

@@ -0,0 +1,192 @@
+import { createSystemContext as createJsonRestSystemContext, isSystemContext } from "json-rest-api";
+import { resolveActorId } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
+import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+// Module-private: only jobContext() marks a context as background work's, so a
+// request cannot claim it. Object spread keeps the marker, as json-rest-api's
+// own system marker.
+const JOB_CONTEXT = Symbol("jskit.resources.jobContext");
+
+/**
+ * The context one json-rest-api call works in: a copy of the caller's, with its
+ * visibility context and scope values copied too, since json-rest-api writes an
+ * operation's working state into the context it is given. A system context
+ * stays one, because spread keeps its marker.
+ * @param {object | null | undefined} [context]
+ */
+function createJsonRestContext(context = null) {
+  if (!context || typeof context !== "object" || Array.isArray(context)) {
+    return {};
+  }
+
+  const nextContext = {
+    ...context
+  };
+
+  if (context.visibilityContext && typeof context.visibilityContext === "object" && !Array.isArray(context.visibilityContext)) {
+    nextContext.visibilityContext = {
+      ...context.visibilityContext
+    };
+  }
+
+  if (context.scopeValues && typeof context.scopeValues === "object" && !Array.isArray(context.scopeValues)) {
+    nextContext.scopeValues = {
+      ...context.scopeValues
+    };
+  }
+
+  return nextContext;
+}
+
+/**
+ * Whether a context belongs to background work: a system context, or a
+ * workspace or user context a system context derived. Request row limits
+ * apply to every other context.
+ * @param {unknown} context
+ */
+function isJobContext(context) {
+  return isSystemContext(context) || Boolean(context && typeof context === "object" && context[JOB_CONTEXT]);
+}
+
+/**
+ * Who a call runs for, as its row policy sees it: background work across every workspace and user ("system"),
+ * background work a system context derived for one workspace or user ("job"), each with its reason; a request by a
+ * signed-in user ("user", with the user's id); or a request by no one ("anonymous"). A derived job context names a
+ * user only as the person it acts for (`actorId`, when it was given one), never as a signed-in user, so a policy
+ * that keys on the actor tells it from an anonymous request by its kind.
+ * @param {unknown} context
+ * @returns {Readonly<{ kind: "system", reason: string } | { kind: "job", reason: string, actorId?: string } | { kind: "user", userId: string } | { kind: "anonymous" }>}
+ */
+function callerOf(context) {
+  if (isSystemContext(context)) {
+    return Object.freeze({
+      kind: "system",
+      reason: context.systemReason
+    });
+  }
+  if (context && typeof context === "object" && context[JOB_CONTEXT]) {
+    return Object.freeze({
+      kind: "job",
+      reason: context.jobReason,
+      ...(context.onBehalfOf ? { actorId: context.onBehalfOf.id } : {})
+    });
+  }
+  const userId = resolveActorId(context);
+  return Object.freeze(userId ? { kind: "user", userId } : { kind: "anonymous" });
+}
+
+/**
+ * The event scope of work on one workspace, one user or one person in a workspace, as a request there carries it, so
+ * an event the work publishes reaches that workspace's or that user's audience, never everyone.
+ * @param {{ workspaceId?: string, userId?: string }} scopeValues
+ */
+function eventScopeOf({ workspaceId, userId }) {
+  if (workspaceId && userId) {
+    return Object.freeze({
+      kind: "workspace_user",
+      id: workspaceId,
+      scopeId: workspaceId,
+      userId
+    });
+  }
+  return Object.freeze(workspaceId ? { kind: "workspace", id: workspaceId } : { kind: "user", id: userId });
+}
+
+/**
+ * @param {string} reason
+ * @param {Record<string, unknown>} scopeValues
+ * @param {{ actorId?: unknown }} options The person the work acts for, if any: `onBehalfOf.id`, for audit fields only.
+ * @param {string} label The deriving method, such as "forWorkspace".
+ */
+function jobContext(reason, scopeValues, options, label) {
+  if (options !== undefined && (!options || typeof options !== "object" || Object.keys(options).some((key) => key !== "actorId"))) {
+    throw new TypeError(`${label} takes { actorId } as its last argument: the user the work acts for.`);
+  }
+  const actorId = options?.actorId === undefined ? null : requireScopeId(options.actorId, label, "user it acts for");
+  return Object.freeze({
+    scopeValues: Object.freeze(scopeValues),
+    scope: eventScopeOf(scopeValues),
+    jobReason: reason,
+    ...(actorId ? { onBehalfOf: Object.freeze({ id: actorId }) } : {}),
+    [JOB_CONTEXT]: true
+  });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label The deriving method, such as "forWorkspace".
+ * @param {"workspace" | "user" | "user it acts for"} subject What the id names.
+ */
+function requireScopeId(value, label, subject) {
+  const id = normalizeRecordId(value, { fallback: null });
+  if (!id) {
+    throw new TypeError(`${label} needs the id of the ${subject} to work on.`);
+  }
+  return id;
+}
+
+/**
+ * The context of work across every workspace and user, for a feature that
+ * declares `systemScope`. Ownership predicates are skipped for it, row
+ * policies receive `caller.kind` "system" (a derived context's `caller.kind`
+ * is "job"), and creates name their ownership values.
+ * `forWorkspace(id)`, `forUser(id)` and `forWorkspaceUser(workspaceId, userId)`
+ * derive ordinary contexts scoped to one workspace, one user, or one user in
+ * one workspace, so the work for each is scoped as usual (and, as background
+ * work, free of request row limits). Each takes `{ actorId }` last, for work
+ * done for one person (a request a job carries out): the context's
+ * `onBehalfOf`, which audit fields read with `resolveAuditActorId(context)`,
+ * and the row policy's `caller.actorId`. It names who the work is for, never
+ * which rows it reaches, and it signs no one in: `resolveActorId` and every
+ * authentication check still see no one.
+ * @param {{ feature: string, systemScope: string, reason: string }} declaration
+ */
+function createSystemContext({ feature, systemScope, reason }) {
+  const normalizedReason = normalizeText(reason);
+  if (!normalizedReason) {
+    throw new TypeError(`Feature "${feature}" needs the reason its work reads or writes every workspace's rows.`);
+  }
+  const description = `${feature}: ${normalizedReason}`;
+
+  /**
+   * @param {unknown} workspaceId
+   * @param {{ actorId?: unknown }} [options]
+   */
+  function forWorkspace(workspaceId, options) {
+    return jobContext(description, { workspaceId: requireScopeId(workspaceId, "forWorkspace", "workspace") }, options, "forWorkspace");
+  }
+
+  /**
+   * @param {unknown} userId
+   * @param {{ actorId?: unknown }} [options]
+   */
+  function forUser(userId, options) {
+    return jobContext(description, { userId: requireScopeId(userId, "forUser", "user") }, options, "forUser");
+  }
+
+  /**
+   * One user's context inside one workspace: a `workspace_user` table reads
+   * that user's rows in that workspace, a `workspace` table the workspace's
+   * and a `user` table the user's.
+   * @param {unknown} workspaceId
+   * @param {unknown} userId
+   * @param {{ actorId?: unknown }} [options]
+   */
+  function forWorkspaceUser(workspaceId, userId, options) {
+    return jobContext(description, {
+      workspaceId: requireScopeId(workspaceId, "forWorkspaceUser", "workspace"),
+      userId: requireScopeId(userId, "forWorkspaceUser", "user")
+    }, options, "forWorkspaceUser");
+  }
+
+  return Object.freeze(createJsonRestSystemContext(description, {
+    feature,
+    systemScope,
+    reason: normalizedReason,
+    forWorkspace,
+    forUser,
+    forWorkspaceUser
+  }));
+}
+
+export { callerOf, createJsonRestContext, createSystemContext, isJobContext, isSystemContext };

package/src/server/errors.js

@@ -0,0 +1,137 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+
+// The resource runtime's own refusals. json-rest-api's errors (RestApiRecordsNotFoundError,
+// RestApiBulkWriteUnsupportedError, RestApiLockOutsideTransactionError, RestApiScopedQueryReadOnlyError,
+// RestApiWriteError and the others) reach the caller as json-rest-api throws them.
+
+/** A handle call on an owned resource without the caller's context: ownership cannot be applied, so nothing runs. */
+class MissingScopeError extends TypeError {
+  /**
+   * @param {string} resourceName
+   * @param {"workspace" | "user"} [owner] The owner the table's rows belong to, when the context names none.
+   */
+  constructor(resourceName, owner) {
+    super(
+      (owner
+        ? `${resourceName} rows each belong to a ${owner}, and this context names no ${owner}, so the ownership scope cannot be applied. `
+        : `${resourceName} needs options.context, so the ownership scope can be applied. `) +
+        "Pass on the options your function received. Only a background job of a feature with systemScope uses " +
+        "systemContext(reason).forWorkspace(id); never use it to make a request work."
+    );
+    this.name = "MissingScopeError";
+    this.code = "RESOURCE_MISSING_SCOPE";
+  }
+}
+
+/**
+ * A handle call on a `system` table in a context that is not a system context: its rows belong to no workspace or user,
+ * so a request's context, or one derived for a workspace or a user, would reach every workspace's rows. Nothing runs.
+ */
+class SystemContextRequiredError extends TypeError {
+  /** @param {string} resourceName */
+  constructor(resourceName) {
+    super(
+      `${resourceName} rows belong to no workspace or user (ownership "system"), so only a system context reaches them: ` +
+        "the background work of the feature that owns the table, with systemContext(reason). A request's context, or one " +
+        "forWorkspace, forUser or forWorkspaceUser derived, would reach every workspace's rows. Call the owner's own methods, " +
+        "which run in its system context."
+    );
+    this.name = "SystemContextRequiredError";
+    this.code = "RESOURCE_SYSTEM_CONTEXT_REQUIRED";
+  }
+}
+
+/**
+ * A handle call that reads something only some databases have, on one that lacks it, such as changeHorizon() outside
+ * PostgreSQL. Nothing runs.
+ */
+class UnsupportedDatabaseError extends Error {
+  /**
+   * @param {string} call The call, as `notes.changeHorizon()`.
+   * @param {string} reason What the call reads and which databases have it.
+   */
+  constructor(call, reason) {
+    super(`${call} ${reason}`);
+    this.name = "UnsupportedDatabaseError";
+    this.code = "RESOURCE_DATABASE_UNSUPPORTED";
+  }
+}
+
+/** query() without page.size: every list is paged, and every-row reads say so with queryAll(). */
+class UnpagedQueryError extends TypeError {
+  /** @param {string} resourceName */
+  constructor(resourceName) {
+    super(`${resourceName}.query() needs page.size; read every row with queryAll(), count with aggregate().`);
+    this.name = "UnpagedQueryError";
+    this.code = "RESOURCE_UNPAGED_QUERY";
+  }
+}
+
+/** query() asking for a page larger than the resource serves. */
+class PageSizeError extends TypeError {
+  /**
+   * @param {string} resourceName
+   * @param {unknown} size
+   * @param {number} limit
+   */
+  constructor(resourceName, size, limit) {
+    super(
+      `${resourceName}.query() page.size ${size} is above the resource's page limit (${limit}), so it would return ` +
+        `only ${limit} records. Read every row with queryAll(), or page with page.after.`
+    );
+    this.name = "PageSizeError";
+    this.code = "RESOURCE_PAGE_SIZE";
+  }
+}
+
+/**
+ * queryAll() in a request context reading past the request row limit: the request answers a 400 coded
+ * RESOURCE_ROW_LIMIT, with a sentence the client can show in the user's language, instead of a 500.
+ */
+class RowLimitError extends AppError {
+  /**
+   * @param {string} resourceName
+   * @param {number} rowLimit
+   * @param {unknown} cause
+   */
+  constructor(resourceName, rowLimit, cause) {
+    super(
+      400,
+      `${resourceName}.queryAll() read more than ${rowLimit} rows inside a request. Work over that many rows belongs ` +
+        "in a background job: a feature with systemScope, working per workspace with systemContext(reason).forWorkspace(id).",
+      { cause, code: "RESOURCE_ROW_LIMIT", messageCode: "resource.rowLimit", messageParams: { rowLimit } }
+    );
+    this.name = "RowLimitError";
+  }
+}
+
+/** patch() with lockVersion on a record someone else changed since it was read. */
+class StaleRecordError extends AppError {
+  constructor() {
+    super(409, "This record changed. Reload and try again.", {
+      code: "crud.document.lockVersionConflict"
+    });
+    this.name = "StaleRecordError";
+  }
+}
+
+/** own() for a table or resource name another feature already owns. */
+class DuplicateOwnerError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = "DuplicateOwnerError";
+    this.code = "RESOURCE_DUPLICATE_OWNER";
+  }
+}
+
+export {
+  DuplicateOwnerError,
+  MissingScopeError,
+  PageSizeError,
+  RowLimitError,
+  StaleRecordError,
+  SystemContextRequiredError,
+  UnpagedQueryError,
+  UnsupportedDatabaseError
+};