@flowdular/sdk 0.3.0 → 0.3.2

package/.ai/platform-capabilities.md

@@ -24,6 +24,8 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Feature flags.** A flag is a module setting declared `kind: 'flag'`: a non-secret `boolean` with a `defaultValue`, a `label`, a `description` and `scope: 'tenant'`, which is the default and the only scope a flag may take; `defineModuleSettings` refuses anything else, a platform-scoped flag included. There is no flag store, no flag endpoint and no flag registry. A module reads one on the request path with the ordinary settings read, `context.settings.get<boolean>(tenantId, moduleId, key)`: a lookup of the declaration, a lookup of the cached per `(tenant, module)` value set under a key the read builds, the touch that keeps that entry at the head of the cache, the property read and one `typeof` check. No query of its own, and nothing beyond what any setting already costs: a declared `pattern` is compiled once with the declaration, never per read. There is deliberately no `context.flags`; the read is the settings read, and the module id is the one the module already knows. An override is per workspace behind `system.settings.manage` on the Flags tab of Administration, Modules, which groups every declared flag by its owning module and links the audit trail. Every change appends one `settings.flag.changed` auth audit event with the module, the key, the previous and next values and the actor (`settings.updated` stays the event for every other setting). No percentage rollout and no targeting: a flag is on or off for a workspace.
 
+**Module activation.** The composed module set is CLI-owned and baked at build; what an owner changes from Administration, Modules is per-workspace activation of the modules the application already composes. `system.core` keeps it in `system_module_activations` (a composed module without a row is active), lists it through `GET /api/system/modules` (every catalog row with `active`, `optional` and `dependents`) and `GET /api/system/modules/active` (the active composed ids, for any member holding `system.workspace.access`), and changes it through `POST /api/system/modules/activate` and `/api/system/modules/deactivate` behind `system.settings.manage` with CSRF first. `system.core`, `auth.core`, `users.core` and `profile.core` (`REQUIRED_MODULE_IDS` in `@flowdular/contracts`) are never deactivated; a module another active module depends on, through a declared module dependency or a required capability, is refused with 409 `MODULE_HAS_ACTIVE_DEPENDENTS` naming the dependents, a required one with 409 `MODULE_REQUIRED`, and activating a module whose dependency is inactive with 409 `MODULE_DEPENDENCY_INACTIVE`. Every change appends one `system.module.activated` or `system.module.deactivated` auth audit event. The state is one per-tenant snapshot memoised for 30 seconds and published as the public capability `system.modules.v1` (`isActive(tenantId, moduleId)`, `activeIds(tenantId)`, `modules/system/src/server/capability.ts`). Enforcement costs a module nothing: the generated composition binds every route to its module id (`bindModuleCompositions`, `packages/server/src/module-activation.ts`), `defineEndpoint` answers 403 `MODULE_INACTIVE` after the permission check for an endpoint of an inactive module in the principal's workspace (`EndpointIdentity.tenantId` comes from `endpointIdentityFromContext`), and the application shell reads the active ids before it renders and hides the navigation, views, widgets and command search of an inactive module (`contributionsForActiveModules`, `packages/client/src/shell/modules.ts`; a failed read shows everything). Not covered yet: the agent tools of an inactive module are still offered, because the harness registry has no per-tenant module hook.
+
 **Navigation groups.** A navigation contribution picks exactly one group (`NavigationGroup`, `packages/client/src/contributions.ts`):
 
 <!-- capabilities:navigation-groups -->
@@ -50,7 +52,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Automations triggers.** Two mechanisms in `automations.core`. A schedule uses a cadence string in one of two forms (`modules/automations/src/domain/cadence.ts`): `every:N`, where `N` is whole minutes from 1 to 10080 and the unit is implicit, or `cron:<minute> <hour> <day of month> <month> <day of week>`, five fields with no seconds, at most 100 characters, each field `*`, a number, a three letter month or weekday name, a list, a range, or any of those with a step (`*/15`, `9-17/4`); both day fields restricted means either matches. A cron slot is a wall clock time in the workspace zone from the shared `system.core.timeZone` setting, stored in UTC; a wall time a daylight saving change removes is skipped and one that occurs twice fires at the first of the two. An expression the module cannot honour is refused at save with `INVALID_CADENCE`. Missed slots are skipped, never replayed. An inbound webhook posts to `POST /api/automations/triggers/:id/fire`, authenticated by an HMAC signature in `x-flowdular-signature` with `x-flowdular-timestamp` inside a 5 minute window and a 16 KB body cap, answering `202 { accepted, runId }`. Targets are pluggable through `automations.targets.v1`; the shipped kinds are `agent` and `workflow`.
 
