@flowdular/sdk 0.1.0

package/.ai/references/catalog/tests/idempotency.test.ts

@@ -0,0 +1,297 @@
+import type {
+	DatabaseSession,
+	DatabaseProvider,
+} from '@flowdular/sdk/database';
+import type { AgentToolContext } from '@flowdular/sdk/harness/runtime';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { catalogAgentTools } from '../src/agent/tools.ts';
+import type { CatalogItem } from '../src/domain/types.ts';
+import {
+	createCatalogRuntime,
+	type CatalogRuntime,
+} from '../src/server/runtime.ts';
+import {
+	catalogTestProvider,
+	closeCatalogTestDatabases,
+} from './support/database.ts';
+
+const runtimes = new Set<CatalogRuntime>();
+
+afterEach(async () => {
+	await Promise.all([...runtimes].map((runtime) => runtime.dispose()));
+	runtimes.clear();
+});
+
+afterAll(closeCatalogTestDatabases);
+
+/* A second runtime on the same cluster is what a restart looks like to the
+   module: the process is new, the durable ledger is not. */
+function catalogRuntime(databases: DatabaseProvider): CatalogRuntime {
+	const runtime = createCatalogRuntime({ databases, purpose: 'test' });
+	runtimes.add(runtime);
+	return runtime;
+}
+
+/* DDL needs the owner; tenant data still needs a tenant, even for its owner. */
+async function withMigrationLease<T>(
+	databases: DatabaseProvider,
+	work: (database: DatabaseSession) => Promise<T>,
+): Promise<T> {
+	const lease = await databases.acquire({
+		namespace: 'catalog.core',
+		purpose: 'migration',
+	});
+	try {
+		return await lease.database.transaction(work, {
+			tenantId: 'tenant-a',
+			access: 'write',
+		});
+	} finally {
+		await lease.release();
+	}
+}
+
+async function rowCounts(
+	databases: DatabaseProvider,
+): Promise<Record<string, number>> {
+	const row = await withMigrationLease(
+		databases,
+		async (database) =>
+			(
+				await database.query<Record<string, string>>({
+					text: `SELECT (SELECT count(*) FROM catalog_items) AS items,
+						 (SELECT count(*) FROM catalog_items_history_v2) AS history,
+						 (SELECT count(*) FROM catalog_idempotency_ledger) AS ledger`,
+				})
+			).rows[0],
+	);
+	return {
+		items: Number(row?.items),
+		history: Number(row?.history),
+		ledger: Number(row?.ledger),
+	};
+}
+
+function context(key: string, tenantId = 'tenant-a'): AgentToolContext {
+	return {
+		runId: 'run-1',
+		tenantId,
+		requestedBy: 'account-1',
+		idempotencyKey: key,
+		actor: {
+			kind: 'agent',
+			id: 'catalog-agent',
+			label: 'Catalog agent',
+			runId: 'run-1',
+		},
+		permissions: new Set(['catalog.items.manage']),
+		signal: new AbortController().signal,
+	};
+}
+
+const input = {
+	sku: 'SKU-100',
+	name: 'Steel bolt',
+	kind: 'product' as const,
+	unit: 'pcs',
+	basePriceMinor: 250,
+	currency: 'EUR',
+};
+
+describe('catalog target idempotency', () => {
+	it('returns the first result after restart and refuses key reuse for another input or operation', async () => {
+		const databases = await catalogTestProvider();
+		const firstRuntime = catalogRuntime(databases);
+		const create = catalogAgentTools(firstRuntime)[1]!;
+		const first = (await create.execute(
+			{ ...input, sku: ' sku-100 ', name: '  Steel bolt  ', currency: 'eur' },
+			context('catalog-create-key-1'),
+		)) as CatalogItem;
+		await firstRuntime.dispose();
+
+		const recoveredRuntime = catalogRuntime(databases);
+		const recoveredCreate = catalogAgentTools(recoveredRuntime)[1]!;
+		const replay = (await recoveredCreate.execute(
+			input,
+			context('catalog-create-key-1'),
+		)) as CatalogItem;
+		expect(replay).toEqual(first);
+		await expect(
+			(await recoveredRuntime.service()).list('tenant-a'),
+		).resolves.toEqual([first]);
+		expect(
+			(
+				await (
+					await recoveredRuntime.service()
+				).history('tenant-a', {
+					recordId: first.id,
+					limit: 10,
+					cursor: null,
+				})
+			).entries,
+		).toHaveLength(1);
+
+		await expect(
+			recoveredCreate.execute(
+				{ ...input, name: 'Different item' },
+				context('catalog-create-key-1'),
+			),
+		).rejects.toMatchObject({ code: 'CATALOG_IDEMPOTENCY_CONFLICT' });
+		await expect(
+			(await recoveredRuntime.service()).createIdempotent(
+				'tenant-a',
+				input,
+				context('catalog-create-key-1').actor!,
+				{
+					key: 'catalog-create-key-1',
+					operationId: 'catalog.item.create@2',
+				},
+			),
+		).rejects.toMatchObject({ code: 'CATALOG_IDEMPOTENCY_CONFLICT' });
+
+		const tenantB = (await recoveredCreate.execute(
+			input,
+			context('catalog-create-key-1', 'tenant-b'),
+		)) as CatalogItem;
+		expect(tenantB.tenantId).toBe('tenant-b');
+		await expect(
+			(await recoveredRuntime.service()).list('tenant-b'),
+		).resolves.toHaveLength(1);
+	});
+
+	it('keeps the ledger after deletion without adding history on replay', async () => {
+		const databases = await catalogTestProvider();
+		const runtime = catalogRuntime(databases);
+		const create = catalogAgentTools(runtime)[1]!;
+		const created = (await create.execute(
+			input,
+			context('catalog-delete-key-1'),
+		)) as CatalogItem;
+		const actor = { kind: 'user', id: 'owner-1', label: 'Owner' } as const;
+		await (await runtime.service()).archive('tenant-a', created.id, actor);
+		await (await runtime.service()).delete('tenant-a', created.id, actor);
+		await expect((await runtime.service()).list('tenant-a')).resolves.toEqual(
+			[],
+		);
+
+		expect(
+			await create.execute(input, context('catalog-delete-key-1')),
+		).toEqual(created);
+		await expect((await runtime.service()).list('tenant-a')).resolves.toEqual(
+			[],
+		);
+		expect(
+			(
+				await (
+					await runtime.service()
+				).history('tenant-a', {
+					recordId: created.id,
+					limit: 10,
+					cursor: null,
+				})
+			).entries.map((entry) => entry.action),
+		).toEqual(['deleted', 'archived', 'created']);
+
+		const evidence = await withMigrationLease(
+			databases,
+			async (database) =>
+				(
+					await database.query<Record<string, unknown>>({
+						text: `SELECT tenant_id, idempotency_key, operation_id, input_digest,
+							 outcome, result_digest
+							 FROM catalog_idempotency_ledger`,
+					})
+				).rows[0],
+		);
+		expect(evidence).toMatchObject({
+			tenant_id: 'tenant-a',
+			idempotency_key: 'catalog-delete-key-1',
+			operation_id: 'catalog.item.create@1',
+			outcome: 'succeeded',
+		});
+		expect(evidence?.input_digest).toMatch(/^sha256:[a-f0-9]{64}$/);
+		expect(evidence?.result_digest).toMatch(/^sha256:[a-f0-9]{64}$/);
+		expect(JSON.stringify(evidence)).not.toContain('Steel bolt');
+	});
+
+	it('rolls back the item and history if the ledger cannot commit', async () => {
+		const databases = await catalogTestProvider();
+		const runtime = catalogRuntime(databases);
+		await runtime.service();
+		/* The ledger is empty here, so an always-false constraint only ever
+		   rejects the write the tool is about to attempt. */
+		await withMigrationLease(databases, (database) =>
+			database.execute({
+				text: `ALTER TABLE catalog_idempotency_ledger
+					 ADD CONSTRAINT forced_ledger_failure CHECK (false) NOT VALID`,
+			}),
+		);
+
+		try {
+			await expect(
+				catalogAgentTools(runtime)[1]!.execute(
+					input,
+					context('catalog-rollback-key-1'),
+				),
+			).rejects.toThrow(/forced_ledger_failure/);
+			await expect((await runtime.service()).list('tenant-a')).resolves.toEqual(
+				[],
+			);
+			expect(await rowCounts(databases)).toEqual({
+				items: 0,
+				history: 0,
+				ledger: 0,
+			});
+		} finally {
+			await withMigrationLease(databases, (database) =>
+				database.execute({
+					text: `ALTER TABLE catalog_idempotency_ledger
+						 DROP CONSTRAINT forced_ledger_failure`,
+				}),
+			);
+		}
+	});
+
+	it('fails closed on a corrupted replay result without recreating the item', async () => {
+		const databases = await catalogTestProvider();
+		const first = catalogRuntime(databases);
+		const create = catalogAgentTools(first)[1]!;
+		const created = (await create.execute(
+			input,
+			context('catalog-corrupt-key-1'),
+		)) as CatalogItem;
+		const actor = { kind: 'user', id: 'owner-1', label: 'Owner' } as const;
+		await (await first.service()).archive('tenant-a', created.id, actor);
+		await (await first.service()).delete('tenant-a', created.id, actor);
+		await first.dispose();
+
+		await withMigrationLease(databases, (database) =>
+			database.execute({
+				text: `UPDATE catalog_idempotency_ledger SET result_json = $1
+					 WHERE tenant_id = $2 AND idempotency_key = $3`,
+				parameters: [
+					JSON.stringify({ ...created, name: 'Tampered' }),
+					'tenant-a',
+					'catalog-corrupt-key-1',
+				],
+			}),
+		);
+
+		const recovered = catalogRuntime(databases);
+		await expect(
+			catalogAgentTools(recovered)[1]!.execute(
+				input,
+				context('catalog-corrupt-key-1'),
+			),
+		).rejects.toMatchObject({ code: 'CATALOG_IDEMPOTENCY_LEDGER_CORRUPT' });
+		await expect((await recovered.service()).list('tenant-a')).resolves.toEqual(
+			[],
+		);
+		expect(
+			await catalogAgentTools(recovered)[1]!.execute(
+				input,
+				context('catalog-corrupt-key-1', 'tenant-b'),
+			),
+		).toMatchObject({ tenantId: 'tenant-b' });
+	});
+});

