@flowdular/sdk 0.2.4 → 0.3.1

package/.ai/policies/capabilities.yaml

@@ -45,6 +45,14 @@ core:
     command: pnpm flowdular module validate
     risk: read
     note: 'schema plus composition entries (PLATFORM_SERVER_ENTRY_MISSING, PLATFORM_EXPORT_MISSING, PLATFORM_CLIENT_ENTRY_MISSING, PLATFORM_CLIENT_EXPORT_MISSING), PACKAGE_NAME_MISMATCH, SPEC_ID_MISMATCH, TRANSLATION_FILE_MISSING, TRANSLATION_KEYS_MISMATCH; warnings SPEC_VERSION_DRIFT, LOCALE_NOT_IN_PROJECT (packages/cli/src/module-validate.ts)'
+  module.version:
+    command: pnpm flowdular module version <id>
+    risk: read
+  module.version.bump:
+    command: pnpm flowdular module version bump <id> <patch|minor|major> [--apply]
+    risk: workspace-write
+    supportsDryRun: true
+    note: one edit for module.json, package.json, specVersion and every dependent range that stops matching
   module.create:
     command: pnpm flowdular module new <id> --spec <path> [--apply]
     risk: workspace-write
@@ -64,6 +72,24 @@ core:
     localOnly: true
     supportsDryRun: true
     effect: applies or adopts the outstanding migrations of one module against the configured PostgreSQL (embedded PGlite outside production) and writes the _coreloom_migrations_v2 ledger; without --apply it reports the plan and writes nothing
+  database.backup:
+    command: pnpm flowdular database backup --output <dir> [--apply]
+    risk: process
+    supportsDryRun: true
+    effect: 'writes the configured database into <dir> plus a backup.json manifest (timestamp, adapter, platform version, enabled modules, SHA-256 fingerprints of the six encryption keys, never the key material); PostgreSQL runs pg_dump --format=custom on the migrator connection with the credentials passed as PG* variables, the embedded adapter is a directory copy; BACKUP_TOOL_MISSING when pg_dump is not on PATH, BACKUP_TARGET_EXISTS when the directory already holds a backup'
+  database.restore:
+    command: pnpm flowdular database restore --input <dir> --apply --confirm restore-database
+    risk: destructive
+    localOnly: true
+    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
@@ -95,6 +121,11 @@ modules:
       risk: process
       supportsDryRun: true
       effect: grants the module spec permissions to every tenant owner in the auth database
+    auth.secrets.rotate:
+      command: pnpm flowdular auth secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals enrolled TOTP secrets with the current MFA key; batches of 200 rows, idempotent, and never prints key material or a secret
     auth.greenfield.reset:
       command: pnpm flowdular auth greenfield --apply --confirm reset-local-auth
       risk: destructive
@@ -110,6 +141,99 @@ modules:
       command: pnpm flowdular agents audit-verify --tenant <id>
       risk: read
       localOnly: true
