@jskit-ai/payments-core 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+- `@jskit-ai/database-runtime` and `@jskit-ai/resource-runtime` are optional peer dependencies, as they are of assistant-runtime, instead of dependencies: an app without a database installs, composes and starts the package without them, where installing them made boot refuse it for want of a database driver. An app that uses its payment store has them through its database.
+- On json-rest-api 3.0.0's release candidate, an account's changed state is written with one read of the locked row before its UPDATE, where it took two.
+- The payment store locks or creates each account and catalogue row with its handle's `lockOrCreate`, in place of a helper of its own with the same behaviour.
+- Breaking: `createKnexPaymentStore` is gone, so the payment tables have one owner, `PaymentStoreFeature`. A JSKIT application registers it in its server providers and composes billing on the `payments.store` it provides; a script or CLI starts it in a capability runtime of its own on the application's Knex, as `docs/standalone.md` shows. `createPaymentService` given no store names that fix, and a missing configuration names `validatePaymentConfiguration`.
+- `withAccount` and `withCatalogue` create a missing account or catalogue row inside the work's own transaction (an insert that skips an existing id), so work that fails leaves no row behind. Two first uses of one key that collide on that insert before either work runs (a deadlock on MySQL's and MariaDB's gap locks, a duplicate key elsewhere) run the loser again, up to three times; work that has started never runs again. An existing row costs one locking read, where the store read it once outside the transaction and again under the lock, and work that leaves the state as it was (a duplicate grant, a read) writes nothing.
+
 ## 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".

package/README.md

@@ -24,7 +24,11 @@ they are not an editor configuration database.
 Public API imports:
 
 - `@jskit-ai/payments-core/shared`: `validatePaymentConfiguration(document)`.
-- `@jskit-ai/payments-core/server/storage`: `createKnexPaymentStore({ knex })`.
+- `@jskit-ai/payments-core/server/storage`: `PaymentStoreFeature`, the payment
+  tables' one owner: registered in the server providers, it owns them through
+  `runtime.resources` and provides the payment store as `payments.store`. A
+  script or CLI starts it in a capability runtime of its own
+  ([standalone setup](docs/standalone.md#payments-from-a-script-or-cli)).
 - `@jskit-ai/payments-core/server`: `createPaymentService({ store, configuration, clock })`.
 - `@jskit-ai/payments-core/server/stripe`: `createStripePaymentAdapter(options)`.
 - `@jskit-ai/payments-core/server/paddle`: `createPaddlePaymentAdapter(options)`.

package/docs/standalone.md

@@ -81,9 +81,12 @@ values, including the placeholder `MISSING`, must fail setup visibly.
 
 ## Compose the server libraries
 
-This is application startup code. `knex`, `authorizeBilling`, `applicationId`,
-`environment` and `configurationUrl` are supplied by the application's existing
-server composition. Select them on the server. `applicationId` is a durable
+This is application startup code, in a server provider that requires
+`payments.store`: the payment store of `PaymentStoreFeature` (from
+`@jskit-ai/payments-core/server/storage`), which the application registers in
+its server providers as the payment tables' one owner. `store`,
+`authorizeBilling`, `applicationId`, `environment` and `configurationUrl` are
+supplied by the application's existing server composition. Select them on the server. `applicationId` is a durable
 application identity, not its current domain. The environment is explicitly
 `sandbox` or `live`; do not silently fall back between them.
 
@@ -91,7 +94,6 @@ application identity, not its current domain. The environment is explicitly
 import { readFile } from 'node:fs/promises';
 import { createEnvironmentReferenceResolver } from '@jskit-ai/connectors-core/server';
 import { validatePaymentConfiguration } from '@jskit-ai/payments-core/shared';
-import { createKnexPaymentStore } from '@jskit-ai/payments-core/server/storage';
 import { createPaymentService } from '@jskit-ai/payments-core/server';
 import { createStripePaymentAdapter } from '@jskit-ai/payments-core/server/stripe';
 import { createPaymentCheckoutService } from '@jskit-ai/payments-core/server/checkout';
@@ -114,7 +116,6 @@ const merchantScope = {
   applicationId, integrationId: binding.integrationId,
   providerAccountId: binding.providerAccountId, environment
 };
-const store = createKnexPaymentStore({ knex });
 const payments = createPaymentService({ store, configuration });
 const published = await store.inspectCatalogue(merchantScope);
 const priceBindings = Object.fromEntries(Object.entries(published.plans)
@@ -152,6 +153,36 @@ preserving the unmodified request Buffer. Enforce features using
 using a stable business-operation reference. A successful checkout redirect is
 not proof of payment: verified provider reconciliation updates access and credits.
 
+## Payments from a script or CLI
+
+Code outside the server, such as a CLI that publishes the catalogue, starts
+`PaymentStoreFeature` in a capability runtime of its own on the application's
+Knex, so the payment tables keep one owner:
+
+```js
+import { ActionProvider } from '@jskit-ai/kernel/server/actions';
+import { EventProvider } from '@jskit-ai/kernel/server/runtime';
+import { silentLogger } from '@jskit-ai/kernel/server/runtime/logger';
+import { createCapabilityRuntime, defineProvider } from '@jskit-ai/kernel/shared/capabilities';
+import { ResourceRuntimeProvider } from '@jskit-ai/resource-runtime/server';
+import { PaymentStoreFeature } from '@jskit-ai/payments-core/server/storage';
+
+let store;
+const runtime = createCapabilityRuntime({
+  inputs: { 'runtime.logger': silentLogger },
+  providers: [
+    EventProvider,
+    ActionProvider,
+    defineProvider({ id: 'cli.database', provides: { database: 'runtime.database' }, setup: () => ({ database: { knex } }) }),
+    ResourceRuntimeProvider,
+    PaymentStoreFeature,
+    defineProvider({ id: 'cli.payments', requires: { payments: 'payments.store' }, setup({ payments }) { store = payments; } })
+  ]
+});
+await runtime.start();
+// ... compose the services above on `store`, then `await runtime.shutdown()` and destroy the Knex.
+```
+
 ## Paddle composition
 
 Use `createPaddlePaymentAdapter` from `@jskit-ai/payments-core/server/paddle`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/payments-core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "Application-owned payment configuration, subscription access and transactional usage credits.",
   "exports": {
@@ -10,7 +10,7 @@
     "./docs/contract.md": "./docs/contract.md",
     "./docs/conformance.md": "./docs/conformance.md",
     "./server": "./src/server/service.js",
-    "./server/storage": "./src/server/knexStore.js",
+    "./server/storage": "./src/server/storage.js",
     "./server/checkout": "./src/server/checkout.js",
     "./server/stripe": "./src/server/stripe.js",
     "./server/paddle": "./src/server/paddle.js",
@@ -20,9 +20,10 @@
     "./locales/en.json": "./locales/en.json"
   },
   "scripts": {
-    "test": "node --test --test-concurrency=1"
+    "test": "jskit test"
   },
   "dependencies": {
+    "@jskit-ai/resource-core": "0.1.205",
     "@paddle/paddle-node-sdk": "3.10.0",
     "ajv": "8.20.0",
     "stripe": "22.6.2"
@@ -66,5 +67,18 @@
         "providers": []
       }
     }
+  },
+  "peerDependencies": {
+    "@jskit-ai/database-runtime": "0.1.263",
+    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/resource-runtime": "0.2.12"
+  },
+  "peerDependenciesMeta": {
+    "@jskit-ai/database-runtime": {
+      "optional": true
+    },
+    "@jskit-ai/resource-runtime": {
+      "optional": true
+    }
   }
 }

