@flowdular/sdk 0.1.0

package/modules/profile/src/services/database-repository.ts

@@ -0,0 +1,154 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import type { Profile, ProfileLanguagePreference } from '../domain/types.ts';
+import { databaseMigrations } from './migration.ts';
+import type { ProfileRepository } from './repository.ts';
+
+interface ProfileRow {
+	tenant_id: string;
+	account_id: string;
+	display_name: string;
+	updated_at: number | bigint | string;
+}
+
+interface ProfileLanguageRow {
+	tenant_id: string;
+	account_id: string;
+	locale: string;
+	updated_at: number | bigint | string;
+}
+
+/* Queries stay explicit. Profile data never passes through a SQL rewriter, and
+   values always use the adapter's parameter channel. */
+const FIND = `SELECT tenant_id, account_id, display_name, updated_at
+			 FROM profile_records
+			 WHERE tenant_id = $1 AND account_id = $2`;
+
+const SAVE = `INSERT INTO profile_records
+			 (tenant_id, account_id, display_name, updated_at)
+			 VALUES ($1, $2, $3, $4)
+			 ON CONFLICT (tenant_id, account_id) DO UPDATE SET
+			   display_name = excluded.display_name,
+			   updated_at = excluded.updated_at`;
+
+const FIND_LANGUAGE = `SELECT tenant_id, account_id, locale, updated_at
+			 FROM profile_language_preferences
+			 WHERE tenant_id = $1 AND account_id = $2`;
+
+const SAVE_LANGUAGE = `INSERT INTO profile_language_preferences
+			 (tenant_id, account_id, locale, updated_at)
+			 VALUES ($1, $2, $3, $4)
+			 ON CONFLICT (tenant_id, account_id) DO UPDATE SET
+			   locale = excluded.locale,
+			   updated_at = excluded.updated_at`;
+
+/* PostgreSQL returns BIGINT as a string, so every numeric read is normalized
+   before it reaches the domain. */
+function integer(value: ProfileRow['updated_at']): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized) || normalized < 0) {
+		throw new Error('The profile database returned an invalid timestamp.');
+	}
+	return normalized;
+}
+
+function fromRow(row: ProfileRow): Profile {
+	return {
+		tenantId: row.tenant_id,
+		accountId: row.account_id,
+		displayName: row.display_name,
+		updatedAt: integer(row.updated_at),
+	};
+}
+
+function languageFromRow(row: ProfileLanguageRow): ProfileLanguagePreference {
+	return {
+		tenantId: row.tenant_id,
+		accountId: row.account_id,
+		locale: row.locale,
+		updatedAt: integer(row.updated_at),
+	};
+}
+
+/** A repository over a platform-owned PostgreSQL handle. */
+export class DatabaseProfileRepository implements ProfileRepository {
+	constructor(
+		private readonly database: DatabaseHandle,
+		private readonly readyPromise: Promise<void> = Promise.resolve(),
+	) {}
+
+	async find(tenantId: string, accountId: string): Promise<Profile | null> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<ProfileRow>({
+					text: FIND,
+					parameters: [tenantId, accountId],
+				}),
+			{ access: 'read', tenantId },
+		);
+		const row = result.rows[0];
+		return row ? fromRow(row) : null;
+	}
+
+	async save(profile: Profile): Promise<Profile> {
+		await this.readyPromise;
+		await this.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: SAVE,
+					parameters: [
+						profile.tenantId,
+						profile.accountId,
+						profile.displayName,
+						profile.updatedAt,
+					],
+				}),
+			{ access: 'write', tenantId: profile.tenantId },
+		);
+		return profile;
+	}
+
+	async findLanguage(
+		tenantId: string,
+		accountId: string,
+	): Promise<ProfileLanguagePreference | null> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<ProfileLanguageRow>({
+					text: FIND_LANGUAGE,
+					parameters: [tenantId, accountId],
+				}),
+			{ access: 'read', tenantId },
+		);
+		const row = result.rows[0];
+		return row ? languageFromRow(row) : null;
+	}
+
+	async saveLanguage(
+		preference: ProfileLanguagePreference,
+	): Promise<ProfileLanguagePreference> {
+		await this.readyPromise;
+		await this.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: SAVE_LANGUAGE,
+					parameters: [
+						preference.tenantId,
+						preference.accountId,
+						preference.locale,
+						preference.updatedAt,
+					],
+				}),
+			{ access: 'write', tenantId: preference.tenantId },
+		);
+		return preference;
+	}
+}
+
+export async function migrateProfileDatabase(
+	database: DatabaseHandle,
+): Promise<void> {
+	await runDatabaseMigrations(database, 'profile.core', databaseMigrations);
+}