+    agents.secrets.rotate:
+      command: pnpm flowdular agents secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored provider credentials with the current encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, and never prints a credential
+  automations.core:
+    automations.secrets.rotate:
+      command: pnpm flowdular automations secrets-rotate [--apply]
+      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]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored webhook signing secrets with the current encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, and never prints a secret
+  audit.core:
+    audit.export:
+      command: pnpm flowdular audit export --workspace <slug|id> --output <dir> [--apply]
+      risk: process
+      supportsDryRun: true
+      note: records an export request the running platform performs into FD_AUDIT_EXPORT_DIRECTORY; the dry run counts rows per class and writes nothing; the archive is owner-only
+    audit.seal:
+      command: pnpm flowdular audit seal --workspace <slug|id> --output <dir> [--apply]
+      risk: process
+      supportsDryRun: true
+      note: closes a segment of the workspace audit chain into a signed JSON Lines file under FD_AUDIT_EXPORT_DIRECTORY and records its anchor; the dry run prints the range and writes neither file nor row
+    audit.verify:
+      command: pnpm flowdular audit verify --workspace <slug|id> --input <dir>
+      risk: read
+      supportsDryRun: false
+      note: recomputes every event hash, the segment chain and the anchor signatures of the segments named after that workspace, leaving another workspace's files unread, and names the first line that does not match; it also fails when a recorded anchor has no segment file in the directory and when a file named after this workspace carries another workspace's anchor; one pass reads the newest 4096 files and anchors and reports that window; reads only
+    audit.erase:
+      command: pnpm flowdular audit erase --workspace <slug|id> --account <id> --output <dir> [--apply --confirm erase-subject] [--destroy-key]
+      risk: process
+      supportsDryRun: true
+      note: records an erasure request the running platform performs across every class of the sealed data class registry, through the erase operation each declares; a class declaring none is named not-erasable; refused under a legal hold with HOLD_ACTIVE; the dry run lists what would be erased and writes nothing but the request row, which expires after 24 hours; apply needs --confirm erase-subject and writes an owner-only certificate
+    audit.secrets.rotate:
+      command: pnpm flowdular audit secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-signs stored chain anchors with the current FD_AUDIT_ANCHOR_KEY once their stored signature verifies under the ring, reporting an anchor on an unknown key or one that does not verify instead of rotating it; the anchor and segment hashes are untouched so written segment files still verify, idempotent, and never prints key material
+    audit.holds.list:
+      command: pnpm flowdular audit holds list --workspace <slug|id> [--status active|lifted]
+      risk: read
+      supportsDryRun: false
+      note: lists the legal holds of one workspace, which name the account covered and the matter behind it; reads only
+    audit.holds.place:
+      command: pnpm flowdular audit holds place --workspace <slug|id> --scope <account|workspace|data-class|date-range> --reason <text> [--account <id>] [--class <id>] [--from <date>] [--to <date>] [--apply]
+      risk: process
+      supportsDryRun: true
+      note: places a legal hold and writes the audit event in the same workspace transaction; the dry run prints the plan and writes nothing
+    audit.holds.lift:
+      command: pnpm flowdular audit holds lift --workspace <slug|id> --hold <id> --reason <text> [--apply]
+      risk: process
+      supportsDryRun: true
+      note: lifts one active hold with the reason it is lifted and writes the audit event; lifting an already lifted hold changes nothing; the dry run prints the plan and writes nothing
+  metering.core:
+    metering.limits.list:
+      command: pnpm flowdular metering limits list --workspace <slug|id>
+      risk: read
+      supportsDryRun: false
+      note: lists the workspace's monthly limits per meter; reads only
+    metering.limits.set:
+      command: pnpm flowdular metering limits set --workspace <slug|id> --meter <key> --monthly-limit <n> [--apply]
+      risk: process
+      supportsDryRun: true
+      note: sets one workspace's monthly ceiling for a meter and writes a limit event with the operator label in the same transaction; the dry run prints the plan and writes nothing; an undeclared meter is a warning
+  workflows.core:
+    workflows.secrets.rotate:
+      command: pnpm flowdular workflows secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored run payloads with the current encryption key; batches of 200 payloads in one tenant-scoped transaction each, idempotent, and never prints a payload
   sandbox.core:
     sandbox.access.list:
       command: pnpm flowdular sandbox access
@@ -140,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)
@@ -159,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/policies/path-ownership.yaml

@@ -1,6 +1,9 @@
 schemaVersion: 1