package/src/server/PaymentStoreFeature.js

@@ -0,0 +1,28 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { PAYMENT_TABLES } from "./paymentResources.js";
+import { createPaymentStore } from "./paymentStore.js";
+
+const PAYMENT_STORE_FEATURE = "payments.store";
+const PAYMENT_STORE_SYSTEM_SCOPE = "payment rows are keyed by their merchant and billable subject, which is their scope, not by a workspace or user";
+
+// The owner of the payment tables in a JSKIT application: it provides the payment store on their handles as
+// `payments.store`. An application that keeps payments elsewhere passes its own store and leaves this feature out.
+const PaymentStoreFeature = defineFeature({
+  id: PAYMENT_STORE_FEATURE,
+  domain: "payments",
+  owns: PAYMENT_TABLES,
+  systemScope: PAYMENT_STORE_SYSTEM_SCOPE,
+  provides: {
+    store: "payments.store"
+  },
+  /**
+   * @param {object} dependencies
+   * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources
+   * @param {(reason: string) => import("@jskit-ai/resource-runtime/server/types").SystemContext} dependencies.systemContext
+   */
+  setup({ resources, systemContext }) {
+    return { store: createPaymentStore({ resources, systemContext }) };
+  }
+});
+
+export { PAYMENT_STORE_FEATURE, PAYMENT_STORE_SYSTEM_SCOPE, PaymentStoreFeature };

package/src/server/paymentResources.js

@@ -0,0 +1,71 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { normalizeOpaqueId } from "@jskit-ai/kernel/shared/support/normalize";
+
+// The payment tables. Each row is keyed by a fingerprint of its merchant (and, for accounts and their entries, its
+// billable subject), not by a workspace or user column: the key is the row's scope, so the tables are public to their
+// owner feature, which reaches them only through keys it computes from a caller's merchant and subject.
+
+// A string key the store computes; text is kept exactly as written.
+const key = (column) => Object.freeze({ type: "string", primary: true, required: true, storage: { column } });
+const text = Object.freeze({ type: "string", required: true, noTrim: true });
+
+// One billable subject's account under one merchant: its state as JSON.
+const paymentAccountResource = defineTableResource({
+  name: "paymentAccounts",
+  tableName: "payment_accounts",
+  ownership: "public",
+  idProperty: "account_key",
+  schema: {
+    id: key("account_key"),
+    payload: text
+  }
+});
+
+// What an account recorded once under a business reference, keyed by the account and the reference.
+const paymentEntryResource = defineTableResource({
+  name: "paymentEntries",
+  tableName: "payment_entries",
+  ownership: "public",
+  idProperty: "entry_key",
+  schema: {
+    id: key("entry_key"),
+    accountKey: { ...text, storage: { column: "account_key" } },
+    payload: text
+  }
+});
+
+// The billable subject a provider customer is bound to, per merchant.
+const paymentCustomerResource = defineTableResource({
+  name: "paymentCustomers",
+  tableName: "payment_customers",
+  ownership: "public",
+  idProperty: "customer_key",
+  schema: {
+    id: key("customer_key"),
+    subjectId: { ...text, storage: { column: "subject_id" } }
+  }
+});
+
+// One merchant's published catalogue: its state as JSON.
+const paymentCatalogueResource = defineTableResource({
+  name: "paymentCatalogues",
+  tableName: "payment_catalogues",
+  ownership: "public",
+  idProperty: "catalogue_key",
+  schema: {
+    id: key("catalogue_key"),
+    payload: text
+  }
+});
+
+// The feature's owns entries: each key is an opaque fingerprint, not a numeric id.
+const PAYMENT_TABLES = Object.freeze([paymentAccountResource, paymentEntryResource, paymentCustomerResource, paymentCatalogueResource]
+  .map((resource) => Object.freeze({ resource, normalizeId: normalizeOpaqueId })));
+
+export {
+  PAYMENT_TABLES,
+  paymentAccountResource,
+  paymentCatalogueResource,
+  paymentCustomerResource,
+  paymentEntryResource
+};

package/src/server/paymentStore.js

@@ -0,0 +1,104 @@
+import { PaymentError, fingerprint } from "./errors.js";
+
+const empty = () => ({ lots: [], subscriptions: {} });
+const emptyCatalogue = () => ({ plans: {}, history: [] });
+
+function merchant(scope) {
+  const fields = ["applicationId", "integrationId", "providerAccountId", "environment"];
+  for (const field of fields) {
+    if (typeof scope?.[field] !== "string" || !scope[field] || scope[field].length > 200) throw new TypeError(`Payment scope requires ${field}.`);
+  }
+  if (!["sandbox", "live"].includes(scope.environment)) throw new TypeError("Payment scope requires sandbox or live.");
+  return fields.map((field) => scope[field]);
+}
+function identifier(value) {
+  if (typeof value !== "string" || !value || value.length > 200) throw new TypeError("Payment identity is required (maximum 200 characters).");
+  return value;
+}
+const accountKey = (scope) => fingerprint([...merchant(scope), identifier(scope.subjectId)]);
+const customerKey = (scope, customerId) => fingerprint([...merchant(scope), identifier(customerId)]);
+const entryKey = (account, reference) => fingerprint([account, identifier(reference)]);
+
+/**
+ * The payment store on its table resources' handles: each account and each catalogue is one locked row holding its
+ * state as JSON, an account's entries are recorded once per reference, and a provider customer is bound to one
+ * subject per merchant. Every call works in a system context, because a row's scope is its key.
+ * @param {object} dependencies
+ * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources The handles of PAYMENT_TABLES.
+ * @param {(reason: string) => object} dependencies.systemContext
+ * @returns {import("./types.js").PaymentStore}
+ */
+function createPaymentStore({ resources, systemContext }) {
+  const { paymentAccounts: accounts, paymentEntries: entries, paymentCustomers: customers, paymentCatalogues: catalogues } = resources;
+  const accountOptions = Object.freeze({ context: systemContext("an account is read and changed by its merchant and subject key") });
+  const customerOptions = Object.freeze({ context: systemContext("a provider customer is bound and resolved by its merchant and customer key") });
+  const catalogueOptions = Object.freeze({ context: systemContext("a catalogue is read and changed by its merchant key") });
+
+  async function inspect(scope) {
+    const account = await accounts.get(accountKey(scope), {}, { ...accountOptions, missing: "skip" });
+    return account ? JSON.parse(account.payload) : empty();
+  }
+
+  async function withAccount(scope, work) {
+    const key = accountKey(scope);
+    // The retained account row serializes grants, usage, refunds and event handling.
+    return accounts.lockOrCreate({ id: key, payload: JSON.stringify(empty()) }, accountOptions, async (account, txOptions) => {
+      const state = JSON.parse(account.payload);
+      const stored = JSON.stringify(state);
+      const result = await work({
+        state,
+        async find(reference) {
+          const entry = await entries.get(entryKey(key, reference), {}, { ...txOptions, missing: "skip" });
+          return entry ? JSON.parse(entry.payload) : null;
+        },
+        async record(reference, payload) {
+          await entries.create({ id: entryKey(key, reference), accountKey: key, payload: JSON.stringify(payload) }, { ...txOptions, returning: "none" });
+        }
+      });
+      // Work that leaves the state as it was, such as a duplicate grant, writes nothing.
+      const payload = JSON.stringify(state);
+      if (payload !== stored) await accounts.patch(key, { payload }, { ...txOptions, returning: "none" });
+      return result;
+    });
+  }
+
+  async function bindCustomer(scope, customerId, subjectId) {
+    const id = customerKey(scope, customerId);
+    identifier(subjectId);
+    const bound = await customers.findOrCreate({ id, subjectId }, customerOptions);
+    if (bound.subjectId !== subjectId) throw new PaymentError("payment_customer_conflict", "This provider customer is already bound to a different billable subject.", 409);
+  }
+
+  async function resolveCustomer(scope, customerId) {
+    const bound = await customers.get(customerKey(scope, customerId), {}, { ...customerOptions, missing: "skip" });
+    return bound?.subjectId ?? null;
+  }
+
+  async function inspectCatalogue(scope) {
+    const catalogue = await catalogues.get(fingerprint(merchant(scope)), {}, { ...catalogueOptions, missing: "skip" });
+    return catalogue ? JSON.parse(catalogue.payload) : emptyCatalogue();
+  }
+
+  async function withCatalogue(scope, work) {
+    const key = fingerprint(merchant(scope));
+    return catalogues.lockOrCreate({ id: key, payload: JSON.stringify(emptyCatalogue()) }, catalogueOptions, async (catalogue, txOptions) => {
+      const state = JSON.parse(catalogue.payload);
+      const stored = JSON.stringify(state);
+      const result = await work(state);
+      const payload = JSON.stringify(state);
+      if (payload !== stored) await catalogues.patch(key, { payload }, { ...txOptions, returning: "none" });
+      return result;
+    });
+  }
+
+  return Object.freeze({
+    inspect,
+    withAccount,
+    bindCustomer,
+    resolveCustomer,
+    inspectCatalogue,
+    withCatalogue
+  });
+}
+
+export { createPaymentStore };