-**CLI extensions.** A module contributes `pnpm flowdular <namespace> <action>` through `src/cli/commands.json` plus `defineCliExtension` (`packages/cli-protocol/src/index.ts`), declared in `module.json` under `cli`. The first path segment must equal the module id's first segment and may not be a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `migration`, `setup`). Each command carries a `CapabilityDescriptor` with `id`, `version`, `summary`, `risk: 'read' | 'workspace-write' | 'process' | 'external' | 'destructive'`, `requiresApprovedSpec`, `supportsDryRun`, optional `localOnly` and `confirmation`. The runner refuses `external` always and non-local `destructive` always, gates `localOnly` to `development` and `test`, and treats every write command as a dry run without `--apply`.
+**CLI extensions.** A module contributes `pnpm flowdular <namespace> <action>` through `src/cli/commands.json` plus `defineCliExtension` (`packages/cli-protocol/src/index.ts`), declared in `module.json` under `cli`. The first path segment must equal the module id's first segment and may not be a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `migration`, `setup`). Each command carries a `CapabilityDescriptor` with `id`, `version`, `summary`, `risk: 'read' | 'workspace-write' | 'process' | 'external' | 'destructive'`, `requiresApprovedSpec`, `supportsDryRun`, optional `localOnly` and `confirmation`. The runner refuses `external` and non-local `destructive` commands unless `--grant <token> --tenant <id>` carries a verified approval grant for the capability and the invocation digest, gates `localOnly` to `development` and `test`, and treats every write command as a dry run without `--apply`.
 
 **Translations.** The shipped locales are `en` and `pl`. A module keeps a flat bundle per locale in `translations/<locale>.json`, imports them in `src/client/contribution.tsrx` and returns `translations: { en, pl }`. Keys resolve fully qualified as `<first module segment>.<key>` through `t()`. `flowdular module validate` reports `TRANSLATION_FILE_MISSING`, `TRANSLATION_PARSE_ERROR`, `TRANSLATION_KEYS_MISMATCH` and `TRANSLATION_KEY_MISSING`.
 
@@ -66,7 +68,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Connectors.** `connectors.core` (optional) is the governed way out to an external system. A module ships a connector definition through the public capability `connectors.definitions.v1` (`modules/connectors/src/domain/definitions.ts`): `register({ key, moduleId, label, authKinds, operations: [{ key, label, method, path, inputSchema, outputSchema }], defaultAllowedHosts, allowedPorts? })` (ports default to 443 only), and the platform ships `http-json`. An owner creates an instance behind `connectors.instances.manage` with a base URL, sealed credentials under `FD_CONNECTORS_SECRET_KEY`, a host allowlist and two consent flags, `allowWorkflows` and `allowAgents`, both off. A call goes through `connectors.calls.v1`: `call({ tenantId, instanceId, operation, input, caller: 'test' | 'workflow' | 'agent', callerRef? })`, which enforces status, consent for that caller kind, the egress policy (https, no private addresses, no redirects, timeout and size caps) and logs the call without any body; `consented(tenantId, instanceId, caller)` answers admission alone. The agent tool `connectors.call` is declared `workspace-write` with the harness consent gate `connectors.instance-consent` (`AgentToolConsent` in `packages/harness/src/runtime.ts`), carries the full action contract (`idempotency: 'required'` backed by a per-call key ledger) so workflows may use it, has no HTTP route of its own, and dials only the addresses the egress policy verified, so the ceiling is raised per instance by the owner's consent, never by a declaration.
 