-# Consumed by nobody (zero references under packages/). Review guidance: who
-# answers for a path and which role may write it.
+# Read by the git-pr delivery target (packages/sandbox/src/server/delivery/
+# policies.ts, loadPathOwnership): owners name who answers for a changed path
+# and crossOwnerChanges.requireReviewer asks for a reviewer from each owner in
+# the pull request body. Otherwise review guidance: who answers for a path and
+# which role may write it.
 owners:
   packages/contracts/**: platform-architecture
   packages/kernel/**: platform-architecture

package/.ai/policies/task-budgets.yaml

@@ -1,7 +1,9 @@
 schemaVersion: 1
-# Consumed by nobody (zero references under packages/). The values are the
-# review expectation for a change; the sandbox enforces only the limits marked
-# as code.
+# Read by the git-pr delivery target (packages/sandbox/src/server/delivery/
+# policies.ts, loadTaskBudgets): defaults and per-kind overrides of
+# maxChangedFiles and maxNewDependencies bound a pull request delivery.
+# flowdular.json sandbox.delivery.maxChangedFiles takes precedence. Other
+# values are the review expectation for a change.
 defaults:
   maxChangedFiles: 18
   maxRepairLoops: 2

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

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "catalog.core",
 	"package": "@flowdular/module-catalog",
-	"version": "0.6.1",
+	"version": "0.7.1",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],
 	"platform": {
@@ -13,15 +13,15 @@
 	"dependencies": [
 		{
 			"id": "system.core",
-			"range": "0.5.0"
+			"range": "^0.7.0"
 		},
 		{
 			"id": "auth.core",
-			"range": "0.10.0"
+			"range": "^0.13.0"
 		}
 	],
 	"tenancy": "required",
 	"locales": ["en", "pl"],
 	"stability": "experimental",
-	"platformApi": "0.1.0"
+	"platformApi": "^0.1.0"
 }

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

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-catalog",
-	"version": "0.6.1",
+	"version": "0.7.1",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.1.0"
+		"@flowdular/sdk": "0.3.0"
 	},
 	"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.6.1
+specVersion: 0.7.1
 status: approved
 name: Product Catalog Core
 description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.
@@ -12,9 +12,9 @@ capabilities:
   - translations
 dependencies:
   - id: system.core
-    range: 0.5.0
+    range: ^0.7.0
   - id: auth.core
-    range: 0.10.0
+    range: ^0.13.0
 tenancy: required
 locales:
   - en
@@ -30,6 +30,7 @@ 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.
+  - 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
     description: Read products and services in the active tenant.
@@ -38,6 +39,7 @@ permissions:
 dataOwnership:
   - catalog.core owns SKU, item identity, kind, unit, base price, currency, and lifecycle status.
   - 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

package/.ai/references/catalog/src/platform.ts

@@ -4,6 +4,7 @@ import type {
 } from '@flowdular/sdk/modules/auth/server';
 import { platformVariableRegistry } from '@flowdular/sdk/kernel';
 import { registerCatalogVariableSource } from './domain/variables.ts';
+import { catalogDataClasses } from './services/data-classes.ts';
 import {
 	catalogAgentTools,
 	createCatalogRoutes,
@@ -28,6 +29,7 @@ export function createServerComposition(
 		platformVariableRegistry(context.capabilities),
 		tools,
 	);
+	context.dataClasses.declare(catalogDataClasses(() => runtime.service()));
 	return {
 		routes: createCatalogRoutes(context.auth, runtime),
 		dispose: () => runtime.dispose(),

package/.ai/references/catalog/src/services/catalog-service.ts

@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import {
 	normalizeActor,
 	type Actor,
+	type DataClassExportSink,
+	type DataClassExportSummary,
 	type HistoryPage,
 	type HistoryRequest,
 } from '@flowdular/sdk/kernel';
@@ -11,7 +13,11 @@ import type {
 	CreateCatalogItemInput,
 	UpdateCatalogItemInput,
 } from '../domain/types.ts';
-import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	DuplicateSkuError,
+	type CatalogRepository,
+	type ExportCursor,
+} from './repository.ts';
 import {
 	canonicalDigest,
 	TargetIdempotencyConflictError,
@@ -22,6 +28,9 @@ export interface CatalogIdempotencyRequest {
 	readonly operationId: string;
 }
 
+/** Rows one export read carries; the whole tenant is walked page by page. */
+export const EXPORT_PAGE = 200;
+
 export class CatalogServiceError extends Error {
 	constructor(
 		readonly code: string,
@@ -271,6 +280,60 @@ export class CatalogService {
 		});
 	}
 