package/src/server/service.js

@@ -48,9 +48,15 @@ async function grant(tx, { reference: id, units: quantity, expiresAt }, now) {
  * @param {() => number} [dependencies.clock]
  */
 function createPaymentService({ store, configuration, clock = Date.now }) {
-  // readable-check: allow method-probe - input validation: the application passes its own payment store and validated configuration
-  if (typeof store?.withAccount !== "function" || typeof store?.inspect !== "function" || !configuration?.plans) {
-    throw new TypeError("Supply payment storage and validated payment configuration.");
+  // readable-check: allow method-probe - input validation: the application passes its own payment store
+  if (typeof store?.withAccount !== "function" || typeof store?.inspect !== "function") {
+    throw new TypeError(
+      "createPaymentService requires a payment store: register PaymentStoreFeature from @jskit-ai/payments-core/server/storage " +
+      "in your server providers and pass the payments.store it provides."
+    );
+  }
+  if (!configuration?.plans) {
+    throw new TypeError("createPaymentService requires validated payment configuration: pass validatePaymentConfiguration(document) from @jskit-ai/payments-core/shared.");
   }
   const plans = structuredClone(configuration.plans);
   const environments = structuredClone(configuration.environments);

package/src/server/storage.js

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

package/src/server/types.js

@@ -50,8 +50,8 @@
  */
 
 /**
- * Where payment accounts and catalogues are kept: createKnexPaymentStore() or
- * the application's own store. Each `with*` call runs its work under the
+ * Where payment accounts and catalogues are kept: the store PaymentStoreFeature
+ * provides as `payments.store`, or the application's own store. Each `with*` call runs its work under the
  * record's lock and saves the state the work leaves.
  * @typedef {object} PaymentStore
  * @property {(scope: PaymentAccountScope) => Promise<PaymentAccountState>} inspect

package/test/catalogue.test.js

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import knex from 'knex';
 import migration from '../migrations/payments_core_initial.cjs';
-import { createKnexPaymentStore } from '../src/server/knexStore.js';
+import { createTestPaymentStore } from './support/paymentStore.js';
 import { createPaymentCatalogue } from '../src/server/catalogue.js';
 
 const scope = { applicationId: 'app', integrationId: 'billing', providerAccountId: 'acct_a', environment: 'sandbox' };
@@ -13,7 +13,7 @@ const config = { environments: { sandbox: { integrationId: 'billing', providerAc
 test('reviewed catalogue publication preserves IDs, handles drift, and recovers a partial write', async () => {
   const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   const products = new Map(); const prices = new Map();
   let writes = 0; let failPrice = false;
   const adapter = {
@@ -68,7 +68,7 @@ test('reviewed catalogue publication preserves IDs, handles drift, and recovers
 test('sandbox and live publish independently and cannot reuse each other’s review', async () => {
   const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   const configuration = structuredClone(config);
   configuration.environments.live = { integrationId: 'billing-live', providerAccountId: 'acct_live' };
   const liveScope = { ...scope, environment: 'live', ...configuration.environments.live };

package/test/checkout.test.js

@@ -5,7 +5,7 @@ import knex from 'knex';
 import Stripe from 'stripe';
 import { Paddle, Environment } from '@paddle/paddle-node-sdk';
 import migration from '../migrations/payments_core_initial.cjs';
-import { createKnexPaymentStore } from '../src/server/knexStore.js';
+import { createTestPaymentStore } from './support/paymentStore.js';
 import { createPaymentService } from '../src/server/service.js';
 import { createPaymentCheckoutService } from '../src/server/checkout.js';
 import { createStripePaymentAdapter } from '../src/server/stripe.js';
@@ -36,7 +36,7 @@ test('official SDK signature verification rejects mutation and expired delivery
 test('checkout authorizes before provider access, persists intent, deduplicates requests and needs explicit recovery', async () => {
   const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   let creates = 0;
   let fails = false;
   const adapter = {
@@ -163,7 +163,7 @@ test('Paddle reconciliation uses current status and grants only qualifying compl
 test('signed subscription lifecycle updates app access without crossing subjects or environments', async () => {
   const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   const stripeSdk = new Stripe('sk_test_fixture', { maxNetworkRetries: 0 });
   const paddleSdk = new Paddle('test-fixture', { environment: Environment.sandbox });
   try {

package/test/conformance.test.js

@@ -6,7 +6,7 @@ import knex from 'knex';
 import migration from '../migrations/payments_core_initial.cjs';
 import { validatePaymentConfiguration } from '../src/shared/configuration.js';
 import { createPaymentService } from '../src/server/service.js';
-import { createKnexPaymentStore } from '../src/server/knexStore.js';
+import { createTestPaymentStore } from './support/paymentStore.js';
 
 const fixture = JSON.parse(await readFile(new URL('../contracts/conformance.json', import.meta.url), 'utf8'));
 const schema = JSON.parse(await readFile(new URL('../contracts/configuration.schema.json', import.meta.url), 'utf8'));
@@ -53,7 +53,7 @@ test('portable account sequence defines actual credit, renewal, expiry and subje
   const scenario = fixture.accountScenario;
   const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   let now = scenario.clock;
   const service = createPaymentService({ store, configuration: validatePaymentConfiguration(scenario.document), clock: () => now });
   const { subjectId, ...merchant } = scenario.scope;

package/test/paymentStore.mysql.test.js

@@ -0,0 +1,396 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexLib from "knex";
+import { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+import migration from "../migrations/payments_core_initial.cjs";
+import { createPaymentService } from "../src/server/service.js";
+import { validatePaymentConfiguration } from "../src/shared/configuration.js";
+import { createTestPaymentStore } from "./support/paymentStore.js";
+
+// The payment store's behaviour on MariaDB, through its public functions, as PaymentStoreFeature provides it: what an
+// account, its entries, a provider customer and a merchant's catalogue answer and keep; which scope sees which rows;
+// that work on one account or catalogue runs one at a time and rolls back as a whole, its row's creation included; and
+// the errors it gives.
+
+// The runtime's own MySQL connection settings (database-runtime's resolveKnexConnectionFromEnvironment).
+const RUNTIME_MYSQL = Object.freeze({ supportBigNumbers: true, bigNumberStrings: true, dateStrings: ["DATE"], timezone: "Z" });
+
+/** A migrated database of the test's own, beside TEST_DB_NAME, dropped after the test. */
+async function ownDatabase(context, suffix) {
+  const name = `${requireTestDatabase(process.env)}_${suffix}`;
+  const server = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 3306, user: process.env.DB_USER, password: process.env.DB_PASSWORD };
+  const admin = knexLib({ client: "mysql2", connection: server, pool: { min: 0, max: 1 } });
+  await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+  await admin.raw("CREATE DATABASE ??", [name]);
+  const knex = knexLib({ client: "mysql2", connection: { ...server, database: name, ...RUNTIME_MYSQL }, pool: { min: 0, max: 6 } });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+    await admin.destroy();
+  });
+  await migration.up(knex);
+  return knex;
+}
+
+const merchant = Object.freeze({ applicationId: "app", integrationId: "billing", providerAccountId: "acct_test", environment: "sandbox" });
+const subject = (subjectId, changes = {}) => ({ ...merchant, ...changes, subjectId });
+const EMPTY_ACCOUNT = Object.freeze({ lots: [], subscriptions: {} });
+const EMPTY_CATALOGUE = Object.freeze({ plans: {}, history: [] });
+const IDENTITY_REQUIRED = { name: "TypeError", message: "Payment identity is required (maximum 200 characters)." };
+
+/** The rows in one of the payment tables (COUNT is a big number, which the runtime reads as a string). */
+async function rowCount(knex, table) {
+  const [{ rows }] = await knex(table).count({ rows: "*" });
+  return Number(rows);
+}
+
+/** A promise the test resolves itself, to hold one piece of work while others run. */
+function gate() {
+  let open;
+  const opened = new Promise((resolve) => {
+    open = resolve;
+  });
+  return { opened, open };
+}
+
+test("the store refuses incomplete scopes and identities before any work runs", async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_refusals"));
+  assert.ok(Object.isFrozen(store));
+  assert.deepEqual(Object.keys(store), ["inspect", "withAccount", "bindCustomer", "resolveCustomer", "inspectCatalogue", "withCatalogue"]);
+
+  for (const [changes, message] of [
+    [{ applicationId: "" }, "Payment scope requires applicationId."],
+    [{ integrationId: 7 }, "Payment scope requires integrationId."],
+    [{ providerAccountId: "a".repeat(201) }, "Payment scope requires providerAccountId."],
+    [{ environment: undefined }, "Payment scope requires environment."],
+    [{ environment: "production" }, "Payment scope requires sandbox or live."]
+  ]) {
+    await assert.rejects(store.inspect(subject("tenant-a", changes)), { name: "TypeError", message }, message);
+    await assert.rejects(store.inspectCatalogue({ ...merchant, ...changes }), { name: "TypeError", message }, message);
+    await assert.rejects(store.resolveCustomer({ ...merchant, ...changes }, "cus_1"), { name: "TypeError", message }, message);
+  }
+  // A field of exactly 200 characters is accepted.
+  assert.deepEqual(await store.inspect(subject("s".repeat(200), { providerAccountId: "p".repeat(200) })), EMPTY_ACCOUNT);
+
+  let worked = false;
+  const work = async () => {
+    worked = true;
+  };
+  await assert.rejects(store.inspect(merchant), IDENTITY_REQUIRED, "an account needs its subject");
+  await assert.rejects(store.inspect(subject("s".repeat(201))), IDENTITY_REQUIRED);
+  await assert.rejects(store.withAccount(merchant, work), IDENTITY_REQUIRED);
+  await assert.rejects(store.withAccount(subject("tenant-a", { environment: "test" })), { name: "TypeError", message: "Payment scope requires sandbox or live." });
+  await assert.rejects(store.withCatalogue({ ...merchant, applicationId: null }, work), { name: "TypeError", message: "Payment scope requires applicationId." });
+  assert.equal(worked, false, "no work runs for a refused scope");
+  await assert.rejects(store.bindCustomer(merchant, "", "tenant-a"), IDENTITY_REQUIRED);
+  await assert.rejects(store.bindCustomer(merchant, "cus_1", ""), IDENTITY_REQUIRED);
+  await assert.rejects(store.bindCustomer(merchant, "cus_1", 42), IDENTITY_REQUIRED);
+  await assert.rejects(store.resolveCustomer(merchant, "c".repeat(201)), IDENTITY_REQUIRED);
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), null, "the refused binding left nothing behind");
+});
+
+test("an account starts empty, keeps the state its work leaves as JSON, and answers what the work returns", async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_account"));
+  const scope = subject("tenant-a");
+
+  const fresh = await store.inspect(scope);
+  assert.deepEqual(fresh, EMPTY_ACCOUNT);
+  fresh.lots.push({ credits: 1 });
+  assert.deepEqual(await store.inspect(scope), EMPTY_ACCOUNT, "each inspect answers a new copy");
+
+  const result = await store.withAccount(scope, async (account) => {
+    assert.deepEqual(Object.keys(account).sort(), ["find", "record", "state"]);
+    assert.deepEqual(account.state, EMPTY_ACCOUNT, "a new account's work starts from the empty state");
+    account.state.lots.push({ credits: 5, grantedAt: new Date(Date.UTC(2026, 0, 1)), note: undefined });
+    account.state.subscriptions.pro = { status: "active" };
+    account.state.extra = { kept: true };
+    return { granted: 5 };
+  });
+  assert.deepEqual(result, { granted: 5 });
+  const expected = {
+    lots: [{ credits: 5, grantedAt: "2026-01-01T00:00:00.000Z" }],
+    subscriptions: { pro: { status: "active" } },
+    extra: { kept: true }
+  };
+  assert.deepEqual(await store.inspect(scope), expected, "the whole state is kept, as JSON: dates become text, undefined goes");
+
+  await store.withAccount(scope, async ({ state }) => {
+    assert.deepEqual(state, expected, "the next work starts from the kept state");
+  });
+  assert.deepEqual(await store.inspect(scope), expected, "work that changes nothing keeps the state");
+  assert.equal(await store.withAccount(scope, async () => undefined), undefined);
+});
+
+test("entries are recorded once per reference, read back by find, and belong to their own account", async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_entries"));
+  const scope = subject("tenant-a");
+
+  await store.withAccount(scope, async ({ find, record }) => {
+    assert.equal(await find("event:evt_1"), null);
+    assert.equal(await record("event:evt_1", { amount: 5, at: new Date(Date.UTC(2026, 1, 2)), skipped: undefined }), undefined);
+    assert.deepEqual(await find("event:evt_1"), { amount: 5, at: "2026-02-02T00:00:00.000Z" }, "seen at once inside the same work");
+  });
+  assert.deepEqual(await store.withAccount(scope, ({ find }) => find("event:evt_1")), { amount: 5, at: "2026-02-02T00:00:00.000Z" });
+
+  // Another subject, or the same subject under another merchant, has entries of its own.
+  for (const other of [subject("tenant-b"), subject("tenant-a", { environment: "live" }), subject("tenant-a", { applicationId: "other-app" })]) {
+    assert.equal(await store.withAccount(other, ({ find }) => find("event:evt_1")), null);
+  }
+  await store.withAccount(subject("tenant-b"), ({ record }) => record("event:evt_1", { amount: 9 }));
+  assert.deepEqual(await store.withAccount(subject("tenant-b"), ({ find }) => find("event:evt_1")), { amount: 9 });
+  assert.deepEqual(await store.withAccount(scope, ({ find }) => find("event:evt_1")), { amount: 5, at: "2026-02-02T00:00:00.000Z" });
+
+  // Recording a reference twice fails the whole work with the driver's own duplicate-key error (no PaymentError),
+  // and nothing the work did is kept.
+  await assert.rejects(store.withAccount(scope, async ({ state, record }) => {
+    state.lots.push({ credits: 1 });
+    await record("event:evt_1", { amount: 6 });
+  }), (error) => {
+    assert.equal(error.code, "ER_DUP_ENTRY");
+    assert.notEqual(error.name, "PaymentError");
+    return true;
+  });
+  assert.deepEqual(await store.inspect(scope), EMPTY_ACCOUNT);
+  assert.deepEqual(await store.withAccount(scope, ({ find }) => find("event:evt_1")), { amount: 5, at: "2026-02-02T00:00:00.000Z" });
+
+  await assert.rejects(store.withAccount(scope, ({ find }) => find("")), IDENTITY_REQUIRED);
+  await assert.rejects(store.withAccount(scope, ({ record }) => record("r".repeat(201), {})), IDENTITY_REQUIRED);
+  await assert.rejects(store.withAccount(scope, ({ find }) => find(7)), IDENTITY_REQUIRED);
+});
+
+test("work that fails rolls back its state and entries, and its error reaches the caller unchanged", async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_pay_rollback");
+  const store = await createTestPaymentStore(knex);
+  const scope = subject("tenant-a");
+  await store.withAccount(scope, async ({ state, record }) => {
+    state.lots.push({ credits: 1 });
+    await record("debit:first", { quantity: 1 });
+  });
+
+  const failure = new Error("provider unavailable");
+  await assert.rejects(store.withAccount(scope, async ({ state, record }) => {
+    state.lots.push({ credits: 2 });
+    state.subscriptions.pro = { status: "active" };
+    await record("debit:second", { quantity: 2 });
+    throw failure;
+  }), (error) => error === failure);
+  assert.deepEqual(await store.inspect(scope), { lots: [{ credits: 1 }], subscriptions: {} });
+  assert.deepEqual(await store.withAccount(scope, async ({ find }) => [await find("debit:first"), await find("debit:second")]), [{ quantity: 1 }, null]);
+
+  // A new account or catalogue whose first work fails leaves no row: its creation rolls back with the work.
+  await assert.rejects(store.withAccount(subject("tenant-new"), async ({ state }) => {
+    state.lots.push({ credits: 3 });
+    throw failure;
+  }), (error) => error === failure);
+  assert.deepEqual(await store.inspect(subject("tenant-new")), EMPTY_ACCOUNT);
+  await assert.rejects(store.withCatalogue(merchant, async (state) => {
+    state.history.push("never kept");
+    throw failure;
+  }), (error) => error === failure);
+  assert.equal(await rowCount(knex, "payment_accounts"), 1, "tenant-a's account alone");
+  assert.equal(await rowCount(knex, "payment_catalogues"), 0);
+});
+
+test("a reference granted again answers duplicate: true, also when two first grants on a new account race", { timeout: 20_000 }, async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_pay_duplicate");
+  const store = await createTestPaymentStore(knex);
+  const configuration = validatePaymentConfiguration({
+    integrations: { billing: { provider: "stripe", accountMode: "shared", authentication: { method: "api-key", secretRef: "env:STRIPE_KEY" } } },
+    extensions: { payments: {
+      version: 1,
+      environments: { sandbox: { integrationId: "billing", providerAccountId: "acct_test", webhookSecretRef: "env:STRIPE_WEBHOOK_SECRET", returnUrlRef: "env:APP_URL" } },
+      plans: { pro: { name: "Pro", amount: 1200, currency: "USD", interval: "month", features: [], renewalCredits: 100 } }
+    } }
+  });
+  const payments = createPaymentService({ store, configuration, clock: () => 1000 });
+  const grant = { reference: "welcome", units: 5, expiresAt: null };
+
+  assert.deepEqual(await payments.grantCredits(subject("tenant-a"), grant), { granted: 5, expiresAt: null, duplicate: false });
+  assert.deepEqual(await payments.grantCredits(subject("tenant-a"), grant), { granted: 5, expiresAt: null, duplicate: true });
+  assert.equal((await payments.inspect(subject("tenant-a"))).balance, 5);
+
+  // Two first grants on accounts that do not exist yet, each pair with one reference: each account is created once,
+  // one grant of each pair applies and the other answers the first one's result as a duplicate.
+  const tenants = ["tenant-b", "tenant-c", "tenant-d"];
+  const outcomes = await Promise.all(tenants.flatMap((tenant) => [payments.grantCredits(subject(tenant), grant), payments.grantCredits(subject(tenant), grant)]));
+  for (const [index, tenant] of tenants.entries()) {
+    assert.deepEqual(outcomes.slice(index * 2, index * 2 + 2).map((outcome) => outcome.duplicate).sort(), [false, true], tenant);
+    assert.equal((await payments.inspect(subject(tenant))).balance, 5, tenant);
+  }
+  assert.equal(await rowCount(knex, "payment_accounts"), 4);
+  assert.equal(await rowCount(knex, "payment_entries"), 4);
+});
+
+test("the hot path: inspect is one read, and work on an existing account locks it once and writes only a changed state", async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_pay_statements");
+  const store = await createTestPaymentStore(knex);
+  const scope = subject("tenant-a");
+  await store.withAccount(scope, async ({ state, record }) => {
+    state.lots.push({ credits: 1 });
+    await record("grant:first", { credits: 1 });
+  });
+  const statementsOf = async (operation) => {
+    const statements = [];
+    const listener = (query) => statements.push(query.sql);
+    knex.on("query", listener);
+    try {
+      await operation();
+    } finally {
+      knex.off("query", listener);
+    }
+    return statements.map((sql) => sql.split(" ")[0].toLowerCase());
+  };
+
+  assert.deepEqual(await statementsOf(() => store.inspect(scope)), ["select"]);
+  assert.deepEqual(await statementsOf(() => store.withAccount(scope, ({ find }) => find("grant:first"))), ["begin;", "select", "select", "commit;"],
+    "the account's lock and the entry's read; an unchanged state is not written");
+  // A changed state is one UPDATE, which json-rest-api's patch precedes with one read of the row the work holds locked.
+  assert.deepEqual(await statementsOf(() => store.withAccount(scope, async ({ state }) => {
+    state.lots[0].credits = 2;
+  })), ["begin;", "select", "select", "update", "commit;"]);
+  assert.deepEqual((await store.inspect(scope)).lots, [{ credits: 2 }]);
+});
+
+test("work on one account runs one at a time, while other accounts, the catalogue and plain reads go on", { timeout: 20_000 }, async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_serial"));
+  const scope = subject("tenant-a");
+  const other = subject("tenant-b");
+  await store.withAccount(scope, async ({ state }) => {
+    state.count = 0;
+  });
+  await store.withAccount(other, async () => {});
+
+  const entered = [];
+  const firstIn = gate();
+  const release = gate();
+  const first = store.withAccount(scope, async ({ state }) => {
+    entered.push("first");
+    firstIn.open();
+    const seen = state.count;
+    await release.opened;
+    state.count = seen + 1;
+    return seen;
+  });
+  await firstIn.opened;
+  const second = store.withAccount(scope, async ({ state }) => {
+    entered.push("second");
+    const seen = state.count;
+    state.count = seen + 1;
+    return seen;
+  });
+  // While the first work holds tenant-a: another account's work, the merchant's catalogue and plain reads finish.
+  await store.withAccount(other, async ({ state }) => {
+    state.touched = true;
+  });
+  await store.withCatalogue(merchant, async (state) => {
+    state.history.push("touched");
+  });
+  assert.deepEqual(await store.inspect(scope), { lots: [], subscriptions: {}, count: 0 }, "inspect reads what is committed, without waiting");
+  assert.deepEqual(entered, ["first"], "the second work on tenant-a waits for the first");
+  release.open();
+  assert.deepEqual(await Promise.all([first, second]), [0, 1], "the second work saw the first one's state: no update is lost");
+  assert.deepEqual(entered, ["first", "second"]);
+  assert.equal((await store.inspect(scope)).count, 2);
+  assert.equal((await store.inspect(other)).touched, true);
+});
+
+test("a provider customer binds to one subject per merchant: the first binding wins and a different one is refused", { timeout: 20_000 }, async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_customers"));
+
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), null);
+  assert.equal(await store.bindCustomer(merchant, "cus_1", "tenant-a"), undefined);
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), "tenant-a");
+  assert.equal(await store.bindCustomer(merchant, "cus_1", "tenant-a"), undefined, "binding again to the same subject is fine");
+
+  await assert.rejects(store.bindCustomer(merchant, "cus_1", "tenant-b"), (error) => {
+    assert.equal(error.name, "PaymentError");
+    assert.equal(error.code, "payment_customer_conflict");
+    assert.equal(error.statusCode, 409);
+    assert.equal(error.message, "This provider customer is already bound to a different billable subject.");
+    assert.equal(Object.hasOwn(error, "messageCode"), false);
+    return true;
+  });
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), "tenant-a");
+
+  // The customer belongs to the merchant: a subject in the scope is ignored, and another merchant has its own.
+  assert.equal(await store.resolveCustomer(subject("tenant-z"), "cus_1"), "tenant-a");
+  await assert.rejects(store.bindCustomer(subject("tenant-a"), "cus_1", "tenant-b"), { code: "payment_customer_conflict" });
+  for (const changes of [{ providerAccountId: "acct_other" }, { environment: "live" }, { integrationId: "other" }, { applicationId: "other-app" }]) {
+    assert.equal(await store.resolveCustomer({ ...merchant, ...changes }, "cus_1"), null);
+  }
+  await store.bindCustomer({ ...merchant, environment: "live" }, "cus_1", "tenant-b");
+  assert.equal(await store.resolveCustomer({ ...merchant, environment: "live" }, "cus_1"), "tenant-b");
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), "tenant-a");
+
+  // Two subjects binding a new customer at once: exactly one wins, the other is refused.
+  const outcomes = await Promise.allSettled([
+    store.bindCustomer(merchant, "cus_2", "tenant-x"),
+    store.bindCustomer(merchant, "cus_2", "tenant-y")
+  ]);
+  const won = outcomes.findIndex((outcome) => outcome.status === "fulfilled");
+  assert.deepEqual(outcomes.map((outcome) => outcome.status).sort(), ["fulfilled", "rejected"]);
+  assert.equal(outcomes[1 - won].reason.code, "payment_customer_conflict");
+  assert.equal(await store.resolveCustomer(merchant, "cus_2"), ["tenant-x", "tenant-y"][won]);
+});
+
+test("a merchant's catalogue starts empty, keeps what its work leaves, rolls back on failure and is shared by the merchant's subjects", { timeout: 20_000 }, async (context) => {
+  requireTestDatabase(process.env);
+  const store = await createTestPaymentStore(await ownDatabase(context, "da_pay_catalogue"));
+
+  const fresh = await store.inspectCatalogue(merchant);
+  assert.deepEqual(fresh, EMPTY_CATALOGUE);
+  fresh.history.push("changed");
+  assert.deepEqual(await store.inspectCatalogue(merchant), EMPTY_CATALOGUE, "each inspect answers a new copy");
+
+  const result = await store.withCatalogue(merchant, async (...args) => {
+    assert.equal(args.length, 1, "catalogue work gets the state alone");
+    const [state] = args;
+    assert.deepEqual(state, EMPTY_CATALOGUE);
+    state.plans.pro = { productId: "prod_1", priceId: "price_1", publishedAt: new Date(Date.UTC(2026, 2, 3)) };
+    state.history.push({ action: "create-price" });
+    return "published";
+  });
+  assert.equal(result, "published");
+  const saved = { plans: { pro: { productId: "prod_1", priceId: "price_1", publishedAt: "2026-03-03T00:00:00.000Z" } }, history: [{ action: "create-price" }] };
+  assert.deepEqual(await store.inspectCatalogue(merchant), saved);
+  assert.deepEqual(await store.inspectCatalogue(subject("tenant-a")), saved, "a subject in the scope is ignored");
+  assert.deepEqual(await store.inspect(subject("tenant-a")), EMPTY_ACCOUNT, "the catalogue is apart from the accounts");
+  for (const changes of [{ environment: "live" }, { providerAccountId: "acct_other" }, { integrationId: "other" }, { applicationId: "other-app" }]) {
+    assert.deepEqual(await store.inspectCatalogue({ ...merchant, ...changes }), EMPTY_CATALOGUE);
+  }
+
+  const failure = new Error("review expired");
+  await assert.rejects(store.withCatalogue(merchant, async (state) => {
+    state.plans.pro.priceId = "price_2";
+    throw failure;
+  }), (error) => error === failure);
+  assert.deepEqual(await store.inspectCatalogue(merchant), saved, "failed work keeps nothing");
+
+  // Catalogue work runs one at a time per merchant.
+  const firstIn = gate();
+  const release = gate();
+  const first = store.withCatalogue(merchant, async (state) => {
+    firstIn.open();
+    const seen = state.history.length;
+    await release.opened;
+    state.history.push({ action: "first" });
+    return seen;
+  });
+  await firstIn.opened;
+  const second = store.withCatalogue(merchant, async (state) => {
+    state.history.push({ action: "second" });
+    return state.history.length - 1;
+  });
+  assert.deepEqual(await store.withCatalogue({ ...merchant, environment: "live" }, async () => "other merchant"), "other merchant");
+  release.open();
+  assert.deepEqual(await Promise.all([first, second]), [1, 2]);
+  assert.deepEqual((await store.inspectCatalogue(merchant)).history, [{ action: "create-price" }, { action: "first" }, { action: "second" }]);
+});