-**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back.
+**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back. A request whose `subjectRef` is `encodeCapabilitySubjectRef({ capabilityId, inputDigest })` yields, once approved, a signed token through `grant(tenantId, id, subjectModule)`, handed only to the module that opened it; the CLI runner takes it as `--grant` (valid until expiry) and the harness as `AgentExecutionRequest.grants` (one tool call per grant), both bound to the tenant, the capability id and `approvalInputDigest` of the input.
 
 **Documents.** `documents.core` (optional) owns file attachments of any record. A screen uploads through `POST /api/documents/upload` with the raw body and the headers `x-document-filename`, `x-document-owner-module`, `x-document-record-ref` and `x-document-description`, lists with `GET /api/documents?ownerModule=&recordRef=`, opens through `POST /api/documents/read-url` (a short-lived storage URL) and deletes through `POST /api/documents/delete`, all behind `documents.files.read` or `documents.files.manage` with CSRF first. A module reads its own records' attachments through the public capability `documents.attachments.v1` (`modules/documents/src/domain/attachments.ts`): `list(tenantId, ownerModule, recordRef)`, `open(tenantId, ownerModule, recordRef, id)` answering `{ contentType, bytes, filename, body }` or null for anything not readable (unknown, another pair, deleted, infected) and `delete(tenantId, ownerModule, recordRef, id)`; the reference pair is a scope, the caller's permission on its own record is the authorization, and the storage key never leaves documents.core. Checksums, scan verdicts and the object limits come from the storage port.
 

package/.ai/policies/capabilities.yaml

@@ -84,6 +84,12 @@ core:
     confirmation: restore-database
     supportsDryRun: true
     effect: 'replaces the configured database with the backup in <dir> (pg_restore --clean --if-exists, or a staged replacement of the embedded data directory); refuses BACKUP_ADAPTER_MISMATCH across adapters and warns BACKUP_KEY_MISMATCH when the running environment holds keys the backup was not taken with'
+  database.restore.production:
+    command: pnpm flowdular database restore-production --input <dir> --target <database> --grant <token> --tenant <id> [--allow-key-mismatch] [--platform-url <origin>|--platform-stopped] --apply --confirm restore-database
+    risk: destructive
+    confirmation: restore-database
+    supportsDryRun: true
+    effect: 'the same restore without localOnly, so it runs in any environment but only under a verified approval grant (see approvals.destructive-not-local; the grant binds --input, --target and every other capability flag); --target must repeat the database of the migrator DSN (the embedded data directory for pglite) or RESTORE_TARGET_MISMATCH; MIGRATOR_ROLE_REQUIRED when FD_DATABASE_MIGRATOR_URL is absent or equals FD_DATABASE_URL; a key divergence is a BACKUP_KEY_MISMATCH refusal unless --allow-key-mismatch is part of the approved invocation; with --apply, PLATFORM_RUNNING while <origin>/api/health (from --platform-url, else http://127.0.0.1:$FD_PORT) answers, and PLATFORM_STATE_UNKNOWN when no endpoint is named or the probe times out unless --platform-stopped attests the platform is down'
   workspace.state.migrate:
     command: pnpm flowdular setup migrate-state [--apply --confirm migrate-legacy-state]
     risk: destructive
@@ -146,6 +152,24 @@ modules:
       risk: process
       supportsDryRun: true
       note: re-seals stored trigger secrets with the current encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, and never prints a secret
+  documents.core:
+    documents.storage.rotate:
+      command: pnpm flowdular documents secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored document objects in place with the current storage encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves an object under an unknown key or one that fails authentication as it is, and never prints object content
+  exports.core:
+    exports.storage.rotate:
+      command: pnpm flowdular exports secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored export files in place with the current storage encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves a file under an unknown key or one that fails authentication as it is, and never prints file content
+  connectors.core:
+    connectors.secrets.rotate:
+      command: pnpm flowdular connectors secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored connector credentials with the current encryption key and recomputes their fingerprints under it; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves a row under an unknown key as it is, and never prints a credential
   notifications.core:
     notifications.secrets.rotate:
       command: pnpm flowdular notifications secrets-rotate [--apply]
@@ -240,14 +264,18 @@ modules:
 
 # packages/cli/src/runner.ts, runExtensionCommand, in evaluation order.
 approvals:
