@flowdular/sdk 0.1.0

package/.ai/references/catalog/src/services/database-repository.ts

@@ -0,0 +1,440 @@
+import { randomUUID } from 'node:crypto';
+import type {
+	DatabaseHandle,
+	DatabaseTransaction,
+} from '@flowdular/sdk/database';
+import {
+	appendRecordHistory,
+	queryRecordHistory,
+	runDatabaseMigrations,
+} from '@flowdular/sdk/database';
+import {
+	diffFields,
+	type Actor,
+	type HistoryPage,
+	type HistoryQuery,
+	type TrackedFields,
+} from '@flowdular/sdk/kernel';
+import type { CatalogItem } from '../domain/types.ts';
+import { databaseMigrations } from './migration.ts';
+import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	canonicalDigest,
+	TargetIdempotencyCorruptionError,
+	TargetIdempotencyConflictError,
+	type TargetIdempotencyEntry,
+	type TargetIdempotencyRequest,
+} from './target-idempotency.ts';
+
+const HISTORY_TABLE = 'catalog_items_history_v2';
+
+const COLUMNS = `id, tenant_id, sku, name, kind, unit, base_price_minor,
+	currency, status, created_at`;
+
+/* Queries stay explicit. Catalog data never passes through a SQL rewriter, and
+   values always use the adapter's parameter channel. */
+const LIST = `SELECT ${COLUMNS} FROM catalog_items
+			 WHERE tenant_id = $1 ORDER BY sku_normalized, id`;
+
+const FIND = `SELECT ${COLUMNS} FROM catalog_items WHERE tenant_id = $1 AND id = $2`;
+
+const INSERT = `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)`;
+
+const UPDATE = `UPDATE catalog_items
+			 SET name = $1, kind = $2, unit = $3, base_price_minor = $4, currency = $5
+			 WHERE tenant_id = $6 AND id = $7 RETURNING ${COLUMNS}`;
+
+const SET_STATUS = `UPDATE catalog_items SET status = $1 WHERE tenant_id = $2 AND id = $3
+			 RETURNING ${COLUMNS}`;
+
+const DELETE = 'DELETE FROM catalog_items WHERE tenant_id = $1 AND id = $2';
+
+const FIND_IDEMPOTENCY = `SELECT operation_id, input_digest, result_json, result_digest
+			 FROM catalog_idempotency_ledger
+			 WHERE tenant_id = $1 AND idempotency_key = $2`;
+
+const RECORD_IDEMPOTENCY = `INSERT INTO catalog_idempotency_ledger
+			 (id, tenant_id, idempotency_key, operation_id, input_digest,
+			  outcome, result_json, result_digest, created_at)
+			 VALUES ($1, $2, $3, $4, $5, 'succeeded', $6, $7, $8)`;
+
+interface CatalogItemRow {
+	id: string;
+	tenant_id: string;
+	sku: string;
+	name: string;
+	kind: CatalogItem['kind'];
+	unit: string;
+	base_price_minor: number | bigint | string;
+	currency: string;
+	status: CatalogItem['status'];
+	created_at: number | bigint | string;
+}
+
+interface IdempotencyRow {
+	operation_id: string;
+	input_digest: string;
+	result_json: string;
+	result_digest: string;
+}
+
+/* 23505 is the SQLSTATE for a unique violation; the constraint name keeps a
+   different unique index on the table from being mistaken for the SKU. The
+   driver text is never surfaced, only the stable domain error. */
+function isDuplicateSku(error: unknown): boolean {
+	const cause = error as { code?: unknown; constraint?: unknown };
+	const text = String(error);
+	return (
+		(cause?.code === '23505' || text.includes('23505')) &&
+		(String(cause?.constraint ?? '').includes('sku_normalized') ||
+			text.includes('sku_normalized'))
+	);
+}
+
+/* PostgreSQL returns BIGINT as a string, so every integer read crosses this
+   instead of trusting the driver's representation. */
+function integer(value: number | bigint | string, field: string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized)) {
+		throw new Error(`The catalog database returned an invalid ${field}.`);
+	}
+	return normalized;
+}
+
+function fromRow(row: CatalogItemRow): CatalogItem {
+	return {
+		id: row.id,
+		tenantId: row.tenant_id,
+		sku: row.sku,
+		name: row.name,
+		kind: row.kind,
+		unit: row.unit,
+		basePriceMinor: integer(row.base_price_minor, 'price'),
+		currency: row.currency,
+		status: row.status,
+		createdAt: integer(row.created_at, 'timestamp'),
+	};
+}
+
+/* The fields a history version reports on. Identity, tenancy and creation time
+   cannot change and are never part of a diff. */
+function tracked(item: CatalogItem): TrackedFields {
+	return {
+		sku: item.sku,
+		name: item.name,
+		kind: item.kind,
+		unit: item.unit,
+		basePriceMinor: item.basePriceMinor,
+		currency: item.currency,
+		status: item.status,
+	};
+}
+
+export async function migrateCatalogDatabase(
+	database: DatabaseHandle,
+): Promise<void> {
+	await runDatabaseMigrations(database, 'catalog.core', databaseMigrations);
+}
+
+/** A repository over a platform-owned PostgreSQL handle. */
+export class DatabaseCatalogRepository implements CatalogRepository {
+	constructor(
+		private readonly database: DatabaseHandle,
+		private readonly readyPromise: Promise<void> = Promise.resolve(),
+	) {}
+
+	async list(tenantId: string): Promise<readonly CatalogItem[]> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<CatalogItemRow>({
+					text: LIST,
+					parameters: [tenantId],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async find(tenantId: string, id: string): Promise<CatalogItem | null> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<CatalogItemRow>({
+					text: FIND,
+					parameters: [tenantId, id],
+				}),
+			{ access: 'read', tenantId },
+		);
+		const row = result.rows[0];
+		return row ? fromRow(row) : null;
+	}
+
+	async create(
+		item: CatalogItem,
+		normalizedSku: string,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		await this.readyPromise;
+		try {
+			return await this.database.transaction(
+				(transaction) => this.#insert(transaction, item, normalizedSku, actor),
+				{ access: 'write', tenantId: item.tenantId },
+			);
+		} catch (error) {
+			if (isDuplicateSku(error)) throw new DuplicateSkuError();
+			throw error;
+		}
+	}
+
+	async createIdempotent(
+		item: CatalogItem,
+		normalizedSku: string,
+		actor: Actor,
+		idempotency: TargetIdempotencyRequest,
+	): Promise<CatalogItem> {
+		await this.readyPromise;
+		try {
+			return await this.database.transaction(
+				async (transaction) => {
+					const existing = await this.#idempotencyEntry(
+						transaction,
+						item.tenantId,
+						idempotency.key,
+					);
+					if (existing) {
+						if (
+							existing.operationId !== idempotency.operationId ||
+							existing.inputDigest !== idempotency.inputDigest
+						) {
+							throw new TargetIdempotencyConflictError();
+						}
+						return this.#result(existing, item.tenantId);
+					}
+
+					const created = await this.#insert(
+						transaction,
+						item,
+						normalizedSku,
+						actor,
+					);
+					await transaction.execute({
+						text: RECORD_IDEMPOTENCY,
+						parameters: [
+							randomUUID(),
+							item.tenantId,
+							idempotency.key,
+							idempotency.operationId,
+							idempotency.inputDigest,
+							JSON.stringify(created),
+							canonicalDigest(created),
+							Date.now(),
+						],
+					});
+					return created;
+				},
+				{ access: 'write', tenantId: item.tenantId },
+			);
+		} catch (error) {
+			if (isDuplicateSku(error)) throw new DuplicateSkuError();
+			throw error;
+		}
+	}
+
+	async update(item: CatalogItem, actor: Actor): Promise<CatalogItem | null> {
+		await this.readyPromise;
+		return this.database.transaction(
+			async (transaction) => {
+				const before = await this.#find(transaction, item.tenantId, item.id);
+				if (!before) return null;
+				const result = await transaction.query<CatalogItemRow>({
+					text: UPDATE,
+					parameters: [
+						item.name,
+						item.kind,
+						item.unit,
+						item.basePriceMinor,
+						item.currency,
+						item.tenantId,
+						item.id,
+					],
+				});
+				const row = result.rows[0];
+				if (!row) return null;
+				const after = fromRow(row);
+				const changes = diffFields(tracked(before), tracked(after));
+				if (Object.keys(changes).length > 0) {
+					await appendRecordHistory(transaction, HISTORY_TABLE, {
+						tenantId: item.tenantId,
+						recordId: after.id,
+						action: 'updated',
+						actor,
+						changes,
+						occurredAt: Date.now(),
+					});
+				}
+				return after;
+			},
+			{ access: 'write', tenantId: item.tenantId },
+		);
+	}
+
+	async setStatus(
+		tenantId: string,
+		id: string,
+		status: CatalogItem['status'],
+		actor: Actor,
+	): Promise<CatalogItem | null> {
+		await this.readyPromise;
+		return this.database.transaction(
+			async (transaction) => {
+				const before = await this.#find(transaction, tenantId, id);
+				if (!before) return null;
+				const result = await transaction.query<CatalogItemRow>({
+					text: SET_STATUS,
+					parameters: [status, tenantId, id],
+				});
+				const row = result.rows[0];
+				if (!row) return null;
+				const after = fromRow(row);
+				if (before.status !== after.status) {
+					await appendRecordHistory(transaction, HISTORY_TABLE, {
+						tenantId,
+						recordId: id,
+						action: status === 'archived' ? 'archived' : 'restored',
+						actor,
+						changes: diffFields(tracked(before), tracked(after)),
+						occurredAt: Date.now(),
+					});
+				}
+				return after;
+			},
+			{ access: 'write', tenantId },
+		);
+	}
+
+	async delete(tenantId: string, id: string, actor: Actor): Promise<boolean> {
+		await this.readyPromise;
+		return this.database.transaction(
+			async (transaction) => {
+				const before = await this.#find(transaction, tenantId, id);
+				if (!before) return false;
+				await appendRecordHistory(transaction, HISTORY_TABLE, {
+					tenantId,
+					recordId: id,
+					action: 'deleted',
+					actor,
+					changes: diffFields(tracked(before), {
+						sku: null,
+						name: null,
+						kind: null,
+						unit: null,
+						basePriceMinor: null,
+						currency: null,
+						status: null,
+					}),
+					occurredAt: Date.now(),
+				});
+				const result = await transaction.execute({
+					text: DELETE,
+					parameters: [tenantId, id],
+				});
+				return result.affectedRows === 1;
+			},
+			{ access: 'write', tenantId },
+		);
+	}
+
+	async history(query: HistoryQuery): Promise<HistoryPage> {
+		await this.readyPromise;
+		return this.database.transaction(
+			(transaction) => queryRecordHistory(transaction, HISTORY_TABLE, query),
+			{ access: 'read', tenantId: query.tenantId },
+		);
+	}
+
+	async #find(
+		transaction: DatabaseTransaction,
+		tenantId: string,
+		id: string,
+	): Promise<CatalogItem | null> {
+		const result = await transaction.query<CatalogItemRow>({
+			text: FIND,
+			parameters: [tenantId, id],
+		});
+		const row = result.rows[0];
+		return row ? fromRow(row) : null;
+	}
+
+	async #insert(
+		transaction: DatabaseTransaction,
+		item: CatalogItem,
+		normalizedSku: string,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		await transaction.execute({
+			text: INSERT,
+			parameters: [
+				item.id,
+				item.tenantId,
+				item.sku,
+				normalizedSku,
+				item.name,
+				item.kind,
+				item.unit,
+				item.basePriceMinor,
+				item.currency,
+				item.status,
+				item.createdAt,
+			],
+		});
+		await appendRecordHistory(transaction, HISTORY_TABLE, {
+			tenantId: item.tenantId,
+			recordId: item.id,
+			action: 'created',
+			actor,
+			changes: diffFields(null, tracked(item)),
+			occurredAt: item.createdAt,
+		});
+		return item;
+	}
+
+	async #idempotencyEntry(
+		transaction: DatabaseTransaction,
+		tenantId: string,
+		key: string,
+	): Promise<TargetIdempotencyEntry | null> {
+		const result = await transaction.query<IdempotencyRow>({
+			text: FIND_IDEMPOTENCY,
+			parameters: [tenantId, key],
+		});
+		const row = result.rows[0];
+		return row
+			? {
+					operationId: row.operation_id,
+					inputDigest: row.input_digest,
+					resultJson: row.result_json,
+					resultDigest: row.result_digest,
+				}
+			: null;
+	}
+
+	#result(entry: TargetIdempotencyEntry, tenantId: string): CatalogItem {
+		let result: CatalogItem;
+		try {
+			result = JSON.parse(entry.resultJson) as CatalogItem;
+		} catch {
+			throw new TargetIdempotencyCorruptionError();
+		}
+		if (
+			result.tenantId !== tenantId ||
+			canonicalDigest(result) !== entry.resultDigest
+		) {
+			throw new TargetIdempotencyCorruptionError();
+		}
+		return result;
+	}
+}