package/test/paymentStoreFeature.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexLib from "knex";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createTestResourceRuntime } from "@jskit-ai/resource-runtime/test";
+import migration from "../migrations/payments_core_initial.cjs";
+import { PaymentStoreFeature } from "../src/server/storage.js";
+
+const merchant = Object.freeze({ applicationId: "app", integrationId: "billing", providerAccountId: "acct_test", environment: "sandbox" });
+
+test("PaymentStoreFeature owns the payment tables and provides the store on their handles as payments.store", async (t) => {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  t.after(() => knex.destroy());
+  await migration.up(knex);
+  const resources = await createTestResourceRuntime({ knex });
+  let store = null;
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.logger": silentLogger },
+    providers: [
+      EventProvider,
+      ActionProvider,
+      defineProvider({ id: "test.resources", provides: { resources: "runtime.resources" }, setup: () => ({ resources }) }),
+      PaymentStoreFeature,
+      defineProvider({ id: "test.payments", requires: { payments: "payments.store" }, setup({ payments }) { store = payments; } })
+    ]
+  });
+  await runtime.start();
+  t.after(() => runtime.shutdown());
+
+  assert.deepEqual(resources.ownedTables().map(({ tableName, featureId }) => [tableName, featureId]), [
+    ["payment_accounts", "payments.store"],
+    ["payment_entries", "payments.store"],
+    ["payment_customers", "payments.store"],
+    ["payment_catalogues", "payments.store"]
+  ]);
+  const scope = { ...merchant, subjectId: "tenant-a" };
+  assert.equal(await store.withAccount(scope, async ({ state, record }) => {
+    state.lots.push({ credits: 2 });
+    await record("grant:1", { credits: 2 });
+    return "granted";
+  }), "granted");
+  assert.deepEqual(await store.inspect(scope), { lots: [{ credits: 2 }], subscriptions: {} });
+  assert.deepEqual(await store.withAccount(scope, ({ find }) => find("grant:1")), { credits: 2 });
+  await store.bindCustomer(merchant, "cus_1", "tenant-a");
+  assert.equal(await store.resolveCustomer(merchant, "cus_1"), "tenant-a");
+  await store.withCatalogue(merchant, async (state) => {
+    state.revision = 1;
+  });
+  assert.deepEqual(await store.inspectCatalogue(merchant), { plans: {}, history: [], revision: 1 });
+});