+	async exportItemsTo(
+		tenantId: string,
+		sink: DataClassExportSink,
+	): Promise<DataClassExportSummary> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		return await exportPaged(
+			(cursor) =>
+				this.repository.listItemsForExport(
+					trustedTenantId,
+					cursor,
+					EXPORT_PAGE,
+				),
+			(item) => item.createdAt,
+			(item) => ({
+				id: item.id,
+				sku: item.sku,
+				name: item.name,
+				kind: item.kind,
+				unit: item.unit,
+				basePriceMinor: item.basePriceMinor,
+				currency: item.currency,
+				status: item.status,
+				createdAt: new Date(item.createdAt).toISOString(),
+			}),
+			sink,
+		);
+	}
+
+	async exportHistoryTo(
+		tenantId: string,
+		sink: DataClassExportSink,
+	): Promise<DataClassExportSummary> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		return await exportPaged(
+			(cursor) =>
+				this.repository.listHistoryForExport(
+					trustedTenantId,
+					cursor,
+					EXPORT_PAGE,
+				),
+			(entry) => entry.occurredAt,
+			(entry) => ({
+				id: entry.id,
+				recordId: entry.recordId,
+				version: entry.version,
+				action: entry.action,
+				actor: entry.actor,
+				changes: entry.changes,
+				occurredAt: new Date(entry.occurredAt).toISOString(),
+			}),
+			sink,
+		);
+	}
+
 	private async item(tenantId: string, id: string): Promise<CatalogItem> {
 		const item = await this.repository.find(
 			tenantId,
@@ -304,3 +367,28 @@ export class CatalogService {
 		return item;
 	}
 }
+
+async function exportPaged<T extends { readonly id: string }>(
+	page: (after: ExportCursor | null) => Promise<readonly T[]>,
+	at: (record: T) => number,
+	row: (record: T) => Record<string, unknown>,
+	sink: DataClassExportSink,
+): Promise<DataClassExportSummary> {
+	let cursor: ExportCursor | null = null;
+	let rows = 0;
+	let from: Date | null = null;
+	let to: Date | null = null;
+	for (;;) {
+		const records = await page(cursor);
+		for (const record of records) {
+			await sink.write(row(record));
+			rows += 1;
+			from ??= new Date(at(record));
+			to = new Date(at(record));
+		}
+		if (records.length < EXPORT_PAGE) break;
+		const last = records[records.length - 1]!;
+		cursor = { at: at(last), id: last.id };
+	}
+	return { rows, from, to };
+}

package/.ai/references/catalog/src/services/data-classes.ts

@@ -0,0 +1,47 @@
+import type { DataClassDeclaration } from '@flowdular/sdk/kernel';
+import type { CatalogService } from './catalog-service.ts';
+
+/** The class ids are `catalog.core.<key>`. */
+export const CATALOG_DATA_CLASS_KEYS = {
+	items: 'items',
+	history: 'history',
+	idempotencyLedger: 'idempotency-ledger',
+} as const;
+
+/**
+ * What this module holds, for the workspace's data class catalogue. Items and
+ * their history are master data: no retention period, no sweep, no erasure. A
+ * row leaves only when a person deletes it. The idempotency ledger is the
+ * replay guard of the mutating tools and workflow actions; it stays out of the
+ * export because the item it points at is already in the items class.
+ */
+export function catalogDataClasses(
+	service: () => Promise<CatalogService>,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: CATALOG_DATA_CLASS_KEYS.items,
+			label: 'Catalog items',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async ({ tenantId, sink }) =>
+				(await service()).exportItemsTo(tenantId, sink),
+		},
+		{
+			key: CATALOG_DATA_CLASS_KEYS.history,
+			label: 'Catalog item history',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async ({ tenantId, sink }) =>
+				(await service()).exportHistoryTo(tenantId, sink),
+		},
+		{
+			key: CATALOG_DATA_CLASS_KEYS.idempotencyLedger,
+			label: 'Catalog idempotency ledger',
+			defaultRetentionDays: null,
+			exportable: false,
+			excludedReason:
+				'Operational replay ledger of mutating tools and workflow actions; the catalog items it points at are exported by catalog.core.items.',
+		},
+	];
+}

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