package/modules/profile/src/services/index.ts

@@ -0,0 +1,6 @@
+export { ProfileService, ProfileServiceError } from './profile-service.ts';
+export type { ProfileRepository } from './repository.ts';
+export {
+	DatabaseProfileRepository,
+	migrateProfileDatabase,
+} from './database-repository.ts';

package/modules/profile/src/services/migration.ts

@@ -0,0 +1,58 @@
+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 PROFILE_MIGRATION_001 = `CREATE TABLE IF NOT EXISTS profile_records (
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS profile_records_tenant_account_idx ON profile_records (tenant_id, account_id);
+ALTER TABLE profile_records ENABLE ROW LEVEL SECURITY;
+ALTER TABLE profile_records FORCE ROW LEVEL SECURITY;
+CREATE POLICY profile_records_tenant_policy ON profile_records
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const PROFILE_MIGRATION_002 = `CREATE TABLE IF NOT EXISTS profile_language_preferences (
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  locale TEXT NOT NULL CHECK (length(locale) BETWEEN 2 AND 16),
+  updated_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, account_id)
+);
+ALTER TABLE profile_language_preferences ENABLE ROW LEVEL SECURITY;
+ALTER TABLE profile_language_preferences FORCE ROW LEVEL SECURITY;
+CREATE POLICY profile_language_preferences_tenant_policy ON profile_language_preferences
+  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_profile_core',
+		sql: { postgresql: PROFILE_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'profile_records',
+				'profile_records_tenant_policy',
+				[() => database.schema.hasIndex('profile_records_tenant_account_idx')],
+			),
+	},
+	{
+		id: '0002_profile_language',
+		sql: { postgresql: PROFILE_MIGRATION_002 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'profile_language_preferences',
+				'profile_language_preferences_tenant_policy',
+			),
+	},
+];

package/modules/profile/src/services/profile-service.ts