-  external: refused with APPROVAL_VERIFIER_REQUIRED (no signed approval verifier exists)
-  destructive-not-local: refused with APPROVAL_VERIFIER_REQUIRED
+  external: the same grant check as destructive-not-local; APPROVAL_VERIFIER_REQUIRED without a token or key
+  destructive-not-local: needs --grant <token> --tenant <id>, an approval grant verified under FD_APPROVAL_GRANT_KEY against the tenant, the capability id and the invocation digest (positional arguments plus every flag except --root, --json, --confirm, --grant and --tenant, so --apply is bound and an approval names the applied run, never a dry run); APPROVAL_VERIFIER_REQUIRED without a token or key, APPROVAL_GRANT_INVALID, APPROVAL_GRANT_EXPIRED or APPROVAL_GRANT_MISMATCH otherwise; the runner records no use, so a grant replays until it expires
   localOnly: refused with LOCAL_ONLY_CAPABILITY unless FD_ENV or NODE_ENV is development or test (unset counts as development)
   requiresApprovedSpec: needs --spec <path>; APPROVED_SPEC_REQUIRED, SPEC_VALIDATION_FAILED or SPEC_NOT_APPROVED otherwise
   destructive-apply: --apply needs --confirm <descriptor.confirmation>; CONFIRMATION_REQUIRED otherwise
   non-read-without-dry-run: EXPLICIT_APPLY_REQUIRED without --apply
   dry-run: non-read with supportsDryRun and no --apply runs with apply=false and warns "Dry run only. No writes were authorized."
 
+harnessGate:
+  localOnlyTools: CLI tools whose capability is localOnly are refused by the harness with TOOL_LOCAL_ONLY outside development and test, grant or not
+  grantedTools: external tools and non-local destructive CLI tools are offered only when the run carries a grant verified for the tool id and the input digest; one tool call per grant (APPROVAL_GRANT_CONSUMED afterwards); the consent gate still applies
+
 moduleExtensions:
   discovery: module.json cli.catalog (src/cli/commands.json), schema-validated without executing code
   loadImplementation: module.json cli.entry imported only when the command runs (packages/cli/src/extensions.ts loadCliCommand)
@@ -259,6 +287,5 @@ moduleExtensions:
 planned:
   - migration.plan (served by "migration apply" without --apply, which is a read-only dry run)
   - migration.apply.remote
-  - destructive.execute (signed approval receipts)
   - redaction of *_TOKEN, *_SECRET, *_PASSWORD, DATABASE_URL in a shared logger (only packages/ai-provider/src/errors.ts redactSecrets exists)
   - persisted CLI audit (CommandEnvelope carries a random auditId and evidence per invocation; nothing stores it)

package/.ai/references/catalog/migrations/0005_catalog_list_indexes.down.sql

@@ -0,0 +1,3 @@
+DROP INDEX IF EXISTS catalog_items_tenant_updated_idx;
+DROP INDEX IF EXISTS catalog_items_tenant_name_idx;
+ALTER TABLE catalog_items DROP COLUMN IF EXISTS updated_at;

package/.ai/references/catalog/migrations/0005_catalog_list_indexes.up.sql

@@ -0,0 +1,11 @@
+ALTER TABLE catalog_items ADD COLUMN IF NOT EXISTS updated_at BIGINT NOT NULL DEFAULT 0;
+-- The backfill runs as the migrator, which forced row security keeps out of
+-- every row without a tenant setting; lift the flag for the statement only.
+ALTER TABLE catalog_items NO FORCE ROW LEVEL SECURITY;
+UPDATE catalog_items SET updated_at = created_at WHERE updated_at = 0;
+ALTER TABLE catalog_items FORCE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items ALTER COLUMN updated_at DROP DEFAULT;
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_name_idx
+  ON catalog_items (tenant_id, lower(name), id);
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_updated_idx
+  ON catalog_items (tenant_id, updated_at, id);

package/.ai/references/catalog/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "catalog.core",
 	"package": "@flowdular/module-catalog",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],
 	"platform": {
@@ -18,6 +18,16 @@
 		{
 			"id": "auth.core",
 			"range": "^0.13.0"
+		},
+		{
+			"id": "exports.core",
+			"range": "^0.2.0"
+		}
+	],
+	"requires": [
+		{
+			"id": "exports.lists.v1",
+			"optional": true
 		}
 	],
 	"tenancy": "required",

package/.ai/references/catalog/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-catalog",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.2.4"
+		"@flowdular/sdk": "0.3.1"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/.ai/references/catalog/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 1
 id: catalog.core
-specVersion: 0.7.0
+specVersion: 0.8.0
 status: approved
 name: Product Catalog Core
 description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.
@@ -15,6 +15,11 @@ dependencies:
     range: ^0.7.0
   - id: auth.core
     range: ^0.13.0
+  - id: exports.core
+    range: ^0.2.0
+requires:
+  - id: exports.lists.v1
+    optional: true
 tenancy: required
 locales:
   - en
