@flowdular/sdk 0.3.1 → 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 -->

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.1",
+	"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.1",
+	"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.3.0"
+		"@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.1
+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 };
+}