package/.ai/references/catalog/tests/migrations.test.ts

@@ -0,0 +1,149 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_MIGRATION_LEDGER,
+	databaseMigrationStatus,
+	runDatabaseMigrations,
+} from '@flowdular/sdk/database';
+import { createTestDatabaseProvider } from '@flowdular/sdk/database-testing';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { databaseMigrations } from '../src/services/migration.ts';
+
+const migrationDirectory = new URL('../migrations/', import.meta.url);
+
+const MODULE_TABLES =
+	'catalog_items, catalog_items_history, catalog_items_history_v2, catalog_idempotency_ledger';
+
+let provider: DatabaseProvider;
+let lease: DatabaseAdapterLease;
+
+beforeAll(async () => {
+	provider = createTestDatabaseProvider();
+	lease = await provider.acquire({
+		namespace: 'catalog.core',
+		purpose: 'migration',
+	});
+});
+
+/* Every case states its own starting point, so the shared cluster goes back to
+   an unmigrated, unrecorded schema first. */
+beforeEach(async () => {
+	await lease.database.execute({
+		text: `DROP TABLE IF EXISTS ${MODULE_TABLES} CASCADE`,
+	});
+	if (await lease.database.schema.hasTable(DATABASE_MIGRATION_LEDGER)) {
+		await lease.database.execute({
+			text: `DELETE FROM ${DATABASE_MIGRATION_LEDGER} WHERE namespace = 'catalog.core'`,
+		});
+	}
+});
+
+afterAll(async () => {
+	await lease?.release();
+	await provider?.dispose();
+});
+
+function apply() {
+	return runDatabaseMigrations(
+		lease.database,
+		'catalog.core',
+		databaseMigrations,
+	);
+}
+
+function status() {
+	return databaseMigrationStatus(
+		lease.database,
+		'catalog.core',
+		databaseMigrations,
+	);
+}
+
+describe('catalog migrations', () => {
+	it('mirrors every PostgreSQL up file byte for byte', () => {
+		const files = readdirSync(migrationDirectory)
+			.filter((name) => name.endsWith('.up.sql'))
+			.sort();
+
+		expect(
+			databaseMigrations.map((migration) => `${migration.id}.up.sql`),
+		).toEqual(files);
+		for (const migration of databaseMigrations) {
+			expect(migration.sql.postgresql).toBe(
+				readFileSync(
+					new URL(`${migration.id}.up.sql`, migrationDirectory),
+					'utf8',
+				),
+			);
+			/* PostgreSQL and nothing else. A stray dialect key would ship SQL no
+			   deployment runs and no test covers. */
+			expect(Object.keys(migration.sql)).toEqual(['postgresql']);
+		}
+	});
+
+	it('declares forced PostgreSQL row security for every tenant table', () => {
+		for (const migration of databaseMigrations) {
+			const sql = migration.sql.postgresql ?? '';
+			expect(sql).toContain('ENABLE ROW LEVEL SECURITY');
+			expect(sql).toContain('FORCE ROW LEVEL SECURITY');
+			expect(sql).toContain("current_setting('coreloom.tenant_id', true)");
+			expect(sql).toContain('WITH CHECK');
+		}
+	});
+
+	it('applies every migration on a fresh database', async () => {
+		expect((await apply()).map((entry) => entry.action)).toEqual(
+			databaseMigrations.map(() => 'applied'),
+		);
+		expect((await status()).map((entry) => entry.state)).toEqual(
+			databaseMigrations.map(() => 'applied'),
+		);
+	});
+
+	it('adopts a schema that predates the ledger without changing its rows', async () => {
+		await apply();
+		await lease.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: `INSERT INTO catalog_items
+				 (id, tenant_id, sku, sku_normalized, name, kind, unit,
+				  base_price_minor, currency, status, created_at)
+				 VALUES ('item-1', 'tenant-a', 'SKU-1', 'sku-1', 'Bolt', 'product',
+				         'pcs', 500, 'EUR', 'active', 1)`,
+				}),
+			{ tenantId: 'tenant-a', access: 'write' },
+		);
+		await lease.database.execute({
+			text: `DELETE FROM ${DATABASE_MIGRATION_LEDGER} WHERE namespace = 'catalog.core'`,
+		});
+
+		expect((await status()).map((entry) => entry.state)).toEqual(
+			databaseMigrations.map(() => 'adopted'),
+		);
+		expect((await apply()).map((entry) => entry.action)).toEqual(
+			databaseMigrations.map(() => 'adopted'),
+		);
+		expect(
+			(
+				await lease.database.transaction(
+					(transaction) =>
+						transaction.query<{ sku: string }>({
+							text: 'SELECT sku FROM catalog_items',
+						}),
+					{ tenantId: 'tenant-a', access: 'read' },
+				)
+			).rows,
+		).toEqual([{ sku: 'SKU-1' }]);
+	});
+
+	it('runs clean on a second migration pass', async () => {
+		await apply();
+
+		expect((await apply()).map((entry) => entry.action)).toEqual(
+			databaseMigrations.map(() => 'unchanged'),
+		);
+	});
+});