@@ -30,6 +35,10 @@ invariants:
   - One tenant-scoped durable target ledger is shared by mutating agent tools and workflow actions; each entry binds an idempotency key to the exact tool identifier or versioned workflow action identifier, canonical input digest, and first persisted result in the same transaction as the catalog mutation.
   - Replaying the same idempotency key for the same operation and canonical input returns the original result without another catalog item or history row, while reuse for another operation or input fails with a stable conflict.
   - Idempotency ledger entries remain after a catalog item is deleted, and audit metadata records identifiers, input digests, and outcomes without raw tool input, credentials, secrets, or result payloads.
+  - The items list is answered one page at a time on the shared signed cursor, at most 200 rows per read and 50 by default, ordered by lower-cased name, by normalized SKU or by the last update time, each order ending in the item id, narrowed in SQL by kind, by status and by a substring of the name or the SKU, and read as one index range over the matching (tenant_id, sort expression, id) index. A cursor is bound to the workspace, the sort, the direction and a digest of the filters, and a cursor of another listing or another workspace is refused with CURSOR_INVALID. No unbounded read of a workspace's items exists; the agent list tool and the dashboard widget read one bounded page.
+  - Every item carries the time of its last accepted mutation, set when it is created, edited, archived or restored, so the list can be ordered by recency.
+  - The items list export registered with exports.lists.v1 as catalog.core.items declares the SKU, name, kind, unit, base price in minor units, currency and status columns, is behind catalog.items.read, and is walked by exports.core under the principal that started the job through the same paged read the list endpoint answers, in SKU order. A deployment without exports.core still composes catalog.core and registers nothing.
+  - The bulk archive and bulk restore routes are siblings of the single-row lifecycle routes under the same permission and CSRF rule. Each names 1 to 100 unique item ids and executes the single-row path per id, so every accepted transition keeps its own history row and the idempotency ledger is untouched; an id that is missing or of another workspace answers not-found and a refused id answers refused with its stable code, and neither fails the other ids.
   - catalog.core declares three data classes to the platform registry while it composes and performs their export itself on its own lease under its own tenant transaction. catalog.core.items and catalog.core.history are master data, and each export walks every row of one workspace by keyset in bounded pages, and neither class carries a retention period, a sweep, or an erasure, so a row leaves only when a person deletes it. catalog.core.idempotency-ledger is operational, is never swept, and is excluded from the export with a stated reason because the item it points at is already exported.
 permissions:
   - id: catalog.items.read
@@ -37,15 +46,27 @@ permissions:
   - id: catalog.items.manage
     description: Create and update products and services in the active tenant.
 dataOwnership:
-  - catalog.core owns SKU, item identity, kind, unit, base price, currency, and lifecycle status.
+  - catalog.core owns SKU, item identity, kind, unit, base price, currency, lifecycle status, and the last update time.
   - catalog.core owns the idempotency ledger for its mutating agent tools and workflow actions; callers supply the key but do not maintain a second target ledger.
   - catalog.core declares the data classes catalog.core.items (catalog_items), catalog.core.history (catalog_items_history_v2, which holds every row of the superseded catalog_items_history) and catalog.core.idempotency-ledger (catalog_idempotency_ledger); items and history are exported per workspace, the ledger is excluded with a stated reason.
   - Sales and purchasing modules reference catalog item identifiers and snapshot commercial terms when required by their specs.
 acceptanceScenarios:
   - id: CATALOG-LIST
     given: Tenant-scoped products and services exist.
-    when: An authorized principal lists catalog items.
-    then: Only items owned by the active tenant are returned in deterministic SKU order.
+    when: An authorized principal lists catalog items with a sort, a direction, filters and a page size.
+    then: Only items owned by the active tenant are returned, in the requested order ending in the item id, narrowed by kind, status and search in SQL, one page at a time with a cursor only on a full page, and two consecutive pages neither overlap nor leave a gap.
+  - id: CATALOG-LIST-CURSOR
+    given: A page cursor was issued for one listing of one workspace.
+    when: It is presented tampered, by another workspace, with other filters or with another sort, or an unknown sort is requested.
+    then: The server answers 400 with CURSOR_INVALID for the cursor and INVALID_INPUT for the sort, before any repository read.
+  - id: CATALOG-LIST-EXPORT
+    given: exports.core composed and registered its list capability.
+    when: catalog.core composes and a principal with catalog.items.read starts an export of catalog.core.items.
+    then: The catalogue lists the export with its declared columns and the job streams every item of the principal's workspace in SKU order, page by page, and no item of another workspace.
+  - id: CATALOG-BULK-LIFECYCLE
+    given: A principal with catalog.items.manage selects several items on the list.
+    when: The principal archives or restores the selection, naming a missing id and an id of another workspace beside existing ones.
+    then: Each existing item transitions with its own history row, the missing and foreign ids answer not-found, the call answers one outcome per id, the screen tells the counts, and a body without ids, with more than 100 ids, with a repeated id or without a valid CSRF token is refused.
   - id: CATALOG-CREATE
     given: An authorized principal supplies a unique SKU and valid product or service data.
     when: The catalog item is created.

