create-flowdular 0.2.6 → 0.3.1

package/agent-template/.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/agent-template/.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/agent-template/.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/agent-template/.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/agent-template/.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/agent-template/.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/agent-template/.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,

package/agent-template/.ai/references/catalog/tests/data-classes.test.ts

@@ -0,0 +1,157 @@
+import { createDataClassRegistry, type Actor } from '@flowdular/sdk/kernel';
+import { afterAll, afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+	CatalogService,
+	EXPORT_PAGE,
+} from '../src/services/catalog-service.ts';
+import { catalogDataClasses } from '../src/services/data-classes.ts';
+import {
+	closeCatalogTestDatabases,
+	createCatalogTestDatabase,
+	type CatalogTestDatabase,
+} from './support/database.ts';
+
+const ACTOR: Actor = { kind: 'user', id: 'account-1', label: 'Ada' };
+
+let database: CatalogTestDatabase;
+let service: CatalogService;
+
+beforeEach(async () => {
+	database = await createCatalogTestDatabase();
+	service = new CatalogService(database.repository);
+});
+
+afterEach(() => database.dispose());
+afterAll(closeCatalogTestDatabases);
+
+function declarations() {
+	return catalogDataClasses(() => Promise.resolve(service));
+}
+
+function declared(key: string) {
+	const declaration = declarations().find((entry) => entry.key === key);
+	if (!declaration) throw new Error(`No data class ${key}.`);
+	return declaration;
+}
+
+async function exported(key: string, tenantId: string) {
+	const rows: Record<string, unknown>[] = [];
+	const summary = await declared(key).export!({
+		tenantId,
+		sink: { write: async (row) => void rows.push(row) },
+	});
+	return { rows, summary };
+}
+
+function create(tenantId: string, sku: string) {
+	return service.create(
+		tenantId,
+		{
+			sku,
+			name: `Item ${sku}`,
+			kind: 'product',
+			unit: 'pcs',
+			basePriceMinor: 1_000,
+			currency: 'PLN',
+		},
+		ACTOR,
+	);
+}
+
+describe('catalog data classes', () => {
+	it('declares one class per owned table the platform registry accepts', () => {
+		const registry = createDataClassRegistry();
+		registry.declare('catalog.core', declarations());
+		registry.seal();
+
+		const entry = registry
+			.list()
+			.find((module) => module.moduleId === 'catalog.core');
+		expect(entry?.classes.map((declaration) => declaration.key)).toEqual([
+			'items',
+			'history',
+			'idempotency-ledger',
+		]);
+		for (const key of ['items', 'history']) {
+			const declaration = declared(key);
+			expect(declaration.exportable).toBe(true);
+			expect(declaration.export).toBeTypeOf('function');
+			expect(declaration.defaultRetentionDays).toBeNull();
+			expect(declaration.sweep).toBeUndefined();
+			expect(declaration.erase).toBeUndefined();
+		}
+		const ledger = declared('idempotency-ledger');
+		expect(ledger.exportable).toBe(false);
+		expect(ledger.excludedReason).toBeTruthy();
+		expect(ledger.export).toBeUndefined();
+		expect(ledger.sweep).toBeUndefined();
+	});
+
+	it('exports the items and history of one tenant and none of another', async () => {
+		const kept = await create('tenant-a', 'A-1');
+		const archived = await create('tenant-a', 'A-2');
+		await service.archive('tenant-a', archived.id, ACTOR);
+		await create('tenant-b', 'B-1');
+
+		const items = await exported('items', 'tenant-a');
+		expect(items.rows.map((row) => row.sku)).toEqual(['A-1', 'A-2']);
+		expect(items.rows[0]).toEqual({
+			id: kept.id,
+			sku: 'A-1',
+			name: 'Item A-1',
+			kind: 'product',
+			unit: 'pcs',
+			basePriceMinor: 1_000,
+			currency: 'PLN',
+			status: 'active',
+			createdAt: new Date(kept.createdAt).toISOString(),
+		});
+		expect(items.summary).toEqual({
+			rows: 2,
+			from: new Date(kept.createdAt),
+			to: new Date(archived.createdAt),
+		});
+
+		const history = await exported('history', 'tenant-a');
+		expect(
+			history.rows.map((row) => [row.recordId, row.action, row.version]),
+		).toEqual([
+			[kept.id, 'created', 1],
+			[archived.id, 'created', 1],
+			[archived.id, 'archived', 2],
+		]);
+		expect(history.rows[2]).toMatchObject({
+			actor: ACTOR,
+			changes: { status: { from: 'active', to: 'archived' } },
+		});
+		expect(history.summary.rows).toBe(3);
+		expect(history.summary.from).toBeInstanceOf(Date);
+		expect(history.summary.to).toBeInstanceOf(Date);
+	});
+
+	it('walks past one page and stays inside the tenant', async () => {
+		const total = EXPORT_PAGE + 1;
+		for (let index = 0; index < total; index += 1) {
+			await create('tenant-a', `P-${String(index).padStart(3, '0')}`);
+		}
+		await create('tenant-b', 'B-1');
+
+		const items = await exported('items', 'tenant-a');
+		expect(items.summary.rows).toBe(total);
+		expect(new Set(items.rows.map((row) => row.id)).size).toBe(total);
+		expect(items.rows.some((row) => row.sku === 'B-1')).toBe(false);
+
+		const history = await exported('history', 'tenant-a');
+		expect(history.summary.rows).toBe(total);
+		expect(new Set(history.rows.map((row) => row.id)).size).toBe(total);
+	});
+
+	it('reports an empty tenant without writing a row', async () => {
+		await create('tenant-b', 'B-1');
+		for (const key of ['items', 'history']) {
+			const { rows, summary } = await exported(key, 'tenant-empty');
+			expect(rows).toEqual([]);
+			expect(summary).toEqual({ rows: 0, from: null, to: null });
+		}
+	});
+});