package/.ai/references/catalog/tests/module.test.ts

@@ -0,0 +1,271 @@
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import {
+	registerModuleTranslations,
+	setActiveLocale,
+	t,
+} from '@flowdular/sdk/client/i18n';
+import translationsEn from '../translations/en.json';
+import translationsPl from '../translations/pl.json';
+import { catalogNavigationLabel } from '../src/client/navigation-copy.ts';
+import { moduleDefinition } from '../src/index.ts';
+import {
+	CatalogService,
+	CatalogServiceError,
+} from '../src/services/catalog-service.ts';
+import {
+	closeCatalogTestDatabases,
+	createCatalogTestDatabase,
+	type CatalogTestDatabase,
+} from './support/database.ts';
+
+const TEST_ACTOR = {
+	kind: 'user',
+	id: 'account-1',
+	label: 'Test user',
+} as const;
+
+const databases = new Set<CatalogTestDatabase>();
+
+afterEach(async () => {
+	await Promise.all([...databases].map((database) => database.dispose()));
+	databases.clear();
+});
+
+afterAll(closeCatalogTestDatabases);
+
+async function catalogFixture(): Promise<CatalogTestDatabase> {
+	const database = await createCatalogTestDatabase();
+	databases.add(database);
+	return database;
+}
+
+async function serviceError(
+	action: () => unknown,
+): Promise<CatalogServiceError> {
+	try {
+		await action();
+	} catch (error) {
+		if (error instanceof CatalogServiceError) return error;
+		throw error;
+	}
+	throw new Error('Expected a CatalogServiceError.');
+}
+
+describe('catalog.core', () => {
+	it('ships matching English and Polish translation keys', async () => {
+		expect(Object.keys(translationsPl).sort()).toEqual(
+			Object.keys(translationsEn).sort(),
+		);
+	});
+
+	it('resolves the navigation label from the registered module bundle', async () => {
+		registerModuleTranslations([
+			{
+				moduleId: 'catalog.core',
+				translations: { en: translationsEn, pl: translationsPl },
+			},
+		]);
+		setActiveLocale('en');
+		expect(catalogNavigationLabel()).toBe('Catalog');
+		setActiveLocale('pl');
+		expect(catalogNavigationLabel()).toBe('Katalog');
+		setActiveLocale('en');
+	});
+
+	it('translates every dynamic record and history value', async () => {
+		registerModuleTranslations([
+			{
+				moduleId: 'catalog.core',
+				translations: { en: translationsEn, pl: translationsPl },
+			},
+		]);
+		for (const locale of ['en', 'pl']) {
+			setActiveLocale(locale);
+			for (const kind of ['product', 'service']) {
+				const key = 'catalog.kind.' + kind;
+				expect(t(key), `${locale}: ${key}`).not.toBe(key);
+			}
+			for (const status of ['active', 'archived']) {
+				const key = 'catalog.status.' + status;
+				expect(t(key), `${locale}: ${key}`).not.toBe(key);
+			}
+			for (const action of [
+				'created',
+				'updated',
+				'archived',
+				'restored',
+				'deleted',
+			]) {
+				const key = 'catalog.history.action.' + action;
+				expect(t(key), `${locale}: ${key}`).not.toBe(key);
+			}
+			for (const actor of ['user', 'agent']) {
+				const key = 'catalog.history.actor.' + actor;
+				expect(t(key), `${locale}: ${key}`).not.toBe(key);
+			}
+			const serviceKey = 'catalog.history.actor.serviceConfiguredBy';
+			expect(
+				t(serviceKey, { name: 'Ada' }),
+				`${locale}: ${serviceKey}`,
+			).not.toBe(serviceKey);
+			for (const field of [
+				'sku',
+				'name',
+				'kind',
+				'unit',
+				'basePriceMinor',
+				'currency',
+				'status',
+			]) {
+				const key = 'catalog.history.field.' + field;
+				expect(t(key), `${locale}: ${key}`).not.toBe(key);
+			}
+		}
+		setActiveLocale('en');
+	});
+
+	it('exports its validated identity', async () => {
+		expect(moduleDefinition.manifest.id).toBe('catalog.core');
+	});
+
+	it('enforces SKU uniqueness inside one tenant only', async () => {
+		const service = new CatalogService((await catalogFixture()).repository);
+		const input = {
+			sku: 'consulting',
+			name: 'Consulting hour',
+			kind: 'service' as const,
+			unit: 'hour',
+			basePriceMinor: 12_000,
+			currency: 'EUR',
+		};
+		await service.create('tenant-a', input, TEST_ACTOR);
+		await expect(
+			service.create('tenant-a', input, TEST_ACTOR),
+		).rejects.toThrowError(/active tenant/);
+		await expect(
+			service.create('tenant-b', input, TEST_ACTOR),
+		).resolves.toBeDefined();
+	});
+
+	it('isolates item lists by trusted tenant id', async () => {
+		const service = new CatalogService((await catalogFixture()).repository);
+		await service.create(
+			'tenant-a',
+			{
+				sku: 'A-1',
+				name: 'Alpha',
+				kind: 'product',
+				unit: 'each',
+				basePriceMinor: 100,
+				currency: 'EUR',
+			},
+			TEST_ACTOR,
+		);
+		expect(await service.list('tenant-b')).toEqual([]);
+	});
+
+	it('keeps lifecycle revisions append-only and tenant-scoped', async () => {
+		const service = new CatalogService((await catalogFixture()).repository);
+		const item = await service.create(
+			'tenant-a',
+			{
+				sku: 'A-1',
+				name: 'Alpha',
+				kind: 'product',
+				unit: 'each',
+				basePriceMinor: 100,
+				currency: 'EUR',
+			},
+			TEST_ACTOR,
+		);
+		await service.update(
+			'tenant-a',
+			{ ...item, name: 'Alpha revised', basePriceMinor: 125 },
+			TEST_ACTOR,
+		);
+		expect(
+			await serviceError(() => service.delete('tenant-a', item.id, TEST_ACTOR)),
+		).toMatchObject({ code: 'CATALOG_ITEM_NOT_ARCHIVED', status: 409 });
+		expect((await service.get('tenant-a', item.id))?.status).toBe('active');
+		await service.archive('tenant-a', item.id, {
+			kind: 'agent',
+			id: 'catalog-agent',
+			label: 'Catalog curator',
+			runId: 'run-1',
+		});
+		await service.restore('tenant-a', item.id, TEST_ACTOR);
+		await service.archive('tenant-a', item.id, TEST_ACTOR);
+		await service.delete('tenant-a', item.id, TEST_ACTOR);
+
+		const history = await service.history('tenant-a', {
+			recordId: item.id,
+			limit: 20,
+			cursor: null,
+		});
+		expect(history.entries.map((entry) => entry.action)).toEqual([
+			'deleted',
+			'archived',
+			'restored',
+			'archived',
+			'updated',
+			'created',
+		]);
+		expect(history.entries[3]?.actor).toEqual({
+			kind: 'agent',
+			id: 'catalog-agent',
+			label: 'Catalog curator',
+			runId: 'run-1',
+		});
+		expect(history.entries[4]?.changes).toEqual({
+			name: { from: 'Alpha', to: 'Alpha revised' },
+			basePriceMinor: { from: 100, to: 125 },
+		});
+		expect(
+			(
+				await service.history('tenant-b', {
+					recordId: item.id,
+					limit: 20,
+					cursor: null,
+				})
+			).entries,
+		).toEqual([]);
+	});
+
+	it('refuses a write that forced row security assigns to another tenant', async () => {
+		const database = await catalogFixture();
+
+		await expect(
+			database.runtime.transaction(
+				(transaction) =>
+					transaction.execute({
+						text: `INSERT INTO catalog_items
+							 (id, tenant_id, sku, sku_normalized, name, kind, unit,
+							  base_price_minor, currency, status, created_at)
+							 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+						parameters: [
+							'forged',
+							'tenant-b',
+							'F-1',
+							'f-1',
+							'Forged',
+							'product',
+							'each',
+							1,
+							'EUR',
+							'active',
+							Date.now(),
+						],
+					}),
+				{ access: 'write', tenantId: 'tenant-a' },
+			),
+		).rejects.toBeDefined();
+	});
+
+	it('refuses any runtime statement without a tenant context', async () => {
+		const database = await catalogFixture();
+
+		await expect(
+			database.runtime.transaction(async () => undefined, { access: 'read' }),
+		).rejects.toMatchObject({ code: 'TENANT_CONTEXT_REQUIRED' });
+	});
+});