@jskit-ai/agent-docs 0.1.283 → 0.1.284

package/patterns/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/patterns/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/patterns/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 });

package/patterns/feature-package/example/variations/invoiceResource.js

@@ -0,0 +1,15 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+
+/** The invoices table: its fields, and the workspace that owns each row. Shared with the client. */
+const invoiceResource = defineTableResource({
+  name: "invoices",
+  tableName: "invoices",
+  ownership: "workspace",
+  schema: {
+    status: { type: "string", required: true, search: true },
+    amount: { type: "number", required: true },
+    issuedAt: { type: "dateTime", required: true }
+  }
+});
+
+export { invoiceResource };

package/patterns/feature-package/example/variations/invoiceRollupActions.js

@@ -1,6 +1,6 @@
 import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 
-const ACTION_GET_ROLLUP_STATUS = "invoices.rollup.status.read";
+const ACTION_READ_MONTHLY_TOTALS = "invoices.rollup.monthly-totals.read";
 
 /** The fields every invoice rollup query shares, spread first into each definition: they run on the admin surface. */
 const ROLLUP_QUERY = Object.freeze({
@@ -15,12 +15,12 @@ function createInvoiceRollupActions({ invoiceRollup }) {
   return Object.freeze([
     Object.freeze({
       ...ROLLUP_QUERY,
-      id: ACTION_GET_ROLLUP_STATUS,
+      id: ACTION_READ_MONTHLY_TOTALS,
       input: emptyInputValidator,
       output: null,
-      execute: (input, context) => invoiceRollup.getStatus(input, { context })
+      execute: (input, context) => invoiceRollup.totalsByMonth(input, { context })
     })
   ]);
 }
 
-export { ACTION_GET_ROLLUP_STATUS, createInvoiceRollupActions };
+export { ACTION_READ_MONTHLY_TOTALS, createInvoiceRollupActions };

package/patterns/feature-package/example/variations/ownedTableRepository.js

@@ -0,0 +1,27 @@
+/**
+ * The invoice rollup's persistence: the queries of the invoices table its
+ * feature owns, on that table's handle. The handle adds the workspace to every
+ * statement, so no query names it.
+ * @param {{ invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle }} dependencies
+ */
+function createInvoiceRollup({ invoices }) {
+  /**
+   * How many invoices of each status the workspace issued each month, and their total.
+   * @param {Record<string, never>} input
+   * @param {import("@jskit-ai/resource-runtime/server/types").ResourceCallOptions} options
+   */
+  function totalsByMonth(input, options) {
+    return invoices.aggregate({
+      groupBy: ["status", { field: "issuedAt", bucket: "month", as: "month" }],
+      measures: { invoices: { count: "*" }, amount: { sum: "amount" } },
+      sort: ["month"]
+    }, options);
+  }
+
+  return Object.freeze({
+    withTransaction: invoices.withTransaction,
+    totalsByMonth
+  });
+}
+
+export { createInvoiceRollup };

package/patterns/feature-package/example/variations/types.js

@@ -2,6 +2,6 @@
 // capabilities, for features that require them.
 
 /** @typedef {ReturnType<typeof import("./orchestratorService.js").createAvailabilityEngine>} AvailabilityEngine */
-/** @typedef {ReturnType<typeof import("./customKnexRepository.js").createInvoiceRollup>} InvoiceRollup */
+/** @typedef {ReturnType<typeof import("./ownedTableRepository.js").createInvoiceRollup>} InvoiceRollup */
 
 export {};

package/patterns/minimal-foundation/example/AGENTS.md

@@ -8,6 +8,10 @@ Framework references:
 - `https://mobily-enterprises.github.io/jskit-ai/guide/`
 - `https://mobily-enterprises.github.io/jskit-ai/patterns/`
 
+Before writing or reviewing code that reads or writes a database table, read
+the data access guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access`.
+
 Before writing or reviewing server code (a feature, provider, action, service,
 repository, route, error or test), read the typed features guide at
 `https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features`.

package/patterns/minimal-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/kernel": "0.2.14",
     "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,13 +44,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.13",
+    "@jskit-ai/http-runtime": "0.2.14",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.246",
-    "@jskit-ai/jskit-catalog": "0.2.35",
+    "@jskit-ai/config-eslint": "0.1.247",
+    "@jskit-ai/jskit-catalog": "0.2.36",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/server.js

@@ -1,6 +1,6 @@
 import Fastify from "fastify";
 import SerializerSelector from "@fastify/fast-json-stringify-compiler";
-import { createCachedResponseSerializerFactory } from "@jskit-ai/kernel/server/http";
+import { createCachedResponseSerializerFactory, resolveTrustedProxies } from "@jskit-ai/kernel/server/http";
 import fastifyStatic from "@fastify/static";
 import { buildLoggerOptions } from "./server/lib/loggerOptions.js";
 import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
@@ -94,6 +94,9 @@ function canServeStaticFile(distRoot, relativePath) {
 async function createServer({ runtimeEnv }) {
   const app = Fastify({
     logger: buildLoggerOptions(),
+    // The proxies in front of the server (TRUSTED_PROXIES; loopback without it), so request.ip and the rate limits
+    // counted by it are each client's address behind them.
+    trustProxy: resolveTrustedProxies(runtimeEnv),
     schemaController: {
       compilersFactory: {
         buildSerializer: createCachedResponseSerializerFactory(SerializerSelector())

package/patterns/shell-foundation/example/AGENTS.md

@@ -8,6 +8,10 @@ Framework references:
 - `https://mobily-enterprises.github.io/jskit-ai/guide/`
 - `https://mobily-enterprises.github.io/jskit-ai/patterns/`
 
+Before writing or reviewing code that reads or writes a database table, read
+the data access guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access`.
+
 Before writing or reviewing server code (a feature, provider, action, service,
 repository, route, error or test), read the typed features guide at
 `https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features`.

package/patterns/shell-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/kernel": "0.2.14",
     "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,14 +44,14 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.13",
-    "@jskit-ai/shell-web": "0.2.16",
+    "@jskit-ai/http-runtime": "0.2.14",
+    "@jskit-ai/shell-web": "0.2.17",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.246",
-    "@jskit-ai/jskit-catalog": "0.2.35",
+    "@jskit-ai/config-eslint": "0.1.247",
+    "@jskit-ai/jskit-catalog": "0.2.36",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.13"
+    "@jskit-ai/kernel": "0.2.14"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/shell-foundation/example/server.js

@@ -1,6 +1,6 @@
 import Fastify from "fastify";
 import SerializerSelector from "@fastify/fast-json-stringify-compiler";
-import { createCachedResponseSerializerFactory } from "@jskit-ai/kernel/server/http";
+import { createCachedResponseSerializerFactory, resolveTrustedProxies } from "@jskit-ai/kernel/server/http";
 import fastifyStatic from "@fastify/static";
 import { buildLoggerOptions } from "./server/lib/loggerOptions.js";
 import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
@@ -94,6 +94,9 @@ function canServeStaticFile(distRoot, relativePath) {
 async function createServer({ runtimeEnv }) {
   const app = Fastify({
     logger: buildLoggerOptions(),
+    // The proxies in front of the server (TRUSTED_PROXIES; loopback without it), so request.ip and the rate limits
+    // counted by it are each client's address behind them.
+    trustProxy: resolveTrustedProxies(runtimeEnv),
     schemaController: {
       compilersFactory: {
         buildSerializer: createCachedResponseSerializerFactory(SerializerSelector())

package/reference/autogen/KERNEL_MAP.md

@@ -373,11 +373,12 @@ Exports
 ### `capabilities/defineProvider.js`
 Exports
 - `ARCHITECTURE_ID_PATTERN`
-- `defineProvider({ id, requires = {}, optional = {}, provides = {}, setup, boot = null, shutdown = null } = {})`
+- `defineProvider({ id, requires = {}, optional = {}, provides = {}, hints = {}, setup, boot = null, shutdown = null } = {})`
 - `normalizeArchitectureId(value, label)`
 - `type ProviderDefinition`
 Local functions
 - `normalizeCapabilityMap(value, label)`
+- `normalizeHints(value, requires, providerId)`
 - `assertDistinctLocalNames(maps)`
 - `normalizeLifecycleMethod(value, label)`