package/agent-template/.ai/references/catalog.provenance.json

@@ -1,9 +1,9 @@
 {
 	"id": "catalog.core",
-	"version": "0.6.1",
+	"version": "0.7.1",
 	"repository": "Flowdular/official-modules",
-	"sourceCommit": "8ed1e780ba7405d0bdf5082882b92d130b72d081",
-	"artifactSha256": "9010086822aa5f4d13176e465022fd2118c5dd0cb157200b31c2940fec1f3513",
+	"sourceCommit": "be391ac460e53e06a812fc9f0ea1260e2daa058f",
+	"artifactSha256": "7c645f660f44bb4c4540d32dd188d643aafb067f4c505a2722a7f2605a7b54b8",
 	"files": {
 		"LICENSE": "155d722071bad9d0d832482e06fd5a47f7034389cb63aabcb39f4282aa3499fc",
 		"migrations/0001_catalog_core.down.sql": "0962a1edf0bde959cd4facccf77bd5b634d6cc25f125a0c79a61770c8871093f",
@@ -15,9 +15,9 @@
 		"migrations/0004_catalog_idempotency_ledger.down.sql": "8ba72d8edc4d25ecf6d041888cf321690c25afdaf3723812ddd7d391d75370aa",
 		"migrations/0004_catalog_idempotency_ledger.up.sql": "41e86ba2051159c6cc9672bfae17c1d02051da975f1c43c566a2b66592673cb0",
 		"migrations/README.md": "2a15fd001713c2552a3c82b186246aa5fec136f43143cc2d9aa15bd491a09d41",
-		"module.json": "66afd7635404b565e8b86f7c5bc485c85c9d568144858bfcff8a4a9429f76081",
-		"package.json": "08b76b72f6fd7a8e3b08113c135899f6010b5fbbea8ca6be0b68b599afe75dad",
-		"spec/module.yaml": "2df3b7c2cbd20f5f5950b469b092f85ef140875bf789a69da04fb6dc68ae0ff8",
+		"module.json": "f2c66d18e3d54ef1ad8dcc3d26d1ee39a2982463dd3bc3fb26b159039933ed86",
+		"package.json": "3e05cf299b5cc5d948e4b3569bd93f2648a30b22f4f14d26bb31548a79529092",
+		"spec/module.yaml": "633a719d765d9779e2bf4ae0a608251767a62cbb4e15305dc13afcb1e52f14c9",
 		"src/acl/permissions.ts": "3375521a5a229736ffac5a948140ec347dc7a7e4fba80e778c0baaf9e0622590",
 		"src/agent/tools.ts": "3204d20886d2b864482adc1ed3303c653aebd207e16c4fce0c67a4979ea8db07",
 		"src/api/endpoints.ts": "34f1036e759353550be2acf67c6fa254afc790942d09489db2e76a082df5c3a3",
@@ -32,16 +32,18 @@
 		"src/domain/types.ts": "4b26be80954d792b09a3a34d29d845b9f6119640be505daba325fec820e06ef6",
 		"src/domain/variables.ts": "131130e57838235b1f3fcb799da44baeae16522bb346d522827e022305c110b5",
 		"src/index.ts": "5b27943018db9a18651d62add7d6f8397d7c492a204381fae74547b99b91990d",
-		"src/platform.ts": "3bdc15a5749cceeca4e86388fad13aebcbc151bb4226852d46ed7845248c4efe",
+		"src/platform.ts": "b5d809b071af812877f3fb09cce3ced4cdaed8f62611c3eb6d5fcaf6cd7333cb",
 		"src/server/index.ts": "90eae107d863418124e5d10c4d1fe8a119bd14da605b36de708c18d8500c4b5e",
 		"src/server/runtime.ts": "5f4389a6adf8265f6737c489baf686f63cc3550662103d28b2da9800dd9f5b63",
-		"src/services/catalog-service.ts": "e5ffa703f6a87e4e2e762f5beb87952be40b3b5847d10b373033a9b01fa4a378",
-		"src/services/database-repository.ts": "b513a9459fb3fc1362e9dcd98c10a104b02dbb748ae23c59c6768c2f0e7a1466",
+		"src/services/catalog-service.ts": "51f1dcd7c0335f7b417fb45ba700c0098e7193246ee91659c27cab8608282693",
+		"src/services/data-classes.ts": "ea09b1a7def59fee43d57ca7dab6fdb4d646b51df2cacb60af96676c43602b33",
+		"src/services/database-repository.ts": "e6ff61ba197899d5618a02ce743c90d4bf09ae64dcfd1bd3a9985b18a2d23e80",
 		"src/services/index.ts": "a08aefe5101814538666f861536287fc382e6c655d62ba9b9ef4bbfbc6ede4af",
 		"src/services/migration.ts": "89c8e333482c80bc819deba0cf4f4e37e94137933af0f6503f4f9ebcb4f5f371",
-		"src/services/repository.ts": "df0f1364cb05031972993c873faf6bcb7fbe4c92d05a04ae980497d9a732dd7f",
+		"src/services/repository.ts": "98d27a40ff02137ec0c6d8799d9a853d40a76eab2564dd500806c4e84f6dc3a3",
 		"src/services/target-idempotency.ts": "7111b56a30b691eaaaa64f5691895ac94b6e0735b0079794835bbbeba5102cb0",
 		"tests/agent-tools.test.ts": "3cdda30b5454d58c6e8791a98e3daf6fe58b9852cd5c437b3614c3f6123baa91",
+		"tests/data-classes.test.ts": "bea08e4d1d7380ccdebc211374b74a6034714b192fd98bfb90a2218067b35658",
 		"tests/endpoints.test.ts": "24d05c7dd52820f90c777a1b814529f5188a9a5a9daeaacda07314f17b7483cc",
 		"tests/idempotency.test.ts": "f2e0896635bcd95271b66181daa2c084411913cdf864ae8b4814f2beeb8c2943",
 		"tests/migrations.test.ts": "47d3d741eddde8677be287730d2f96af556b4b7bf0d8378f9a12a7309af17d78",

package/agent-template/.ai/rules/flowdular.md

@@ -63,6 +63,10 @@ Do not load the whole skill catalog into the task context.
 12. Keep handoffs short and factual. No AI attribution footers or em/en dashes.
     Sandbox final line: `HANDOFF: <allowed-role> - <why>` or
     `HANDOFF: none - <why>`, never your own role.
+13. Flow: request, `spec-interview`, approval, `module-new`/`module-update`,
+    `auto-review`. Implement from the approved spec and its touch list; do not
+    scan `modules/` or `packages/`. First lookup is `.ai/platform-capabilities.md`.
+    What the spec lacks is a spec defect to report, never a guess.
 
 Detailed recipes: `docs/agent-contract.md` (lookup only).
 Reference module: `.ai/references/catalog`; visual contract: `docs/design-system.md`.

package/agent-template/.ai/skills/README.md

@@ -4,6 +4,7 @@ Flowdular is an agentic foundation framework: the platform is the foundation, an
 
 | Skill                   | One line                                                                                                              |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `spec-interview`        | Interview a request into a v2 spec: capability card defaults, the questions protocol, decisions and out of scope.     |
 | `module-new`            | Create a module from an approved spec: scaffold, what the scaffold lacks, server and client file sets, enable, grant. |
 | `module-update`         | Change an existing module with a fixed touch list per change class and the version bump rules.                        |
 | `spec-approval`         | Record explicit user approval of an exact current module spec without letting an agent approve its own work.          |
@@ -23,9 +24,18 @@ Flowdular is an agentic foundation framework: the platform is the foundation, an
 | `variables`             | Variable-aware fields and templates: the `{{ }}` contract, the scope mask, server-side resolution, adding a source.   |
 | `workflow-development`  | Build, publish, invoke, simulate, and test typed durable workflows and their module integration capability.           |
 | `release-eject-pr`      | Sandbox eject sequence, repository gates, branch and PR conventions, post-merge scope grant.                          |
+| `deploy-operate`        | Container build, production env keys, migrations at rollout, health and readiness, backup and restore, rollback.      |
 
 Choose one skill per task phase: the most specific matching entry above. For ordinary module work use `module-new` or `module-update`. Finish the phase before switching; do not recursively load other SKILL.md files mentioned in a skill. Consult relevant code and supporting references only as needed. `spec-approval` is host-only and requires an explicit user approval instruction.
 
+The normal path for a module is one phase per step:
+
+```text
+request -> spec-interview -> operator approval (spec-approval) -> module-new -> auto-review
+```
+
+An existing module takes the same path with `module-update` in place of `module-new`. `spec-interview` reads `.ai/platform-capabilities.md` and asks for the decisions it cannot infer; implementation reads the approved spec and the touch list instead of scanning the repository, and reports anything the spec lacks as a spec defect.
+
 Where they are read:
 
 - Sandbox: copies are available in `reference/skills/`, but each turn receives exactly one Task skill selected by role, blueprint and request. An explicit `$skill-name` takes precedence only if installed and eligible for that role. Missing matches never load the whole catalog.