package/test/service.test.js

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import knex from "knex";
 import migration from "../migrations/payments_core_initial.cjs";
-import { createKnexPaymentStore } from "../src/server/knexStore.js";
+import { createTestPaymentStore } from "./support/paymentStore.js";
 import { createPaymentService } from "../src/server/service.js";
 import { validatePaymentConfiguration } from "../src/shared/configuration.js";
 
@@ -64,7 +64,7 @@ test("configuration accepts reactive objects and returns an independent plain sn
 test("transactional payment state isolates subjects, grants once, prevents overspend and reconciles current facts", async (t) => {
   const db = knex({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
   await migration.up(db);
-  const store = createKnexPaymentStore({ knex: db });
+  const store = await createTestPaymentStore(db);
   let now = 1000;
   const service = createPaymentService({ store, configuration: validatePaymentConfiguration(document), clock: () => now });
   try {

package/test/standalone.test.js

@@ -6,9 +6,32 @@ import { join } from 'node:path';
 import knex from 'knex';
 import { validatePaymentConfiguration } from '@jskit-ai/payments-core/shared';
 import { createPaymentService } from '@jskit-ai/payments-core/server';
-import { createKnexPaymentStore } from '@jskit-ai/payments-core/server/storage';
+import { PaymentStoreFeature } from '@jskit-ai/payments-core/server/storage';
+import { ActionProvider } from '@jskit-ai/kernel/server/actions';
+import { EventProvider } from '@jskit-ai/kernel/server/runtime';
+import { silentLogger } from '@jskit-ai/kernel/server/runtime/logger';
+import { createCapabilityRuntime, defineProvider } from '@jskit-ai/kernel/shared/capabilities';
+import { ResourceRuntimeProvider } from '@jskit-ai/resource-runtime/server';
 import migration from '../migrations/payments_core_initial.cjs';
 
+/** The payment store as a script or CLI starts it (docs/standalone.md): PaymentStoreFeature in a runtime of its own. */
+async function startPaymentStore(knex) {
+  let store;
+  const runtime = createCapabilityRuntime({
+    inputs: { 'runtime.logger': silentLogger },
+    providers: [
+      EventProvider,
+      ActionProvider,
+      defineProvider({ id: 'cli.database', provides: { database: 'runtime.database' }, setup: () => ({ database: { knex } }) }),
+      ResourceRuntimeProvider,
+      PaymentStoreFeature,
+      defineProvider({ id: 'cli.payments', requires: { payments: 'payments.store' }, setup({ payments }) { store = payments; } })
+    ]
+  });
+  await runtime.start();
+  return { store, stop: () => runtime.shutdown() };
+}
+
 // No editor, project tooling, network or generated application is involved.
 test('a hand-written app reloads payment policy from disk while retaining its own billing state', async () => {
   const directory = await mkdtemp(join(tmpdir(), 'standalone-payments-'));
@@ -23,16 +46,18 @@ test('a hand-written app reloads payment policy from disk while retaining its ow
     } }
   };
   const scope = { applicationId: 'hand-written-app', integrationId: 'billing', providerAccountId: 'acct_fixture', environment: 'sandbox', subjectId: 'workspace-a' };
+  let payments = null;
   const boot = async () => createPaymentService({
-    store: createKnexPaymentStore({ knex: db }),
+    store: payments.store,
     configuration: validatePaymentConfiguration(JSON.parse(await readFile(path, 'utf8'))),
     clock: () => 1000
   });
   try {
     await migration.up(db);
+    payments = await startPaymentStore(db);
     await writeFile(path, JSON.stringify(document));
     const first = await boot();
-    await createKnexPaymentStore({ knex: db }).bindCustomer(scope, 'cus_fixture', scope.subjectId);
+    await payments.store.bindCustomer(scope, 'cus_fixture', scope.subjectId);
     await first.reconcileEvent(scope, {
       eventId: 'evt_fixture', customerId: 'cus_fixture',
       load: async () => ({ subscription: { id: 'sub_fixture', status: 'active', planId: 'pro', periodEnd: 10000 }, renewal: { id: 'invoice_fixture', planId: 'pro', periodEnd: 10000 } })
@@ -55,6 +80,7 @@ test('a hand-written app reloads payment policy from disk while retaining its ow
     await assert.rejects(boot(), { code: 'payment_configuration_invalid' });
     assert.equal((await restarted.inspect(scope)).balance, 93);
   } finally {
+    await payments?.stop();
     await db.destroy();
     await rm(directory, { recursive: true, force: true });
   }

package/test/support/paymentStore.js

@@ -0,0 +1,36 @@
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { ResourceRuntimeProvider } from "@jskit-ai/resource-runtime/server";
+import { PaymentStoreFeature } from "../../src/server/storage.js";
+
+/**
+ * The payment store on a test's own Knex, as an application gets it: PaymentStoreFeature owning the payment tables
+ * through the resource runtime and providing `payments.store`. The runtime holds no timers or connections of its own,
+ * and the Knex stays the test's.
+ * @param {import("knex").Knex} knex
+ * @returns {Promise<import("../../src/server/types.js").PaymentStore>}
+ */
+export async function createTestPaymentStore(knex) {
+  let store = null;
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.logger": silentLogger },
+    providers: [
+      EventProvider,
+      ActionProvider,
+      defineProvider({ id: "test.database", provides: { database: "runtime.database" }, setup: () => ({ database: { knex } }) }),
+      ResourceRuntimeProvider,
+      PaymentStoreFeature,
+      defineProvider({
+        id: "test.payments",
+        requires: { payments: "payments.store" },
+        setup({ payments }) {
+          store = payments;
+        }
+      })
+    ]
+  });
+  await runtime.start();
+  return store;
+}

package/test/withoutDatabase.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { createInstalledRuntime } from "@jskit-ai/kernel/server/platform";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+
+const TABLE_RUNTIME = ["@jskit-ai/database-runtime", "@jskit-ai/resource-runtime"];
+const readManifest = async (url) => JSON.parse(await readFile(url, "utf8"));
+
+/**
+ * An app installed as npm installs it: each package's manifest under node_modules, by name, and nothing else, so no
+ * package of the monorepo is reached by accident.
+ * @param {import("node:test").TestContext} t
+ * @param {object[]} manifests
+ */
+async function installedApp(t, manifests) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "payments-core-without-database-"));
+  t.after(() => rm(appRoot, { recursive: true, force: true }));
+  for (const manifest of manifests) {
+    const packageRoot = path.join(appRoot, "node_modules", ...manifest.name.split("/"));
+    await mkdir(packageRoot, { recursive: true });
+    await writeFile(path.join(packageRoot, "package.json"), JSON.stringify(manifest));
+  }
+  const [own] = manifests;
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
+    name: "app-without-database",
+    private: true,
+    dependencies: { [own.name]: own.version }
+  }));
+  return appRoot;
+}
+
+test("an app without a database installs @jskit-ai/payments-core without the table runtime, composes it and starts", async (t) => {
+  const manifest = await readManifest(new URL("../package.json", import.meta.url));
+  // npm installs a package's dependencies, never its optional peers: the table runtime comes with an app's database.
+  for (const name of TABLE_RUNTIME) {
+    assert.equal(manifest.dependencies?.[name], undefined, `${name} is not a dependency`);
+    assert.equal(manifest.peerDependenciesMeta?.[name]?.optional, true, `${name} is an optional peer`);
+  }
+
+  const started = await createInstalledRuntime({ appRoot: await installedApp(t, [manifest]), logger: silentLogger });
+  assert.ok(started.packageOrder.includes(manifest.name));
+  assert.equal(started.packageOrder.some((name) => TABLE_RUNTIME.includes(name)), false);
+
+  // Installed as a dependency, the table runtime would need a database driver the app does not have.
+  const databaseRuntime = await readManifest(new URL("../../database-runtime/package.json", import.meta.url));
+  await assert.rejects(
+    createInstalledRuntime({ appRoot: await installedApp(t, [manifest, databaseRuntime]), logger: silentLogger }),
+    /requires capability runtime\.database\.driver, but no installed package provides it/u
+  );
+});

package/src/server/knexStore.js

@@ -1,92 +0,0 @@
-import { PaymentError, fingerprint } from "./errors.js";
-
-const empty = () => ({ lots: [], subscriptions: {} });
-
-function merchant(scope) {
-  const fields = ["applicationId", "integrationId", "providerAccountId", "environment"];
-  for (const field of fields) {
-    if (typeof scope?.[field] !== "string" || !scope[field] || scope[field].length > 200) throw new TypeError(`Payment scope requires ${field}.`);
-  }
-  if (!["sandbox", "live"].includes(scope.environment)) throw new TypeError("Payment scope requires sandbox or live.");
-  return fields.map((field) => scope[field]);
-}
-function identifier(value) {
-  if (typeof value !== "string" || !value || value.length > 200) throw new TypeError("Payment identity is required (maximum 200 characters).");
-  return value;
-}
-const accountKey = (scope) => fingerprint([...merchant(scope), identifier(scope.subjectId)]);
-
-/** @param {{ knex: import("@jskit-ai/database-runtime/server/types").RuntimeKnex }} dependencies */
-function createKnexPaymentStore({ knex }) {
-  // readable-check: allow method-probe - input validation: the application passes its own Knex instance
-  if (typeof knex !== "function" || typeof knex.transaction !== "function") {
-    throw new TypeError("createKnexPaymentStore requires the application's Knex instance.");
-  }
-
-  async function inspect(scope) {
-    const row = await knex("payment_accounts").where({ account_key: accountKey(scope) }).first();
-    return row ? JSON.parse(row.payload) : empty();
-  }
-  async function withAccount(scope, work) {
-    const key = accountKey(scope);
-    return knex.transaction(async (trx) => {
-      // The retained account row serializes grants, usage, refunds and event handling.
-      await trx("payment_accounts").insert({ account_key: key, payload: JSON.stringify(empty()) })
-        .onConflict("account_key").merge({ account_key: key });
-      const row = await trx("payment_accounts").where({ account_key: key }).forUpdate().first();
-      const state = JSON.parse(row.payload);
-      const result = await work({
-        state,
-        async find(reference) {
-          const entry = await trx("payment_entries").where({ entry_key: fingerprint([key, identifier(reference)]) }).first();
-          return entry ? JSON.parse(entry.payload) : null;
-        },
-        async record(reference, payload) {
-          await trx("payment_entries").insert({ entry_key: fingerprint([key, identifier(reference)]), account_key: key, payload: JSON.stringify(payload) });
-        }
-      });
-      await trx("payment_accounts").where({ account_key: key }).update({ payload: JSON.stringify(state) });
-      return result;
-    });
-  }
-  async function bindCustomer(scope, customerId, subjectId) {
-    const key = fingerprint([...merchant(scope), identifier(customerId)]);
-    identifier(subjectId);
-    await knex.transaction(async (trx) => {
-      await trx("payment_customers").insert({ customer_key: key, subject_id: subjectId })
-        .onConflict("customer_key").merge({ customer_key: key });
-      const row = await trx("payment_customers").where({ customer_key: key }).first();
-      if (row.subject_id !== subjectId) throw new PaymentError("payment_customer_conflict", "This provider customer is already bound to a different billable subject.", 409);
-    });
-  }
-  async function resolveCustomer(scope, customerId) {
-    const row = await knex("payment_customers").where({ customer_key: fingerprint([...merchant(scope), identifier(customerId)]) }).first();
-    return row?.subject_id ?? null;
-  }
-  async function inspectCatalogue(scope) {
-    const row = await knex("payment_catalogues").where({ catalogue_key: fingerprint(merchant(scope)) }).first();
-    return row ? JSON.parse(row.payload) : { plans: {}, history: [] };
-  }
-  async function withCatalogue(scope, work) {
-    const key = fingerprint(merchant(scope));
-    return knex.transaction(async (trx) => {
-      await trx("payment_catalogues").insert({ catalogue_key: key, payload: JSON.stringify({ plans: {}, history: [] }) })
-        .onConflict("catalogue_key").merge({ catalogue_key: key });
-      const row = await trx("payment_catalogues").where({ catalogue_key: key }).forUpdate().first();
-      const state = JSON.parse(row.payload);
-      const result = await work(state);
-      await trx("payment_catalogues").where({ catalogue_key: key }).update({ payload: JSON.stringify(state) });
-      return result;
-    });
-  }
-  return Object.freeze({
-    inspect,
-    withAccount,
-    bindCustomer,
-    resolveCustomer,
-    inspectCatalogue,
-    withCatalogue
-  });
-}
-
-export { createKnexPaymentStore };