@@ -11,13 +11,20 @@ import {
 import {
 	diffFields,
 	type Actor,
+	type HistoryEntry,
 	type HistoryPage,
 	type HistoryQuery,
+	type RecordChanges,
 	type TrackedFields,
+	type UserActor,
 } from '@flowdular/sdk/kernel';
 import type { CatalogItem } from '../domain/types.ts';
 import { databaseMigrations } from './migration.ts';
-import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	DuplicateSkuError,
+	type CatalogRepository,
+	type ExportCursor,
+} from './repository.ts';
 import {
 	canonicalDigest,
 	TargetIdempotencyCorruptionError,
@@ -36,6 +43,18 @@ const COLUMNS = `id, tenant_id, sku, name, kind, unit, base_price_minor,
 const LIST = `SELECT ${COLUMNS} FROM catalog_items
 			 WHERE tenant_id = $1 ORDER BY sku_normalized, id`;
 
+const LIST_FOR_EXPORT = `SELECT ${COLUMNS} FROM catalog_items
+			 WHERE tenant_id = $1
+			   AND ($2::bigint IS NULL OR (created_at, id) > ($2::bigint, $3::text))
+			 ORDER BY created_at, id LIMIT $4`;
+
+const LIST_HISTORY_FOR_EXPORT = `SELECT id, record_id, version, action, actor_kind,
+			  actor_id, actor_label, run_id, configured_by_json, changes_json, occurred_at
+			 FROM ${HISTORY_TABLE}
+			 WHERE tenant_id = $1
+			   AND ($2::bigint IS NULL OR (occurred_at, id) > ($2::bigint, $3::text))
+			 ORDER BY occurred_at, id LIMIT $4`;
+
 const FIND = `SELECT ${COLUMNS} FROM catalog_items WHERE tenant_id = $1 AND id = $2`;
 
 const INSERT = `INSERT INTO catalog_items
@@ -74,6 +93,20 @@ interface CatalogItemRow {
 	created_at: number | bigint | string;
 }
 
+interface HistoryRow {
+	id: string;
+	record_id: string;
+	version: number | bigint | string;
+	action: string;
+	actor_kind: Actor['kind'];
+	actor_id: string;
+	actor_label: string;
+	run_id: string | null;
+	configured_by_json: string | null;
+	changes_json: string;
+	occurred_at: number | bigint | string;
+}
+
 interface IdempotencyRow {
 	operation_id: string;
 	input_digest: string;
@@ -119,6 +152,36 @@ function fromRow(row: CatalogItemRow): CatalogItem {
 	};
 }
 
+function actorFromRow(row: HistoryRow): Actor {
+	const identity = { id: row.actor_id, label: row.actor_label };
+	if (row.actor_kind === 'user') return { kind: 'user', ...identity };
+	if (row.actor_kind === 'agent' && row.run_id !== null) {
+		return { kind: 'agent', ...identity, runId: row.run_id };
+	}
+	if (row.actor_kind === 'service' && row.configured_by_json !== null) {
+		return {
+			kind: 'service',
+			...identity,
+			configuredBy: JSON.parse(row.configured_by_json) as UserActor,
+		};
+	}
+	throw new Error(
+		`The catalog history table returned an invalid actor for "${row.id}".`,
+	);
+}
+
+function historyFromRow(row: HistoryRow): HistoryEntry {
+	return {
+		id: row.id,
+		recordId: row.record_id,
+		version: integer(row.version, 'version'),
+		action: row.action,
+		actor: actorFromRow(row),
+		changes: JSON.parse(row.changes_json) as RecordChanges,
+		occurredAt: integer(row.occurred_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 {
@@ -159,6 +222,40 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 		return result.rows.map(fromRow);
 	}
 
+	async listItemsForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly CatalogItem[]> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<CatalogItemRow>({
+					text: LIST_FOR_EXPORT,
+					parameters: [tenantId, after?.at ?? null, after?.id ?? null, limit],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async listHistoryForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly HistoryEntry[]> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<HistoryRow>({
+					text: LIST_HISTORY_FOR_EXPORT,
+					parameters: [tenantId, after?.at ?? null, after?.id ?? null, limit],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(historyFromRow);
+	}
+
 	async find(tenantId: string, id: string): Promise<CatalogItem | null> {
 		await this.readyPromise;
 		const result = await this.database.transaction(

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

@@ -1,4 +1,9 @@
-import type { Actor, HistoryPage, HistoryQuery } from '@flowdular/sdk/kernel';
+import type {
+	Actor,
+	HistoryEntry,
+	HistoryPage,
+	HistoryQuery,
+} from '@flowdular/sdk/kernel';
 import type { CatalogItem } from '../domain/types.ts';
 import type { TargetIdempotencyRequest } from './target-idempotency.ts';
 
@@ -9,9 +14,25 @@ export class DuplicateSkuError extends Error {
 	}
 }
 
+/** Keyset position of an export page: the record time and id of its last row. */
+export interface ExportCursor {
+	readonly at: number;
+	readonly id: string;
+}
+
 /** The database-agnostic business port. No driver type crosses it. */
 export interface CatalogRepository {
 	list(tenantId: string): Promise<readonly CatalogItem[]>;
+	listItemsForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly CatalogItem[]>;
+	listHistoryForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly HistoryEntry[]>;
 	find(tenantId: string, id: string): Promise<CatalogItem | null>;
 	create(
 		item: CatalogItem,