@@ -0,0 +1,114 @@
+import type {
+	Profile,
+	ProfileLanguagePreference,
+	UpdateProfileInput,
+	UpdateProfileLanguageInput,
+} from '../domain/types.ts';
+import type { ProfileRepository } from './repository.ts';
+
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+const SUPPORTED_PROFILE_LOCALES = new Set(['en', 'pl']);
+
+export class ProfileServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'ProfileServiceError';
+	}
+}
+
+function identifier(value: string, field: string): string {
+	const normalized = typeof value === 'string' ? value.trim() : '';
+	if (!IDENTIFIER_PATTERN.test(normalized)) {
+		throw new ProfileServiceError(
+			'INVALID_IDENTIFIER',
+			field + ' must be a valid identifier containing at most 128 characters.',
+		);
+	}
+	return normalized;
+}
+
+function displayName(value: string): string {
+	if (typeof value !== 'string' || CONTROL_CHARACTER_PATTERN.test(value)) {
+		throw new ProfileServiceError(
+			'INVALID_DISPLAY_NAME',
+			'displayName must not contain control characters.',
+		);
+	}
+	const normalized = value.trim();
+	if (normalized.length < 2 || normalized.length > 120) {
+		throw new ProfileServiceError(
+			'INVALID_DISPLAY_NAME_LENGTH',
+			'displayName must contain between 2 and 120 characters.',
+		);
+	}
+	return normalized;
+}
+
+function locale(value: string): string {
+	const normalized =
+		typeof value === 'string' ? value.trim().toLowerCase() : '';
+	if (!SUPPORTED_PROFILE_LOCALES.has(normalized)) {
+		throw new ProfileServiceError(
+			'UNSUPPORTED_PROFILE_LOCALE',
+			'locale must be one of the supported interface languages.',
+		);
+	}
+	return normalized;
+}
+
+export class ProfileService {
+	constructor(private readonly repository: ProfileRepository) {}
+
+	async read(tenantId: string, accountId: string): Promise<Profile | null> {
+		return this.repository.find(
+			identifier(tenantId, 'tenantId'),
+			identifier(accountId, 'accountId'),
+		);
+	}
+
+	async update(
+		tenantId: string,
+		accountId: string,
+		input: UpdateProfileInput,
+	): Promise<Profile> {
+		const profile: Profile = {
+			tenantId: identifier(tenantId, 'tenantId'),
+			accountId: identifier(accountId, 'accountId'),
+			displayName: displayName(input.displayName),
+			updatedAt: Date.now(),
+		};
+		return this.repository.save(profile);
+	}
+
+	async readLanguage(
+		tenantId: string,
+		accountId: string,
+	): Promise<string | null> {
+		return (
+			(
+				await this.repository.findLanguage(
+					identifier(tenantId, 'tenantId'),
+					identifier(accountId, 'accountId'),
+				)
+			)?.locale ?? null
+		);
+	}
+
+	async updateLanguage(
+		tenantId: string,
+		accountId: string,
+		input: UpdateProfileLanguageInput,
+	): Promise<ProfileLanguagePreference> {
+		return this.repository.saveLanguage({
+			tenantId: identifier(tenantId, 'tenantId'),
+			accountId: identifier(accountId, 'accountId'),
+			locale: locale(input.locale),
+			updatedAt: Date.now(),
+		});
+	}
+}

package/modules/profile/src/services/repository.ts

@@ -0,0 +1,13 @@
+import type { Profile, ProfileLanguagePreference } from '../domain/types.ts';
+
+export interface ProfileRepository {
+	find(tenantId: string, accountId: string): Promise<Profile | null>;
+	save(profile: Profile): Promise<Profile>;
+	findLanguage(
+		tenantId: string,
+		accountId: string,
+	): Promise<ProfileLanguagePreference | null>;
+	saveLanguage(
+		preference: ProfileLanguagePreference,
+	): Promise<ProfileLanguagePreference>;
+}

package/modules/profile/translations/en.json

@@ -0,0 +1,58 @@
+{
+	"module.name": "Profile",
+	"navigation.label": "Profile",
+	"navigation.description": "Language, display name, password, and sessions",
+	"page.eyebrow": "Workspace account",
+	"page.title": "Profile",
+	"page.description": "Manage your language, display name, password, and signed-in sessions.",
+	"page.loading": "Loading your profile…",
+	"page.emptyTitle": "No display name saved",
+	"page.emptyHint": "Save a display name to create your workspace profile.",
+	"action.refresh": "Refresh",
+	"action.retry": "Try again",
+	"displayName.title": "Display name",
+	"displayName.description": "Shown to members of this workspace",
+	"displayName.label": "Display name",
+	"displayName.help": "Use between 2 and 120 characters.",
+	"displayName.saving": "Saving…",
+	"displayName.save": "Save display name",
+	"displayName.saved": "Your display name was saved.",
+	"language.title": "Language",
+	"language.description": "The language used by Flowdular",
+	"language.label": "Interface language",
+	"language.help": "The interface changes as soon as you select a language.",
+	"language.note": "This preference follows your account in this workspace.",
+	"language.saving": "Saving your language preference…",
+	"language.saved": "Your interface language was saved.",
+	"password.title": "Password",
+	"password.description": "Confirm the current password to set a new one",
+	"password.current": "Current password",
+	"password.new": "New password",
+	"password.confirm": "Confirm new password",
+	"password.saving": "Changing…",
+	"password.save": "Change password",
+	"password.saved": "Your password was changed.",
+	"password.validation.required": "Enter your current password and a new password.",
+	"password.validation.mismatch": "The new password and confirmation do not match.",
+	"sessions.title": "Sessions",
+	"sessions.caption": "Your sessions",
+	"sessions.count": "{count} signed in",
+	"sessions.workspace": "Workspace",
+	"sessions.thisDevice": "This device",
+	"sessions.lastSeen": "Last seen",
+	"sessions.expires": "Expires",
+	"sessions.loading": "Loading your sessions…",
+	"sessions.emptyTitle": "No active sessions",
+	"sessions.emptyHint": "Signing in again creates a new session.",
+	"sessions.revoke": "Revoke",
+	"sessions.actions": "Session actions",
+	"sessions.onlyThisDevice": "Only this device is signed in. Changing your password also ends every other session.",
+	"sessions.otherDevices": "Other signed-in sessions: {count}. Revoke the ones you do not recognise.",
+	"sessions.errorLoad": "Could not load your sessions.",
+	"sessions.errorRevoke": "Could not end the session.",
+	"error.load": "Could not load your profile.",
+	"error.languageLoad": "Could not load your language preference.",
+	"error.languageSave": "Could not save your language preference.",
+	"error.update": "Could not update your profile.",
+	"error.password": "Could not change your password."
+}

