@jskit-ai/agent-docs 0.1.283 → 0.1.284

package/skills/jskit/references/patterns/crud/crud-feature-package/example/packages/books/src/shared/bookResource.js

@@ -0,0 +1,74 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { defineCrudContract } from "@jskit-ai/resource-crud-core/shared/crudContract";
+
+const bookResource = defineTableResource({
+  name: "books",
+  tableName: "books",
+  ownership: "user",
+  schema: {
+    userId: {
+      type: "id",
+      required: true,
+      hidden: true
+    },
+    title: {
+      type: "string",
+      maxLength: 255,
+      required: true,
+      search: true
+    },
+    author: {
+      type: "string",
+      maxLength: 255,
+      required: true,
+      search: true
+    },
+    notes: {
+      type: "string",
+      maxLength: 65535,
+      nullable: true,
+      search: true
+    },
+    createdAt: {
+      type: "dateTime",
+      temporalPrecision: 0,
+      storage: { writeSerializer: "datetime-utc" }
+    },
+    updatedAt: {
+      type: "dateTime",
+      temporalPrecision: 0,
+      storage: { writeSerializer: "datetime-utc" }
+    }
+  },
+  searchSchema: {
+    q: {
+      type: "string",
+      oneOf: ["title", "author", "notes"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
+  },
+  defaultSort: ["-createdAt"]
+});
+
+const bookCrud = defineCrudContract(bookResource, {
+  namespace: "books",
+  apiAccess: "authenticated",
+  fields: {
+    title: { output: "required", create: "required", patch: "optional" },
+    author: { output: "required", create: "required", patch: "optional" },
+    notes: { output: "required", create: "optional", patch: "optional" },
+    createdAt: { output: "required" },
+    updatedAt: { output: "required" }
+  },
+  messages: {
+    validation: "Fix invalid values and try again.",
+    saveSuccess: "Book saved.",
+    saveError: "Unable to save this book.",
+    deleteSuccess: "Book deleted.",
+    deleteError: "Unable to delete this book."
+  }
+});
+
+export { bookCrud, bookResource };

package/skills/jskit/references/patterns/crud/crud-feature-package/example/packages/books/src/shared/index.js

@@ -0,0 +1 @@
+export { bookCrud, bookResource } from "./bookResource.js";

package/skills/jskit/references/patterns/crud/crud-screen-set/PATTERN.md

@@ -3,7 +3,7 @@ id: crud/crud-screen-set
 title: CRUD list, view, create, and edit screens
 summary: Build a routed CRUD user interface as thin application pages over JSKIT's shared screen components and composables.
 keywords: actions, add, crud, delete, edit, filters, list, material, routes, view, vue
-requires: @jskit-ai/http-web, @jskit-ai/resource-crud-core
+requires: @jskit-ai/http-web, @jskit-ai/resource-crud-core, @jskit-ai/resource-core
 ---
 
 # CRUD list, view, create, and edit screens
@@ -27,7 +27,7 @@ supporting detail content; those are public extension seams.
 
 Decide which operations exist, the route hierarchy, record title, visible
 fields, create/edit participation, destructive confirmation language, access
-surface, filters, and domain actions. The resource contract and product intent
+surface, filters, and domain actions. The CRUD contract and product intent
 are authoritative. Do not derive these decisions from a live table or a field
 questionnaire.
 
@@ -49,7 +49,7 @@ questionnaire.
   history entry, so neither Up nor Back reopens it.
 - View fields are two-line list items with the value first:
   `<v-list-item :title="record.author" subtitle="Author" />`.
-- Transport and validators come from the shared resource contract.
+- Transport and validators come from the shared CRUD contract.
 - Initial visible loading uses structure-matching skeletons; pending buttons use
   stable disabled labels, never spinners.
 - Resource-load errors stay inside the screen with retry. Command success and
@@ -71,15 +71,18 @@ questionnaire.
 Use `CrudListScreen`, `CrudViewScreen`, `CrudAddEditScreen`, and
 `CrudDeleteAction` with their matching composables from `@jskit-ai/http-web`.
 Use `defineCrudListFilters()`, `defineCrudListRowActions()`, and
-`defineCrudListBulkActions()` for optional list extensions. The resource comes
-from `defineCrudResource()` in `@jskit-ai/resource-crud-core`.
+`defineCrudListBulkActions()` for optional list extensions. Screens take the
+CRUD contract from `defineCrudContract()` in `@jskit-ai/resource-crud-core`,
+built on the table resource from `defineTableResource()` in
+`@jskit-ai/resource-core`.
 
 ## Example files
 
 `example/books/` contains concrete list, view, new, and edit pages for the
-owner-scoped `bookResource` pattern. `BookFormFields.vue` and `formFields.js`
-show the small product-owned form seam. `listExtensions.js` makes optional
-filters and actions explicit without adding empty screen machinery elsewhere.
+owner-scoped `bookResource` table resource and its `bookCrud` contract.
+`BookFormFields.vue` and `formFields.js` show the small product-owned form
+seam. `listExtensions.js` makes optional filters and actions explicit without
+adding empty screen machinery elsewhere.
 
 ## Variation points
 
@@ -166,6 +169,21 @@ through to Vuetify.
 Here `lookups` is the page's `createCrudLookupFieldRuntime()` result for the
 same form fields.
 
+### Linked records in a list
+
+A list that shows a field of a linked record asks for it by relationship name
+in `useCrudListScreen({ ..., requestQueryParams: { include: "service" } })`,
+and each row reads it from its `lookups`: `record.lookups.service.name`. The
+contract decides which of the linked record's fields arrive: its id, its
+relation's `labelKey`, and what `fields.serviceId.output.includeFields` names.
+
+```vue
+<template #table-row="{ record }">
+  <td>{{ record.title }}</td>
+  <td>{{ record.lookups?.service?.name }}</td>
+</template>
+```
+
 ## Verification
 
 - Mount each route with a representative resource response.

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookEditPage.vue

@@ -3,7 +3,7 @@ import { computed } from "vue";
 import { useRoute } from "vue-router";
 import CrudAddEditScreen from "@jskit-ai/http-web/client/components/CrudAddEditScreen";
 import { useCrudAddEditScreen } from "@jskit-ai/http-web/client/composables/useCrudAddEditScreen";
-import { bookResource } from "@local/books/shared";
+import { bookCrud } from "@local/books/shared";
 import BookFormFields from "./BookFormFields.vue";
 import { bookFormFields } from "./formFields.js";
 
@@ -17,7 +17,7 @@ const screen = useCrudAddEditScreen({
   saveLabel: "Save changes",
   cancelTo: "/books/:bookId",
   preserveCancelQuery: true,
-  resource: bookResource,
+  resource: bookCrud,
   operationName: "patch",
   formFields: bookFormFields,
   addEditOptions: {

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookListPage.vue

@@ -1,14 +1,14 @@
 <script setup>
 import CrudListScreen from "@jskit-ai/http-web/client/components/CrudListScreen";
 import { useCrudListScreen } from "@jskit-ai/http-web/client/composables/useCrudListScreen";
-import { bookResource } from "@local/books/shared";
+import { bookCrud } from "@local/books/shared";
 import { listBulkActions, listFilters, listRowActions } from "./listExtensions.js";
 
 // A main menu destination: the app bar shows its title and no Up arrow.
 definePage({ meta: { jskit: { title: "Books" } } });
 
 const screen = useCrudListScreen({
-  resource: bookResource,
+  resource: bookCrud,
   resourceNamespace: "books",
   apiSuffix: "/books",
   recordIdParam: "bookId",

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookNewPage.vue

@@ -1,7 +1,7 @@
 <script setup>
 import CrudAddEditScreen from "@jskit-ai/http-web/client/components/CrudAddEditScreen";
 import { useCrudAddEditScreen } from "@jskit-ai/http-web/client/composables/useCrudAddEditScreen";
-import { bookResource } from "@local/books/shared";
+import { bookCrud } from "@local/books/shared";
 import BookFormFields from "./BookFormFields.vue";
 import { bookFormFields } from "./formFields.js";
 
@@ -11,7 +11,7 @@ const screen = useCrudAddEditScreen({
   mode: "new",
   saveLabel: "Save book",
   cancelTo: "/books",
-  resource: bookResource,
+  resource: bookCrud,
   operationName: "create",
   formFields: bookFormFields,
   addEditOptions: {

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookViewPage.vue

@@ -3,13 +3,13 @@ import CrudDeleteAction from "@jskit-ai/http-web/client/components/CrudDeleteAct
 import CrudViewScreen from "@jskit-ai/http-web/client/components/CrudViewScreen";
 import { useCrudDeleteAction } from "@jskit-ai/http-web/client/composables/useCrudDeleteAction";
 import { useCrudViewScreen } from "@jskit-ai/http-web/client/composables/useCrudViewScreen";
-import { bookResource } from "@local/books/shared";
+import { bookCrud } from "@local/books/shared";
 
 // Up returns to the page the book was opened from, or else to the list.
 definePage({ meta: { jskit: { title: "Book", parent: "/books" } } });
 
 const screen = useCrudViewScreen({
-  resource: bookResource,
+  resource: bookCrud,
   resourceNamespace: "books",
   apiUrlTemplate: "/books/:bookId",
   recordIdParam: "bookId",
@@ -22,7 +22,7 @@ const screen = useCrudViewScreen({
 
 const deleteAction = useCrudDeleteAction({
   screen,
-  resource: bookResource,
+  resource: bookCrud,
   resourceNamespace: "books",
   apiUrlTemplate: "/books/:bookId"
 });

package/skills/jskit/references/patterns/database/mysql-application/PATTERN.md

@@ -11,8 +11,10 @@ requires: @jskit-ai/database-runtime-mysql
 ## Use when
 
 Use this pattern when an application deliberately chooses MySQL or MariaDB.
-Install `@jskit-ai/database-runtime-mysql`; its normal npm dependencies provide
-the database runtime, Knex, and `mysql2` without a package-setup wizard.
+Install `@jskit-ai/database-runtime` and `@jskit-ai/database-runtime-mysql`
+without a package-setup wizard: the runtime brings Knex and the driver brings
+`mysql2`. The driver takes the runtime as a peer, so the application holds its
+one copy.
 
 ## Do not use when
 
@@ -50,8 +52,11 @@ Knex discovers package-owned migrations from the installed dependency graph.
 `example/package.json` contains the runtime dependency and database scripts.
 `example/knexfile.js` loads an optional local `.env` and fixes the MySQL dialect.
 `example/scripts/prepare-database.js` is the portable migrate-then-seed
-entrypoint for managed sessions and deployments. `example/.env.example` names
-the connection values and separate test databases without a secret.
+entrypoint for managed sessions and deployments. It loads the optional `.env`
+as the knexfile does, and migrates the database `DB_NAME` names without
+creating it: the hosting environment or a database administrator creates it
+first. `example/.env.example` names the connection values and separate test
+databases without a secret.
 
 `example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
 exactly one database service: `mariadb` (`mariadb:11.4`, `MARIADB_*`

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -9,6 +9,7 @@
     "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.260"
+    "@jskit-ai/database-runtime": "0.1.263",
+    "@jskit-ai/database-runtime-mysql": "0.1.261"
   }
 }

package/skills/jskit/references/patterns/database/mysql-application/example/scripts/prepare-database.js

@@ -1,3 +1,11 @@
 import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
 
+try {
+  process.loadEnvFile(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
 await prepareDatabaseFromApp({ client: "mysql2", environment: process.env });

package/skills/jskit/references/patterns/database/postgres-application/PATTERN.md

@@ -11,8 +11,9 @@ requires: @jskit-ai/database-runtime-postgres
 ## Use when
 
 Use this pattern when an application deliberately chooses PostgreSQL. Install
-`@jskit-ai/database-runtime-postgres`; its normal npm dependencies provide the
-database runtime, Knex, and `pg` without a package-setup wizard.
+`@jskit-ai/database-runtime` and `@jskit-ai/database-runtime-postgres` without
+a package-setup wizard: the runtime brings Knex and the driver brings `pg`. The
+driver takes the runtime as a peer, so the application holds its one copy.
 
 ## Do not use when
 
@@ -50,8 +51,11 @@ Knex discovers package-owned migrations from the installed dependency graph.
 `example/package.json` contains the runtime dependency and database scripts.
 `example/knexfile.js` loads an optional local `.env` and fixes the PostgreSQL
 dialect. `example/scripts/prepare-database.js` is the portable
-migrate-then-seed entrypoint for managed sessions and deployments.
-`example/.env.example` names the five connection values without a secret.
+migrate-then-seed entrypoint for managed sessions and deployments. It loads
+the optional `.env` as the knexfile does, and migrates the database `DB_NAME`
+names without creating it: the hosting environment or a database
+administrator creates it first. `example/.env.example` names the five
+connection values without a secret.
 
 Tests get their own databases from
 `@jskit-ai/database-runtime/server/testDatabases`. The `test` script runs

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -9,6 +9,7 @@
     "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.259"
+    "@jskit-ai/database-runtime": "0.1.263",
+    "@jskit-ai/database-runtime-postgres": "0.1.260"
   }
 }

package/skills/jskit/references/patterns/database/postgres-application/example/scripts/prepare-database.js

@@ -1,3 +1,11 @@
 import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
 
+try {
+  process.loadEnvFile(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
 await prepareDatabaseFromApp({ client: "pg", environment: process.env });

package/skills/jskit/references/patterns/database/table-resource/PATTERN.md

@@ -0,0 +1,117 @@
+---
+id: database/table-resource
+title: Table resource
+summary: Describe one database table once (its fields, columns, ownership, search and sort) so its owner feature reads and writes it through a scoped handle.
+keywords: database, defaultTo, defineTableResource, lockVersionField, lookup, owns, ownership, resource, table, workspace_or_shared
+requires: @jskit-ai/resource-core
+---
+
+# Table resource
+
+## Use when
+
+Use this pattern for every table an application owns, whether or not it is
+served over HTTP. The table resource is the table's one description; the
+feature that owns the table lists it in `owns`, and every read and write goes
+through the handle setup receives
+([data access](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access)).
+
+## Do not use when
+
+Do not describe a table twice, and do not describe another feature's table:
+ask its owner. A table with standard screens over HTTP adds a CRUD contract on
+this resource (`crud/crud-contract`), not a second resource.
+
+## Product decisions
+
+- who owns a row, always stated: nobody (`public`), a workspace, a user, a
+  user inside a workspace, or a workspace with rows shared with every
+  workspace
+- the fields, which are required, searchable or hidden, and their defaults
+- whether people edit records from forms read earlier (a version number)
+- the default order of lists
+
+## Invariants
+
+- One table, one table resource, one owner feature.
+- `ownership` matches the owner columns: `workspace` filters on the hidden
+  `workspaceId` field, `user` on `userId`, `workspace_user` on both, and
+  `workspace_or_shared` reads a workspace's rows plus the rows whose
+  `workspaceId` is null. The handle adds that predicate to every statement and
+  stamps new rows from the caller's context.
+- A field's default value is `defaultTo`; `default` is refused, since
+  json-rest-api never read it.
+- A field with `defaultTo` is not `required`: a create is checked for
+  required fields before defaults apply, so `defineTableResource` refuses the
+  two together.
+- `lockVersionField` names an integer field over a non-null integer column
+  with a starting value; `patch(id, changes, { ...options, lockVersion })` then refuses
+  stale edits with a 409.
+- The definition is shared with the client, so it holds no server-only keys:
+  the row policy, hooks, server-only search entries and computed query fields
+  go in the owner's `owns` entry.
+- The source-controlled migration and the resource describe the same table.
+
+## Framework APIs
+
+`defineTableResource()` from `@jskit-ai/resource-core/shared/tableResource`
+freezes the description and refuses the CRUD contract's keys (`namespace`,
+`apiAccess`, `operations`, `messages`), `autofilter` and the server-only keys,
+each with an error naming where it belongs.
+
+A field that looks up a record of another resource names that resource's
+namespace with `lookup`:
+
+```js
+customerId: { type: "id", required: true, search: true, lookup: "customers" }
+```
+
+`defineTableResource()` expands it, where `lookup` stood, to:
+
+```js
+relation: { kind: "lookup", namespace: "customers", valueKey: "id" },
+belongsTo: "customers",  // the table resource named by the namespace, camel-cased
+as: "customer",          // the field key without its Id suffix
+ui: { formControl: "autocomplete" }
+```
+
+Keys you write beside `lookup` win: `belongsTo` and `as` replace the
+filled-in values, and `relation` and `ui` are merged over them. A field whose
+key has no `Id` suffix must write `as`.
+
+The owner, on the server:
+
+```js
+const OrdersFeature = defineFeature({
+  id: "orders",
+  owns: [{ resource: orderResource, rowPolicy: ordersTheActorMayHandle }],
+  provides: { orders: "orders" },
+  setup: ({ resources }) => ({ orders: createOrdersRepository({ orders: resources.orders }) })
+});
+```
+
+## Example files
+
+- `example/orderResource.js` is a workspace-owned orders table with a lookup,
+  defaults, a version number, a text search and a default sort.
+
+## Variation points
+
+Rename the table and fields, pick the ownership kind the product's owner
+columns support, add search entries and sorts. A computed output field is
+`storage: { virtual: true }` here and a `queryFields` entry in `owns`.
+
+## Verification
+
+- Import the resource and check its ownership, fields and lookups.
+- Rebuild the table from source-controlled migrations in a disposable database.
+- Give each repository path a scope test (`expectScoped`) and a flat-query
+  test (`expectFlatQueries`) from `@jskit-ai/resource-runtime/test`.
+
+## Avoid
+
+- a second table resource for the same table
+- `where workspace_id = ?` written by hand: ownership adds it
+- a row policy, hooks or SQL in the shared definition
+- `default:` instead of `defaultTo:`
+- `required: true` beside `defaultTo`

package/skills/jskit/references/patterns/database/table-resource/example/orderResource.js

@@ -0,0 +1,25 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+
+// The orders table: one workspace owns each row. Shared with the client; the
+// owner feature lists it in `owns` on the server.
+const orderResource = defineTableResource({
+  name: "orders",
+  tableName: "orders",
+  ownership: "workspace",
+  lockVersionField: "lockVersion",
+  schema: {
+    workspaceId: { type: "id", required: true, hidden: true },
+    customerId: { type: "id", required: true, search: true, lookup: "customers" },
+    reference: { type: "string", maxLength: 64, required: true, search: true },
+    status: { type: "string", maxLength: 32, search: true, defaultTo: "open" },
+    total: { type: "number", defaultTo: 0 },
+    lockVersion: { type: "integer", min: 0, readOnly: true, defaultTo: 0 },
+    createdAt: { type: "dateTime", temporalPrecision: 0, readOnly: true }
+  },
+  searchSchema: {
+    q: { type: "string", oneOf: ["reference"], filterOperator: "like" }
+  },
+  defaultSort: ["-createdAt"]
+});
+
+export { orderResource };

package/skills/jskit/references/patterns/realtime/realtime-application/PATTERN.md

@@ -43,6 +43,13 @@ name and audience. Client features use `RealtimeClientProvider` and the public
 listener registration helpers from `@jskit-ai/realtime`. Use the normal shell
 placement registry for the optional status component.
 
+An audience's `audienceUsers({ event, options })` reads in a context scoped to
+the event's workspace, user or workspace user. An application whose action
+events declare such an audience registers `RealtimeAudienceScopeFeature` from
+`@jskit-ai/realtime/server/RealtimeAudienceScopeFeature`, which provides those
+contexts, or realtime refuses to boot. An audience that reads only public
+tables marks itself `publicTablesOnly: true` and reads with no context.
+
 ## Example files
 
 `example/package.json` declares realtime and shell runtime packages.

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.2.19",
-    "@jskit-ai/shell-web": "0.2.16"
+    "@jskit-ai/realtime": "0.2.20",
+    "@jskit-ai/shell-web": "0.2.17"
   }
 }

package/skills/jskit/references/patterns/rewards/google-rewarded/PATTERN.md

@@ -38,7 +38,7 @@ capability composition beside `RewardedClientProvider` from
 `client.rewarded-delivery`; the generic UI supplies `client.rewarded`.
 Use `useRewardedRuntime().requireUnlock({ gateKey, workspaceSlug })` for gates.
 Separately supply server capability `rewarded.grant-policy` with
-`authorizeGrant({ session, context, trx })`; only `true` permits a grant.
+`authorizeGrant({ session, context, options })`; only `true` permits a grant.
 This delivery example does not provide or choose the server policy.
 
 ## Example files

package/skills/jskit/references/patterns/server/feature-package/PATTERN.md

@@ -2,7 +2,7 @@
 id: server/feature-package
 title: App-local server feature package
 summary: Define a server feature through explicit capabilities and first-class actions, adding services or repositories only when its domain earns them.
-keywords: actions, feature, json-rest, knex, orchestration, package, provider, repository, routes, server
+keywords: actions, aggregate, feature, handle, orchestration, owns, package, provider, repository, routes, server, table resource
 requires: @jskit-ai/kernel
 ---
 
@@ -17,16 +17,18 @@ actions whose implementations capture those exact dependencies.
 
 The concrete `booking-engine` example is intentionally repository-free. The
 `variations/` directory preserves the two important escalations: a meaningful
-orchestration service and an explicit custom Knex repository for a domain that
-cannot fit the normal resource APIs.
+orchestration service and a repository over a table the feature owns, for a
+domain whose operations are not CRUD screens.
 
 ## Do not use when
 
 Do not create a package for a tiny composition callback or one route with no
-domain behavior. Use the CRUD resource patterns when ordinary resource
-operations fit. Do not select custom Knex merely because SQL is familiar; it
-is an explicit exception for persistence behavior the higher-level APIs cannot
-express.
+domain behavior. Use the CRUD feature pattern when the table's operations are
+screens over HTTP. Do not reach for Knex because SQL is familiar: a table's
+reads and writes go through its handle, and a report the handle cannot express
+is one `scopedQuery()` method, as the
+[data access guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access)
+says.
 
 ## Product decisions
 
@@ -50,7 +52,7 @@ questionnaire.
 - Every factory, action creator and hook that receives a collaborator names its
   type in a JSDoc `@param`: `import("./types.js").<Name>` or
   `ReturnType<typeof createX>` inside the package, the owner's `./server/types`
-  across packages; a Knex client is database-runtime's `RuntimeKnex`.
+  across packages; a table's handle is resource-runtime's `ResourceHandle`.
 - Collaborators are required. There is no `= null`, `= {}` or no-op default,
   no `typeof` probe, no optional call and no "requires x" guard: the capability
   runtime refuses to start without a required token.
@@ -80,9 +82,11 @@ questionnaire.
 - One copy of each pure helper per package, imported directly. Files stay under
   750 lines and functions under 600, one concern per factory.
 - The service orchestrates the feature and does not issue SQL directly.
-- A repository owns persistence and accepts transaction/context options.
-- The normal persistence lane uses a public or documented high-level resource
-  API; custom Knex is an explicit, reviewed exception.
+- A feature that owns a table lists its table resource in `owns`; setup
+  receives the table's handle, and only its repository uses it. One table has
+  one owner.
+- A repository holds the owner's queries on its handles and passes each call's
+  options (context and transaction) on.
 - Ordinary HTTP and assistant exposure is projected from actions. Explicit
   route code exists only for a genuinely custom transport.
 - Register routes, actions, contributors, and other catalogue entries during
@@ -97,8 +101,8 @@ questionnaire.
 The provider uses `defineFeature()` from
 `@jskit-ai/kernel/server/features`. The runtime supplies named capabilities
 and the feature publishes its actions through the dedicated action catalogue.
-The custom persistence variation uses `createWithTransaction()` from
-`@jskit-ai/database-runtime/shared`.
+The persistence variation owns its table with `defineFeature({ owns })` and
+reads totals with the handle's `aggregate()`.
 
 ## Example files
 
@@ -147,9 +151,11 @@ const SeasonalAvailabilityFeature = defineFeature({
 `example/variations/availabilityEngineActions.js` and
 `example/variations/orchestratorService.js` show the repository-free lane.
 `example/variations/InvoiceRollupFeature.js`,
-`example/variations/invoiceRollupActions.js` and
-`example/variations/customKnexRepository.js` show the explicit custom
-persistence lane. `example/variations/types.js` declares the
+`example/variations/invoiceRollupActions.js`,
+`example/variations/invoiceResource.js` and
+`example/variations/ownedTableRepository.js` show the persistence lane: the
+feature owns the invoices table, and its repository reads monthly totals with
+`aggregate()`, scoped to the caller's workspace by the handle. `example/variations/types.js` declares the
 `AvailabilityEngine` and `InvoiceRollup` types.
 
 The [typed features guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features)
@@ -172,7 +178,9 @@ illustrative status query with narrow product language before shipping.
   denied access.
 - Exercise HTTP routes only when the package owns them.
 - Test service orchestration independently from persistence.
-- Test repository transaction and context forwarding.
+- Test each repository path against a second workspace's rows
+  (`expectScoped`) and at two sizes (`expectFlatQueries`), from
+  `@jskit-ai/resource-runtime/test`.
 - Rebuild any schema from immutable migrations in a disposable database.
 - Run the app's package, server, and integration verification.
 

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/kernel": "0.2.14",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/server/feature-package/example/variations/InvoiceRollupFeature.js

@@ -1,19 +1,18 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { createInvoiceRollup } from "./customKnexRepository.js";
+import { invoiceResource } from "./invoiceResource.js";
+import { createInvoiceRollup } from "./ownedTableRepository.js";
 import { createInvoiceRollupActions } from "./invoiceRollupActions.js";
 
 const InvoiceRollupFeature = defineFeature({
   id: "feature.invoice-rollup",
   domain: "invoices",
-  requires: {
-    database: "runtime.database"
-  },
+  owns: [invoiceResource],
   provides: {
     invoiceRollup: "feature.invoice-rollup"
   },
-  /** @param {{ database: import("@jskit-ai/database-runtime/server/types").RuntimeDatabase }} capabilities */
-  setup({ database }) {
-    return { invoiceRollup: createInvoiceRollup({ knex: database.knex }) };
+  /** @param {{ resources: { invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle } }} capabilities */
+  setup({ resources }) {
+    return { invoiceRollup: createInvoiceRollup({ invoices: resources.invoices }) };
   },
   actions({ invoiceRollup }) {
     return createInvoiceRollupActions({ invoiceRollup });