package/.ai/references/catalog/src/services/index.ts

@@ -0,0 +1,4 @@
+export { CatalogService, CatalogServiceError } from './catalog-service.ts';
+export type { CatalogRepository } from './repository.ts';
+export { DuplicateSkuError } from './repository.ts';
+export { DatabaseCatalogRepository } from './database-repository.ts';

package/.ai/references/catalog/src/services/migration.ts

@@ -0,0 +1,171 @@
+import type { DatabaseMigration } from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/* Every constant mirrors its migrations/<id>.up.sql file byte for byte;
+   tests/migrations.test.ts fails on drift. */
+
+export const CATALOG_MIGRATION_001 = `CREATE TABLE IF NOT EXISTS catalog_items (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  sku TEXT NOT NULL,
+  sku_normalized TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('product', 'service')),
+  unit TEXT NOT NULL,
+  base_price_minor BIGINT NOT NULL CHECK (base_price_minor >= 0),
+  currency TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'archived')),
+  created_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, sku_normalized)
+);
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_sku_idx
+  ON catalog_items (tenant_id, sku_normalized, id);
+ALTER TABLE catalog_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_tenant_policy ON catalog_items
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const CATALOG_MIGRATION_002_HISTORY = `CREATE TABLE IF NOT EXISTS catalog_items_history (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  record_id TEXT NOT NULL,
+  version BIGINT NOT NULL CHECK (version >= 1),
+  action TEXT NOT NULL CHECK (length(action) BETWEEN 1 AND 32),
+  actor_kind TEXT NOT NULL CHECK (actor_kind IN ('user', 'agent')),
+  actor_id TEXT NOT NULL CHECK (length(actor_id) BETWEEN 1 AND 128),
+  actor_label TEXT NOT NULL CHECK (length(actor_label) BETWEEN 1 AND 160),
+  run_id TEXT CHECK (run_id IS NULL OR length(run_id) BETWEEN 1 AND 128),
+  changes_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS catalog_items_history_tenant_record_version_idx
+  ON catalog_items_history (tenant_id, record_id, version DESC);
+ALTER TABLE catalog_items_history ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items_history FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_history_tenant_policy ON catalog_items_history
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const CATALOG_MIGRATION_003_HISTORY_SERVICE_ACTORS = `CREATE TABLE IF NOT EXISTS catalog_items_history_v2 (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  record_id TEXT NOT NULL,
+  version BIGINT NOT NULL CHECK (version >= 1),
+  action TEXT NOT NULL CHECK (length(action) BETWEEN 1 AND 32),
+  actor_kind TEXT NOT NULL CHECK (actor_kind IN ('user', 'agent', 'service')),
+  actor_id TEXT NOT NULL CHECK (length(actor_id) BETWEEN 1 AND 128),
+  actor_label TEXT NOT NULL CHECK (length(actor_label) BETWEEN 1 AND 160),
+  run_id TEXT CHECK (run_id IS NULL OR length(run_id) BETWEEN 1 AND 128),
+  configured_by_json TEXT CHECK (configured_by_json IS NULL OR configured_by_json::jsonb IS NOT NULL),
+  changes_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  CHECK (
+    (actor_kind = 'agent' AND run_id IS NOT NULL)
+    OR (actor_kind IN ('user', 'service') AND run_id IS NULL)
+  ),
+  CHECK (
+    (actor_kind = 'service' AND configured_by_json IS NOT NULL)
+    OR (actor_kind IN ('user', 'agent') AND configured_by_json IS NULL)
+  )
+);
+CREATE UNIQUE INDEX IF NOT EXISTS catalog_items_history_v2_tenant_record_version_idx
+  ON catalog_items_history_v2 (tenant_id, record_id, version DESC);
+INSERT INTO catalog_items_history_v2
+  (id, tenant_id, record_id, version, action, actor_kind, actor_id,
+   actor_label, run_id, configured_by_json, changes_json, occurred_at)
+SELECT id, tenant_id, record_id, version, action, actor_kind, actor_id,
+       actor_label, run_id, NULL, changes_json, occurred_at
+FROM catalog_items_history
+ON CONFLICT DO NOTHING;
+ALTER TABLE catalog_items_history_v2 ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items_history_v2 FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_history_v2_tenant_policy ON catalog_items_history_v2
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const CATALOG_MIGRATION_004_IDEMPOTENCY_LEDGER = `CREATE TABLE IF NOT EXISTS catalog_idempotency_ledger (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL CHECK (length(idempotency_key) BETWEEN 8 AND 128),
+  operation_id TEXT NOT NULL CHECK (length(operation_id) BETWEEN 3 AND 160),
+  input_digest TEXT NOT NULL CHECK (length(input_digest) = 71),
+  outcome TEXT NOT NULL CHECK (outcome = 'succeeded'),
+  result_json TEXT NOT NULL CHECK (result_json::jsonb IS NOT NULL),
+  result_digest TEXT NOT NULL CHECK (length(result_digest) = 71),
+  created_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS catalog_idempotency_ledger_tenant_operation_idx
+  ON catalog_idempotency_ledger (tenant_id, operation_id, created_at, id);
+ALTER TABLE catalog_idempotency_ledger ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_idempotency_ledger FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_ledger
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_catalog_core',
+		sql: { postgresql: CATALOG_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'catalog_items',
+				'catalog_items_tenant_policy',
+				[() => database.schema.hasIndex('catalog_items_tenant_sku_idx')],
+			),
+	},
+	{
+		id: '0002_catalog_history',
+		sql: { postgresql: CATALOG_MIGRATION_002_HISTORY },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'catalog_items_history',
+				'catalog_items_history_tenant_policy',
+				[
+					() =>
+						database.schema.hasIndex(
+							'catalog_items_history_tenant_record_version_idx',
+						),
+				],
+			),
+	},
+	{
+		id: '0003_catalog_history_service_actors',
+		sql: { postgresql: CATALOG_MIGRATION_003_HISTORY_SERVICE_ACTORS },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'catalog_items_history_v2',
+				'catalog_items_history_v2_tenant_policy',
+				[
+					() =>
+						database.schema.hasIndex(
+							'catalog_items_history_v2_tenant_record_version_idx',
+						),
+				],
+			),
+	},
+	{
+		id: '0004_catalog_idempotency_ledger',
+		sql: { postgresql: CATALOG_MIGRATION_004_IDEMPOTENCY_LEDGER },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'catalog_idempotency_ledger',
+				'catalog_idempotency_ledger_tenant_policy',
+				[
+					() =>
+						database.schema.hasIndex(
+							'catalog_idempotency_ledger_tenant_operation_idx',
+						),
+				],
+			),
+	},
+];