package/modules/profile/translations/pl.json

@@ -0,0 +1,58 @@
+{
+	"module.name": "Profil",
+	"navigation.label": "Profil",
+	"navigation.description": "Język, nazwa wyświetlana, hasło i sesje",
+	"page.eyebrow": "Konto w przestrzeni roboczej",
+	"page.title": "Profil",
+	"page.description": "Zarządzaj językiem, nazwą wyświetlaną, hasłem i aktywnymi sesjami.",
+	"page.loading": "Wczytywanie profilu…",
+	"page.emptyTitle": "Brak zapisanej nazwy wyświetlanej",
+	"page.emptyHint": "Zapisz nazwę wyświetlaną, aby utworzyć profil w przestrzeni roboczej.",
+	"action.refresh": "Odśwież",
+	"action.retry": "Spróbuj ponownie",
+	"displayName.title": "Nazwa wyświetlana",
+	"displayName.description": "Widoczna dla członków tej przestrzeni roboczej",
+	"displayName.label": "Nazwa wyświetlana",
+	"displayName.help": "Wpisz od 2 do 120 znaków.",
+	"displayName.saving": "Zapisywanie…",
+	"displayName.save": "Zapisz nazwę",
+	"displayName.saved": "Nazwa wyświetlana została zapisana.",
+	"language.title": "Język",
+	"language.description": "Język używany w Flowdular",
+	"language.label": "Język interfejsu",
+	"language.help": "Interfejs zmieni się od razu po wybraniu języka.",
+	"language.note": "To ustawienie jest przypisane do Twojego konta w tej przestrzeni roboczej.",
+	"language.saving": "Zapisywanie ustawienia języka…",
+	"language.saved": "Język interfejsu został zapisany.",
+	"password.title": "Hasło",
+	"password.description": "Potwierdź obecne hasło, aby ustawić nowe",
+	"password.current": "Obecne hasło",
+	"password.new": "Nowe hasło",
+	"password.confirm": "Powtórz nowe hasło",
+	"password.saving": "Zmienianie…",
+	"password.save": "Zmień hasło",
+	"password.saved": "Hasło zostało zmienione.",
+	"password.validation.required": "Wpisz obecne i nowe hasło.",
+	"password.validation.mismatch": "Nowe hasło i jego powtórzenie nie są identyczne.",
+	"sessions.title": "Sesje",
+	"sessions.caption": "Twoje sesje",
+	"sessions.count": "Liczba aktywnych sesji: {count}",
+	"sessions.workspace": "Przestrzeń robocza",
+	"sessions.thisDevice": "To urządzenie",
+	"sessions.lastSeen": "Ostatnia aktywność",
+	"sessions.expires": "Wygasa",
+	"sessions.loading": "Wczytywanie sesji…",
+	"sessions.emptyTitle": "Brak aktywnych sesji",
+	"sessions.emptyHint": "Ponowne logowanie utworzy nową sesję.",
+	"sessions.revoke": "Zakończ",
+	"sessions.actions": "Akcje sesji",
+	"sessions.onlyThisDevice": "Zalogowane jest tylko to urządzenie. Zmiana hasła zakończy również wszystkie pozostałe sesje.",
+	"sessions.otherDevices": "Inne aktywne sesje: {count}. Zakończ te, których nie rozpoznajesz.",
+	"sessions.errorLoad": "Nie udało się wczytać sesji.",
+	"sessions.errorRevoke": "Nie udało się zakończyć sesji.",
+	"error.load": "Nie udało się wczytać profilu.",
+	"error.languageLoad": "Nie udało się wczytać ustawienia języka.",
+	"error.languageSave": "Nie udało się zapisać ustawienia języka.",
+	"error.update": "Nie udało się zaktualizować profilu.",
+	"error.password": "Nie udało się zmienić hasła."
+}