package/.ai/references/catalog/src/agent/tools.ts

@@ -8,7 +8,10 @@ import { agentActor, type Actor } from '@flowdular/sdk/kernel';
 import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
 import type { CatalogItemKind } from '../domain/types.ts';
 import type { CatalogRuntime } from '../server/runtime.ts';
-import { CatalogServiceError } from '../services/catalog-service.ts';
+import {
+	CatalogServiceError,
+	FIRST_LIST_PAGE,
+} from '../services/catalog-service.ts';
 
 const MAX_TOOL_ROWS = 200;
 const CREATE_OPERATION = 'catalog.item.create@1';
@@ -39,6 +42,7 @@ const CATALOG_ITEM_OUTPUT_SCHEMA = {
 		currency: { type: 'string' },
 		status: { type: 'string', enum: ['active', 'archived'] },
 		createdAt: { type: 'integer' },
+		updatedAt: { type: 'integer' },
 	},
 } as const;
 
@@ -91,15 +95,20 @@ export function catalogAgentTools(
 				const query = normalized(
 					(input as Record<string, unknown> | null)?.query,
 				);
-				return (await (await runtime.service()).list(context.tenantId))
-					.filter(
-						(item) =>
-							query === '' ||
-							item.id.toLocaleLowerCase('en-US') === query ||
-							item.sku.toLocaleLowerCase('en-US').includes(query) ||
-							item.name.toLocaleLowerCase('en-US').includes(query),
-					)
-					.slice(0, MAX_TOOL_ROWS);
+				const service = await runtime.service();
+				/* An exact id answers one row before any search, so the variable
+				   resolver that binds an item id never reads a page. */
+				const exact =
+					query === '' ? null : await service.get(context.tenantId, query);
+				if (exact) return [exact];
+				return (
+					await service.listPage(context.tenantId, {
+						...FIRST_LIST_PAGE,
+						sort: 'sku',
+						search: query,
+						limit: MAX_TOOL_ROWS,
+					})
+				).items;
 			},
 		}),
 		defineApiAgentTool({

package/.ai/references/catalog/src/api/endpoints.ts

@@ -1,9 +1,12 @@
+import { randomBytes } from 'node:crypto';
 import {
 	defineEndpoint,
 	HttpProblem,
 	jsonResponse,
+	pageResponse,
 	problemResponse,
 	readJsonObject,
+	readPageQuery,
 	requiredInteger,
 	requiredString,
 } from '@flowdular/sdk/server';
@@ -16,13 +19,26 @@ import {
 	sessionMutationDenial,
 } from '@flowdular/sdk/modules/auth/server';
 import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
-import type {
-	CatalogItemKind,
-	CreateCatalogItemInput,
-	UpdateCatalogItemInput,
+import {
+	CATALOG_BULK_LIMIT,
+	CATALOG_LIST_SORTS,
+	CATALOG_SEARCH_LENGTH,
+	type CatalogItemKind,
+	type CatalogListSort,
+	type CreateCatalogItemInput,
+	type UpdateCatalogItemInput,
 } from '../domain/types.ts';
-import { CatalogServiceError } from '../services/catalog-service.ts';
+import {
+	CatalogServiceError,
+	LIST_PAGE_LIMIT,
+	LIST_PAGE_MAX_LIMIT,
+} from '../services/catalog-service.ts';
 import type { CatalogRuntime } from '../server/runtime.ts';
+import {
+	decodeListCursor,
+	encodeListCursor,
+	type CatalogListQuery,
+} from './list-cursor.ts';
 
 function failure(error: unknown): Response {
 	if (error instanceof CatalogServiceError) {
@@ -34,6 +50,59 @@ function failure(error: unknown): Response {
 	return problemResponse(error, 'The catalog operation failed.');
 }
 
+function invalid(message: string): HttpProblem {
+	return new HttpProblem('INVALID_INPUT', message, 400);
+}
+
+function listQuery(url: URL): CatalogListQuery {
+	const sort = url.searchParams.get('sort') ?? 'name';
+	if (!(CATALOG_LIST_SORTS as readonly string[]).includes(sort)) {
+		throw invalid(`sort must be one of ${CATALOG_LIST_SORTS.join(', ')}.`);
+	}
+	const direction = url.searchParams.get('direction') ?? 'asc';
+	if (direction !== 'asc' && direction !== 'desc') {
+		throw invalid('direction must be asc or desc.');
+	}
+	const kind = url.searchParams.get('kind') ?? '';
+	if (kind !== '' && kind !== 'product' && kind !== 'service') {
+		throw invalid('kind must be product or service.');
+	}
+	const status = url.searchParams.get('status') ?? '';
+	if (status !== '' && status !== 'active' && status !== 'archived') {
+		throw invalid('status must be active or archived.');
+	}
+	const search = (url.searchParams.get('q') ?? '').trim();
+	if (search.length > CATALOG_SEARCH_LENGTH) {
+		throw invalid(
+			`q must contain at most ${CATALOG_SEARCH_LENGTH} characters.`,
+		);
+	}
+	return {
+		sort: sort as CatalogListSort,
+		direction,
+		kind: kind === '' ? null : kind,
+		status: status === '' ? null : status,
+		search,
+	};
+}
+
+/* One outcome answers one row, so an id is named once; the count and each id
+   are bounded like the single route's. */
+function requiredIds(value: Record<string, unknown>): readonly string[] {
+	const raw = value.ids;
+	if (!Array.isArray(raw)) throw invalid('ids must be an array.');
+	if (raw.length < 1 || raw.length > CATALOG_BULK_LIMIT) {
+		throw invalid(`ids must name between 1 and ${CATALOG_BULK_LIMIT} items.`);
+	}
+	const ids = raw.map((entry) =>
+		requiredString({ id: entry }, 'id', { max: 128 }),
+	);
+	if (new Set(ids).size !== ids.length) {
+		throw invalid('ids must not repeat an id.');
+	}
+	return ids;
+}
+
 function mutableInput(
 	value: Record<string, unknown>,
 ): Omit<UpdateCatalogItemInput, 'id'> {
@@ -58,18 +127,45 @@ export function createCatalogRoutes(
 	auth: AuthRuntime,
 	runtime: CatalogRuntime,
 ) {
+	/* Module-owned and never stored: a cursor names a position in one
+	   workspace's own list, so a restart invalidating one costs a client the
+	   first page. */
+	const cursorSecret = randomBytes(32);
 	const list = defineEndpoint({
 		id: 'catalog.items.list',
 		path: '/api/catalog/items',
 		methods: ['GET'],
 		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.read },
 		resolveIdentity: endpointIdentityFromContext,
-		handler: async ({ octane }) =>
-			jsonResponse({
-				items: await (
+		handler: async ({ octane }) => {
+			try {
+				const tenantId = principalFromContext(octane)!.tenantId;
+				const url = new URL(octane.request.url);
+				const page = readPageQuery(url, {
+					maxLimit: LIST_PAGE_MAX_LIMIT,
+					defaultLimit: LIST_PAGE_LIMIT,
+				});
+				const query = listQuery(url);
+				const result = await (
 					await runtime.service()
-				).list(principalFromContext(octane)!.tenantId),
-			}),
+				).listPage(tenantId, {
+					...query,
+					limit: page.limit,
+					after: page.cursor
+						? decodeListCursor(cursorSecret, page.cursor, tenantId, query)
+						: null,
+				});
+				return pageResponse({
+					items: result.items,
+					limit: page.limit,
+					nextCursor: result.next
+						? encodeListCursor(cursorSecret, tenantId, query, result.next)
+						: null,
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
 	});
 	const create = defineEndpoint({
 		id: 'catalog.items.create',
@@ -164,6 +260,46 @@ export function createCatalogRoutes(
 		'/api/catalog/items/restore',
 		'catalog.items.restore',
 	);
+	/* The bulk sibling of a lifecycle route: same permission and CSRF rule,
+	   one outcome per id through the same service path. */
+	const lifecycleMany = (
+		action: 'archiveMany' | 'restoreMany',
+		path: string,
+		id: string,
+	) =>
+		defineEndpoint({
+			id,
+			path,
+			methods: ['POST'],
+			access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+			resolveIdentity: endpointIdentityFromContext,
+			handler: async ({ octane }) => {
+				const denial = sessionMutationDenial(octane, auth);
+				if (denial) return denial;
+				try {
+					const value = await readJsonObject(octane.request);
+					const service = await runtime.service();
+					const outcomes = await service[action](
+						principalFromContext(octane)!.tenantId,
+						requiredIds(value),
+						actorFromContext(octane)!,
+					);
+					return jsonResponse({ outcomes });
+				} catch (error) {
+					return failure(error);
+				}
+			},
+		});
+	const archiveMany = lifecycleMany(
+		'archiveMany',
+		'/api/catalog/items/archive-many',
+		'catalog.items.archive-many',
+	);
+	const restoreMany = lifecycleMany(
+		'restoreMany',
+		'/api/catalog/items/restore-many',
+		'catalog.items.restore-many',
+	);
 	const remove = defineEndpoint({
 		id: 'catalog.items.delete',
 		path: '/api/catalog/items/delete',
@@ -227,6 +363,8 @@ export function createCatalogRoutes(
 		update.serverRoute,
 		archive.serverRoute,
 		restore.serverRoute,
+		archiveMany.serverRoute,
+		restoreMany.serverRoute,
 		remove.serverRoute,
 		history.serverRoute,
 	] as const;
@@ -238,6 +376,8 @@ export const endpoints = [
 	'catalog.items.update',
 	'catalog.items.archive',
 	'catalog.items.restore',
+	'catalog.items.archive-many',
+	'catalog.items.restore-many',
 	'catalog.items.delete',
 	'catalog.items.history',
 ] as const;

package/.ai/references/catalog/src/api/list-cursor.ts

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { decodeCursor, encodeCursor, HttpProblem } from '@flowdular/sdk/server';
+import type {
+	CatalogItemKind,
+	CatalogItemStatus,
+	CatalogListSort,
+} from '../domain/types.ts';
+import type { CatalogPageKeyset } from '../services/repository.ts';
+
+/** The listing a cursor belongs to: its order and its filters. */
+export interface CatalogListQuery {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+	readonly kind: CatalogItemKind | null;
+	readonly status: CatalogItemStatus | null;
+	readonly search: string;
+}
+
+function cursorInvalid(): HttpProblem {
+	return new HttpProblem(
+		'CURSOR_INVALID',
+		'The page cursor is not valid.',
+		400,
+	);
+}
+
+/* The filters travel as a digest so a long term cannot push the signed cursor
+   past its length bound. */
+function filtersDigest(query: CatalogListQuery): string {
+	return createHash('sha256')
+		.update(
+			JSON.stringify([query.kind ?? '', query.status ?? '', query.search]),
+		)
+		.digest('hex')
+		.slice(0, 32);
+}
+
+/* The cursor names the position and the listing it belongs to: the workspace,
+   the sort, the direction and the filters. A cursor presented with any of them
+   changed would splice two listings, so it is refused rather than reused. */
+function cursorPayload(
+	tenantId: string,
+	query: CatalogListQuery,
+	keyset: CatalogPageKeyset,
+): Record<string, string> {
+	return {
+		t: tenantId,
+		s: query.sort,
+		d: query.direction,
+		f: filtersDigest(query),
+		v: keyset.sortValue,
+		id: keyset.id,
+	};
+}
+
+export function encodeListCursor(
+	secret: Uint8Array,
+	tenantId: string,
+	query: CatalogListQuery,
+	keyset: CatalogPageKeyset,
+): string {
+	return encodeCursor(cursorPayload(tenantId, query, keyset), secret);
+}
+
+/** Throws `HttpProblem` `CURSOR_INVALID` (400) for a cursor of another listing. */
+export function decodeListCursor(
+	secret: Uint8Array,
+	cursor: string,
+	tenantId: string,
+	query: CatalogListQuery,
+): CatalogPageKeyset {
+	const payload = decodeCursor(cursor, secret);
+	const expected = cursorPayload(tenantId, query, { sortValue: '', id: '' });
+	for (const key of ['t', 's', 'd', 'f'] as const) {
+		if (payload[key] !== expected[key]) throw cursorInvalid();
+	}
+	const sortValue = payload.v;
+	const id = payload.id;
+	if (typeof sortValue !== 'string' || typeof id !== 'string') {
+		throw cursorInvalid();
+	}
+	return { sortValue, id };
+}