package/.ai/references/catalog/src/services/repository.ts

@@ -0,0 +1,36 @@
+import type { Actor, HistoryPage, HistoryQuery } from '@flowdular/sdk/kernel';
+import type { CatalogItem } from '../domain/types.ts';
+import type { TargetIdempotencyRequest } from './target-idempotency.ts';
+
+export class DuplicateSkuError extends Error {
+	constructor() {
+		super('An item with this SKU already exists in the active tenant.');
+		this.name = 'DuplicateSkuError';
+	}
+}
+
+/** The database-agnostic business port. No driver type crosses it. */
+export interface CatalogRepository {
+	list(tenantId: string): Promise<readonly CatalogItem[]>;
+	find(tenantId: string, id: string): Promise<CatalogItem | null>;
+	create(
+		item: CatalogItem,
+		normalizedSku: string,
+		actor: Actor,
+	): Promise<CatalogItem>;
+	createIdempotent(
+		item: CatalogItem,
+		normalizedSku: string,
+		actor: Actor,
+		idempotency: TargetIdempotencyRequest,
+	): Promise<CatalogItem>;
+	update(item: CatalogItem, actor: Actor): Promise<CatalogItem | null>;
+	setStatus(
+		tenantId: string,
+		id: string,
+		status: CatalogItem['status'],
+		actor: Actor,
+	): Promise<CatalogItem | null>;
+	delete(tenantId: string, id: string, actor: Actor): Promise<boolean>;
+	history(query: HistoryQuery): Promise<HistoryPage>;
+}