package/modules/sandbox/migrations/0001_sandbox_core.down.sql

@@ -0,0 +1,6 @@
+DROP POLICY IF EXISTS sandbox_access_grants_tenant_policy ON sandbox_access_grants;
+DROP POLICY IF EXISTS sandbox_sessions_tenant_policy ON sandbox_sessions;
+DROP POLICY IF EXISTS sandbox_audit_events_tenant_policy ON sandbox_audit_events;
+DROP TABLE IF EXISTS sandbox_audit_events;
+DROP TABLE IF EXISTS sandbox_sessions;
+DROP TABLE IF EXISTS sandbox_access_grants;

package/modules/sandbox/migrations/0001_sandbox_core.up.sql

@@ -0,0 +1,70 @@
+CREATE TABLE IF NOT EXISTS sandbox_access_grants (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  email TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  capabilities_json TEXT NOT NULL,
+  note TEXT,
+  granted_by TEXT NOT NULL,
+  granted_at BIGINT NOT NULL,
+  expires_at BIGINT,
+  revoked_at BIGINT,
+  revoked_by TEXT,
+  UNIQUE (tenant_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS sandbox_grants_tenant_idx
+  ON sandbox_access_grants (tenant_id, revoked_at, email);
+
+CREATE TABLE IF NOT EXISTS sandbox_sessions (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  module_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  blueprint TEXT NOT NULL,
+  driver TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK (mode IN ('loopback', 'self-hosted')),
+  state TEXT NOT NULL CHECK (state IN (
+    'draft', 'classified', 'planned', 'editing', 'validating',
+    'previewing', 'awaiting-approval', 'accepted', 'failed', 'blocked'
+  )),
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  ejected_at BIGINT
+);
+CREATE INDEX IF NOT EXISTS sandbox_sessions_tenant_idx
+  ON sandbox_sessions (tenant_id, updated_at DESC, id);
+
+CREATE TABLE IF NOT EXISTS sandbox_audit_events (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  subject_type TEXT NOT NULL CHECK (subject_type IN ('grant', 'session', 'module')),
+  subject_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  previous_hash TEXT,
+  event_hash TEXT NOT NULL,
+  UNIQUE (tenant_id, sequence),
+  UNIQUE (tenant_id, event_hash)
+);
+CREATE INDEX IF NOT EXISTS sandbox_audit_tenant_time_idx
+  ON sandbox_audit_events (tenant_id, occurred_at DESC, sequence DESC);
+ALTER TABLE sandbox_access_grants ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sandbox_access_grants FORCE ROW LEVEL SECURITY;
+CREATE POLICY sandbox_access_grants_tenant_policy ON sandbox_access_grants
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+ALTER TABLE sandbox_sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sandbox_sessions FORCE ROW LEVEL SECURITY;
+CREATE POLICY sandbox_sessions_tenant_policy ON sandbox_sessions
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+ALTER TABLE sandbox_audit_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sandbox_audit_events FORCE ROW LEVEL SECURITY;
+CREATE POLICY sandbox_audit_events_tenant_policy ON sandbox_audit_events
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/sandbox/migrations/0002_sandbox_session_lifecycle.down.sql

@@ -0,0 +1,36 @@
+DROP POLICY IF EXISTS sandbox_sessions_tenant_policy ON sandbox_sessions;
+-- Drops archived and deleted sessions with the column; rows in those states
+-- have no representation in the previous schema.
+CREATE TABLE sandbox_sessions_v1 (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  module_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  blueprint TEXT NOT NULL,
+  driver TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK (mode IN ('loopback', 'self-hosted')),
+  state TEXT NOT NULL CHECK (state IN (
+    'draft', 'classified', 'planned', 'editing', 'validating',
+    'previewing', 'awaiting-approval', 'accepted', 'failed', 'blocked'
+  )),
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  ejected_at BIGINT
+);
+INSERT INTO sandbox_sessions_v1
+  (id, tenant_id, account_id, module_id, title, blueprint, driver, mode, state,
+   created_at, updated_at, ejected_at)
+  SELECT id, tenant_id, account_id, module_id, title, blueprint, driver, mode,
+         state, created_at, updated_at, ejected_at
+  FROM sandbox_sessions
+  WHERE state NOT IN ('archived', 'deleted');
+DROP TABLE sandbox_sessions;
+ALTER TABLE sandbox_sessions_v1 RENAME TO sandbox_sessions;
+CREATE INDEX IF NOT EXISTS sandbox_sessions_tenant_idx
+  ON sandbox_sessions (tenant_id, updated_at DESC, id);
+ALTER TABLE sandbox_sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sandbox_sessions FORCE ROW LEVEL SECURITY;
+CREATE POLICY sandbox_sessions_tenant_policy ON sandbox_sessions
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/sandbox/migrations/0002_sandbox_session_lifecycle.up.sql

@@ -0,0 +1,37 @@
+-- Sessions gain an archive timestamp and two lifecycle states. The table is
+-- rebuilt rather than altered in place so the widened state constraint, the
+-- new column, the index, and the tenant policy all land in one step.
+CREATE TABLE sandbox_sessions_v2 (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  module_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  blueprint TEXT NOT NULL,
+  driver TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK (mode IN ('loopback', 'self-hosted')),
+  state TEXT NOT NULL CHECK (state IN (
+    'draft', 'classified', 'planned', 'editing', 'validating',
+    'previewing', 'awaiting-approval', 'accepted', 'failed', 'blocked',
+    'archived', 'deleted'
+  )),
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  ejected_at BIGINT,
+  archived_at BIGINT
+);
+INSERT INTO sandbox_sessions_v2
+  (id, tenant_id, account_id, module_id, title, blueprint, driver, mode, state,
+   created_at, updated_at, ejected_at, archived_at)
+  SELECT id, tenant_id, account_id, module_id, title, blueprint, driver, mode,
+         state, created_at, updated_at, ejected_at, NULL
+  FROM sandbox_sessions;
+DROP TABLE sandbox_sessions;
+ALTER TABLE sandbox_sessions_v2 RENAME TO sandbox_sessions;
+CREATE INDEX IF NOT EXISTS sandbox_sessions_tenant_idx
+  ON sandbox_sessions (tenant_id, updated_at DESC, id);
+ALTER TABLE sandbox_sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE sandbox_sessions FORCE ROW LEVEL SECURITY;
+CREATE POLICY sandbox_sessions_tenant_policy ON sandbox_sessions
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/sandbox/migrations/README.md

@@ -0,0 +1,7 @@
+# Sandbox core migrations
+
+`0001_sandbox_core.up.sql` owns tenant-scoped sandbox access grants, sandbox
+session records, and the module audit hash chain. Draft source code, chat
+transcripts, and provider credentials stay in the sandbox application and never
+reach this database. The matching down migration is destructive and exists for
+controlled local rollback only.

package/modules/sandbox/module.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "sandbox.core",
+	"package": "@flowdular/module-sandbox",
+	"version": "0.4.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations", "cli"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "system.core",
+			"range": "0.5.0"
+		},
+		{
+			"id": "auth.core",
+			"range": "0.10.0"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental",
+	"cli": {
+		"catalog": "src/cli/commands.json",
+		"entry": "src/cli/index.ts"
+	},
+	"platformApi": "0.1.0"
+}