package/.ai/references/catalog/src/services/target-idempotency.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+
+export interface TargetIdempotencyRequest {
+	readonly key: string;
+	readonly operationId: string;
+	readonly inputDigest: string;
+}
+
+export interface TargetIdempotencyEntry {
+	readonly operationId: string;
+	readonly inputDigest: string;
+	readonly resultJson: string;
+	readonly resultDigest: string;
+}
+
+export class TargetIdempotencyConflictError extends Error {
+	readonly code = 'CATALOG_IDEMPOTENCY_CONFLICT';
+
+	constructor() {
+		super(
+			'The idempotency key is bound to another catalog operation or input.',
+		);
+		this.name = 'TargetIdempotencyConflictError';
+	}
+}
+
+export class TargetIdempotencyCorruptionError extends Error {
+	readonly code = 'CATALOG_IDEMPOTENCY_LEDGER_CORRUPT';
+
+	constructor() {
+		super('The catalog idempotency ledger contains an invalid result.');
+		this.name = 'TargetIdempotencyCorruptionError';
+	}
+}
+
+function canonical(value: unknown): string {
+	if (value === null || typeof value !== 'object') {
+		if (typeof value === 'number' && !Number.isFinite(value)) {
+			throw new Error(
+				'Canonical idempotency input must contain finite numbers.',
+			);
+		}
+		const encoded = JSON.stringify(value);
+		if (encoded === undefined) {
+			throw new Error('Canonical idempotency input must be JSON serializable.');
+		}
+		return encoded;
+	}
+	if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+	return `{${Object.entries(value as Record<string, unknown>)
+		.filter(([, entry]) => entry !== undefined)
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+		.join(',')}}`;
+}
+
+export function canonicalDigest(value: unknown): string {
+	return `sha256:${createHash('sha256').update(canonical(value)).digest('hex')}`;
+}