alepha 0.13.6 → 0.13.7

package/dist/api-parameters/index.js

@@ -1,63 +1,877 @@
-import { $module, Primitive, createPrimitive, t } from "alepha";
-import { $entity, pg } from "alepha/orm";
+import { $hook, $inject, $module, KIND, Primitive, createPrimitive, t } from "alepha";
+import { $action } from "alepha/server";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $entity, $repository, pg } from "alepha/orm";
+import { $topic } from "alepha/topic";
+import { $scheduler } from "alepha/scheduler";
 
 //#region ../../src/api-parameters/entities/parameters.ts
+/**
+* Configuration parameter entity for versioned configuration management.
+*
+* Stores all versions of configuration parameters with:
+* - Automatic status management (expired, current, next, future)
+* - Schema versioning for migrations
+* - Activation scheduling
+* - Audit trail (creator info)
+*/
 const parameters = $entity({
 	name: "parameters",
 	schema: t.object({
 		id: pg.primaryKey(t.uuid()),
 		createdAt: pg.createdAt(),
 		updatedAt: pg.updatedAt(),
-		name: t.string(),
+		name: t.text(),
 		content: t.json(),
-		tags: t.optional(t.array(t.string())),
+		schemaHash: t.text(),
+		status: pg.default(t.enum([
+			"expired",
+			"current",
+			"next",
+			"future"
+		]), "future"),
+		activationDate: t.datetime(),
+		expiredAt: t.optional(t.datetime()),
+		version: t.integer(),
+		changeDescription: t.optional(t.text()),
+		tags: t.optional(t.array(t.text())),
 		creatorId: t.optional(t.uuid()),
-		creatorName: t.optional(t.string()),
-		activationDate: t.datetime({ description: "Optional activation date. Default to now. Must be now or later." })
-	})
+		creatorName: t.optional(t.text()),
+		previousContent: t.optional(t.json()),
+		migrationLog: t.optional(t.text())
+	}),
+	indexes: [
+		{ columns: ["name", "status"] },
+		{ columns: ["name", "activationDate"] },
+		{
+			columns: ["name", "version"],
+			unique: true
+		},
+		{ columns: ["status"] },
+		{ columns: ["activationDate"] }
+	]
 });
 
+//#endregion
+//#region ../../src/api-parameters/services/ConfigStore.ts
+/**
+* ConfigStore manages versioned configuration persistence and synchronization.
+*
+* Features:
+* - Stores all config versions in PostgreSQL
+* - Manages status transitions (future → next → current → expired)
+* - Provides cross-instance sync via topic
+* - Supports schema migrations via hash comparison
+* - Auto-activates scheduled configs
+*/
+var ConfigStore = class {
+	log = $logger();
+	dateTimeProvider = $inject(DateTimeProvider);
+	repo = $repository(parameters);
+	/** Unique identifier for this instance (to avoid self-updates) */
+	instanceId = crypto.randomUUID();
+	/** In-memory cache of registered configs */
+	configs = /* @__PURE__ */ new Map();
+	/** Topic for cross-instance synchronization */
+	syncTopic = $topic({
+		name: "config:sync",
+		schema: { payload: t.object({
+			name: t.text(),
+			version: t.integer(),
+			content: t.json(),
+			status: t.enum([
+				"expired",
+				"current",
+				"next",
+				"future"
+			]),
+			instanceId: t.text()
+		}) },
+		handler: async ({ payload }) => {
+			await this.handleSyncMessage(payload);
+		}
+	});
+	/**
+	* Register a config primitive with the store.
+	*/
+	register(config) {
+		this.configs.set(config.name, config);
+	}
+	/**
+	* Load the current config value from database.
+	* Returns the current or next version if no current exists.
+	*/
+	async load(name) {
+		const all = await this.repo.findMany({
+			where: { name },
+			orderBy: {
+				column: "version",
+				direction: "desc"
+			}
+		});
+		let param = all.find((p) => p.status === "current");
+		if (!param) param = all.filter((p) => p.status === "next").sort((a, b) => {
+			return new Date(a.activationDate).getTime() - new Date(b.activationDate).getTime();
+		})[0];
+		return param?.content;
+	}
+	/**
+	* Save a new config version.
+	*
+	* @param name - Config name (e.g., "app.features.flags")
+	* @param content - New config content
+	* @param schemaHash - Hash of the schema for migration detection
+	* @param options - Additional options (activation date, creator info, etc.)
+	*/
+	async save(name, content, schemaHash, options = {}) {
+		const now = this.dateTimeProvider.now().toDate();
+		const activationDate = options.activationDate ?? now;
+		const isImmediate = activationDate <= now;
+		const versions = await this.repo.findMany({
+			where: { name },
+			orderBy: {
+				column: "version",
+				direction: "desc"
+			}
+		});
+		const latestVersion = versions[0];
+		const newVersion = (latestVersion?.version ?? 0) + 1;
+		let status = "future";
+		if (isImmediate) status = "current";
+		const previousContent = versions.find((v) => v.status === "current")?.content;
+		let migrationLog;
+		if (latestVersion && latestVersion.schemaHash !== schemaHash) {
+			migrationLog = `Schema changed from ${latestVersion.schemaHash} to ${schemaHash} at version ${newVersion}`;
+			this.log.info("Config schema migration detected", {
+				name,
+				migrationLog
+			});
+		}
+		if (isImmediate) await this.transitionStatuses(name, now);
+		const inserted = await this.repo.create({
+			name,
+			content,
+			schemaHash,
+			status,
+			activationDate: activationDate.toISOString(),
+			version: newVersion,
+			changeDescription: options.changeDescription,
+			tags: options.tags,
+			creatorId: options.creatorId,
+			creatorName: options.creatorName,
+			previousContent,
+			migrationLog
+		});
+		await this.recalculateStatuses(name);
+		await this.publishSync(name, newVersion, content, status);
+		this.log.info("Config saved", {
+			name,
+			version: newVersion,
+			status
+		});
+		return inserted;
+	}
+	/**
+	* Get all versions of a config.
+	*/
+	async getHistory(name) {
+		return this.repo.findMany({
+			where: { name },
+			orderBy: {
+				column: "version",
+				direction: "desc"
+			}
+		});
+	}
+	/**
+	* Get a specific version of a config.
+	*/
+	async getVersion(name, version) {
+		return (await this.repo.findMany({ where: {
+			name,
+			version
+		} }))[0] ?? null;
+	}
+	/**
+	* Rollback to a previous version by creating a new version with old content.
+	*/
+	async rollback(name, targetVersion, options = {}) {
+		const target = await this.getVersion(name, targetVersion);
+		if (!target) throw new Error(`Config version not found: ${name}@${targetVersion}`);
+		return this.save(name, target.content, target.schemaHash, {
+			...options,
+			changeDescription: options.changeDescription ?? `Rollback to version ${targetVersion}`
+		});
+	}
+	/**
+	* Get all configs by status.
+	*/
+	async getByStatus(status) {
+		return this.repo.findMany({
+			where: { status },
+			orderBy: {
+				column: "name",
+				direction: "asc"
+			}
+		});
+	}
+	/**
+	* Get current config value with fallback to default from registered primitive.
+	* Returns the in-memory current value which may be the default if never saved.
+	*/
+	getCurrentValue(name) {
+		const config = this.configs.get(name);
+		if (!config) return null;
+		return {
+			content: config.current,
+			isDefault: true
+		};
+	}
+	/**
+	* Get config info including current value with default fallback.
+	*/
+	async getCurrentWithDefault(name) {
+		const history = await this.getHistory(name);
+		const current = history.find((v) => v.status === "current") ?? null;
+		const next = history.find((v) => v.status === "next") ?? null;
+		const config = this.configs.get(name);
+		return {
+			current,
+			next,
+			defaultValue: config?.options.default ?? null,
+			currentValue: config?.current ?? null,
+			schema: config?.schema ?? null
+		};
+	}
+	/**
+	* Get all unique config names (for tree view).
+	*/
+	async getConfigNames() {
+		const results = await this.repo.findMany({ orderBy: {
+			column: "name",
+			direction: "asc"
+		} });
+		const names = /* @__PURE__ */ new Set();
+		for (const r of results) names.add(r.name);
+		return Array.from(names);
+	}
+	/**
+	* Build a tree structure from config names for UI.
+	* Includes both database configs and registered (but not yet saved) configs.
+	*/
+	async getConfigTree() {
+		const dbNames = await this.getConfigNames();
+		const registeredNames = Array.from(this.configs.keys());
+		const allNames = [...new Set([...dbNames, ...registeredNames])].sort();
+		return this.buildTree(allNames);
+	}
+	/**
+	* Check and activate scheduled configs that are due.
+	* Should be called periodically (e.g., via scheduler).
+	*/
+	async activateScheduledConfigs() {
+		const now = this.dateTimeProvider.now().toDate();
+		const dueConfigs = await this.repo.findMany({ where: { status: "next" } });
+		for (const config of dueConfigs) if (new Date(config.activationDate) <= now) {
+			await this.transitionStatuses(config.name, now);
+			await this.recalculateStatuses(config.name);
+			const primitive = this.configs.get(config.name);
+			if (primitive) await primitive.reload();
+			await this.publishSync(config.name, config.version, config.content, "current");
+		}
+	}
+	/**
+	* Transition config statuses when a new current is activated.
+	*/
+	async transitionStatuses(name, now) {
+		const currentConfigs = await this.repo.findMany({ where: {
+			name,
+			status: "current"
+		} });
+		for (const config of currentConfigs) await this.repo.updateById(config.id, {
+			status: "expired",
+			expiredAt: now.toISOString()
+		});
+	}
+	/**
+	* Recalculate statuses based on activation dates.
+	*/
+	async recalculateStatuses(name) {
+		const now = this.dateTimeProvider.now().toDate();
+		const nonExpired = (await this.repo.findMany({
+			where: { name },
+			orderBy: {
+				column: "activationDate",
+				direction: "asc"
+			}
+		})).filter((v) => v.status !== "expired");
+		const shouldBeCurrent = nonExpired.filter((v) => new Date(v.activationDate) <= now).pop();
+		const shouldBeNext = nonExpired.filter((v) => new Date(v.activationDate) > now)[0];
+		for (const v of nonExpired) {
+			let newStatus;
+			if (shouldBeCurrent && v.id === shouldBeCurrent.id) newStatus = "current";
+			else if (shouldBeNext && v.id === shouldBeNext.id) newStatus = "next";
+			else if (new Date(v.activationDate) > now) newStatus = "future";
+			else newStatus = "expired";
+			if (v.status !== newStatus) await this.repo.updateById(v.id, {
+				status: newStatus,
+				expiredAt: newStatus === "expired" ? now.toISOString() : void 0
+			});
+		}
+	}
+	/**
+	* Publish sync event to other instances.
+	*/
+	async publishSync(name, version, content, status) {
+		await this.syncTopic.publish({
+			name,
+			version,
+			content,
+			status,
+			instanceId: this.instanceId
+		});
+	}
+	/**
+	* Handle incoming sync message from other instances.
+	*/
+	async handleSyncMessage(payload) {
+		if (payload.instanceId === this.instanceId) return;
+		const config = this.configs.get(payload.name);
+		if (!config) return;
+		if (payload.status === "current") await config.updateFromSync(payload.content);
+	}
+	/**
+	* Build tree structure from dot-notation names.
+	*/
+	buildTree(names) {
+		const root = [];
+		for (const name of names) {
+			const parts = name.split(".");
+			let currentLevel = root;
+			for (let i = 0; i < parts.length; i++) {
+				const part = parts[i];
+				const isLeaf = i === parts.length - 1;
+				const path = parts.slice(0, i + 1).join(".");
+				let existing = currentLevel.find((n) => n.name === part);
+				if (!existing) {
+					existing = {
+						name: part,
+						path,
+						isLeaf,
+						children: []
+					};
+					currentLevel.push(existing);
+				}
+				if (isLeaf) existing.isLeaf = true;
+				currentLevel = existing.children;
+			}
+		}
+		return root;
+	}
+};
+
+//#endregion
+//#region ../../src/api-parameters/controllers/ConfigController.ts
+const parameterResponseSchema = t.object({
+	id: t.uuid(),
+	createdAt: t.datetime(),
+	updatedAt: t.datetime(),
+	name: t.text(),
+	content: t.json(),
+	schemaHash: t.text(),
+	status: t.enum([
+		"expired",
+		"current",
+		"next",
+		"future"
+	]),
+	activationDate: t.datetime(),
+	expiredAt: t.optional(t.datetime()),
+	version: t.integer(),
+	changeDescription: t.optional(t.text()),
+	tags: t.optional(t.array(t.text())),
+	creatorId: t.optional(t.uuid()),
+	creatorName: t.optional(t.text()),
+	previousContent: t.optional(t.json()),
+	migrationLog: t.optional(t.text())
+});
+const treeNodeSchema = t.object({
+	name: t.text(),
+	path: t.text(),
+	isLeaf: t.boolean(),
+	children: t.array(t.any())
+});
+/**
+* REST API controller for versioned configuration management.
+*
+* Provides endpoints for:
+* - Listing all configurations (tree view support)
+* - Getting configuration history (all versions)
+* - Getting current/next configuration values
+* - Creating new configuration versions (immediate or scheduled)
+* - Rolling back to previous versions
+* - Activating scheduled versions immediately
+*/
+var ConfigController = class {
+	store = $inject(ConfigStore);
+	/**
+	* Get tree structure of all configuration names.
+	* Useful for admin UI navigation.
+	*/
+	getConfigTree = $action({
+		description: "Get tree structure of all configuration names for navigation.",
+		path: "/configs/tree",
+		method: "GET",
+		schema: { response: t.array(treeNodeSchema) },
+		handler: async () => {
+			return this.store.getConfigTree();
+		}
+	});
+	/**
+	* List all unique configuration names.
+	*/
+	listConfigNames = $action({
+		description: "List all unique configuration names.",
+		path: "/configs",
+		method: "GET",
+		schema: { response: t.object({ names: t.array(t.text()) }) },
+		handler: async () => {
+			return { names: await this.store.getConfigNames() };
+		}
+	});
+	/**
+	* Get configurations by status.
+	*/
+	getByStatus = $action({
+		description: "Get all configurations with a specific status.",
+		path: "/configs/status/:status",
+		method: "GET",
+		schema: {
+			params: t.object({ status: t.enum([
+				"expired",
+				"current",
+				"next",
+				"future"
+			]) }),
+			response: t.object({ configs: t.array(parameterResponseSchema) })
+		},
+		handler: async ({ params }) => {
+			return { configs: await this.store.getByStatus(params.status) };
+		}
+	});
+	/**
+	* Get version history for a specific configuration.
+	*/
+	getHistory = $action({
+		description: "Get all versions of a specific configuration.",
+		path: "/configs/:name/history",
+		method: "GET",
+		schema: {
+			params: t.object({ name: t.text({ description: "Configuration name (e.g., app.features.flags)" }) }),
+			response: t.object({ versions: t.array(parameterResponseSchema) })
+		},
+		handler: async ({ params }) => {
+			return { versions: await this.store.getHistory(params.name) };
+		}
+	});
+	/**
+	* Get current and next values for a configuration.
+	* Includes defaultValue and currentValue from the registered primitive
+	* even if no versions exist in the database yet.
+	*/
+	getCurrent = $action({
+		description: "Get current and next scheduled values for a configuration.",
+		path: "/configs/:name",
+		method: "GET",
+		schema: {
+			params: t.object({ name: t.text({ description: "Configuration name (e.g., app.features.flags)" }) }),
+			response: t.object({
+				current: t.optional(parameterResponseSchema),
+				next: t.optional(parameterResponseSchema),
+				defaultValue: t.optional(t.json()),
+				currentValue: t.optional(t.json()),
+				schema: t.optional(t.json())
+			})
+		},
+		handler: async ({ params }) => {
+			const result = await this.store.getCurrentWithDefault(params.name);
+			return {
+				current: result.current ?? void 0,
+				next: result.next ?? void 0,
+				defaultValue: result.defaultValue ?? void 0,
+				currentValue: result.currentValue ?? void 0,
+				schema: result.schema ?? void 0
+			};
+		}
+	});
+	/**
+	* Get a specific version of a configuration.
+	*/
+	getVersion = $action({
+		description: "Get a specific version of a configuration.",
+		path: "/configs/:name/versions/:version",
+		method: "GET",
+		schema: {
+			params: t.object({
+				name: t.text(),
+				version: t.integer()
+			}),
+			response: t.object({ config: t.optional(parameterResponseSchema) })
+		},
+		handler: async ({ params }) => {
+			return { config: await this.store.getVersion(params.name, params.version) ?? void 0 };
+		}
+	});
+	/**
+	* Create a new configuration version.
+	*/
+	createVersion = $action({
+		description: "Create a new version of a configuration (immediate or scheduled).",
+		path: "/configs/:name",
+		method: "POST",
+		schema: {
+			params: t.object({ name: t.text({ description: "Configuration name (e.g., app.features.flags)" }) }),
+			body: t.object({
+				content: t.json({ description: "New configuration content" }),
+				schemaHash: t.text({ description: "Hash of the schema for migration detection" }),
+				activationDate: t.optional(t.datetime({ description: "When to activate (default: now)" })),
+				changeDescription: t.optional(t.text({ description: "Description of changes" })),
+				tags: t.optional(t.array(t.text())),
+				creatorId: t.optional(t.uuid()),
+				creatorName: t.optional(t.text())
+			}),
+			response: parameterResponseSchema
+		},
+		handler: async ({ params, body }) => {
+			return this.store.save(params.name, body.content, body.schemaHash, {
+				activationDate: body.activationDate ? new Date(body.activationDate) : void 0,
+				changeDescription: body.changeDescription,
+				tags: body.tags,
+				creatorId: body.creatorId,
+				creatorName: body.creatorName
+			});
+		}
+	});
+	/**
+	* Rollback to a previous version.
+	*/
+	rollback = $action({
+		description: "Rollback a configuration to a previous version (creates new version with old content).",
+		path: "/configs/:name/rollback",
+		method: "POST",
+		schema: {
+			params: t.object({ name: t.text() }),
+			body: t.object({
+				targetVersion: t.integer({ description: "Version number to rollback to" }),
+				changeDescription: t.optional(t.text()),
+				creatorId: t.optional(t.uuid()),
+				creatorName: t.optional(t.text())
+			}),
+			response: parameterResponseSchema
+		},
+		handler: async ({ params, body }) => {
+			return this.store.rollback(params.name, body.targetVersion, {
+				changeDescription: body.changeDescription,
+				creatorId: body.creatorId,
+				creatorName: body.creatorName
+			});
+		}
+	});
+	/**
+	* Activate a scheduled version immediately.
+	*/
+	activateNow = $action({
+		description: "Activate a future/next configuration version immediately.",
+		path: "/configs/:name/activate",
+		method: "POST",
+		schema: {
+			params: t.object({ name: t.text() }),
+			body: t.object({
+				version: t.integer({ description: "Version number to activate" }),
+				creatorId: t.optional(t.uuid()),
+				creatorName: t.optional(t.text())
+			}),
+			response: parameterResponseSchema
+		},
+		handler: async ({ params, body }) => {
+			const target = await this.store.getVersion(params.name, body.version);
+			if (!target) throw new Error(`Version ${body.version} not found for config ${params.name}`);
+			if (target.status === "current") return target;
+			if (target.status === "expired") throw new Error("Cannot activate an expired version. Use rollback instead.");
+			return this.store.save(params.name, target.content, target.schemaHash, {
+				changeDescription: `Early activation of version ${body.version}`,
+				creatorId: body.creatorId,
+				creatorName: body.creatorName
+			});
+		}
+	});
+	/**
+	* Trigger activation check for all scheduled configs.
+	* Normally called by a scheduler, but exposed for manual triggering.
+	*/
+	checkScheduled = $action({
+		description: "Manually trigger activation check for all scheduled configurations.",
+		path: "/configs/activate-scheduled",
+		method: "POST",
+		schema: { response: t.object({ message: t.text() }) },
+		handler: async () => {
+			await this.store.activateScheduledConfigs();
+			return { message: "Scheduled configuration activation check completed" };
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/api-parameters/schedulers/ConfigActivationScheduler.ts
+/**
+* Scheduler that periodically checks for scheduled configurations
+* that should be activated.
+*
+* Runs every minute to check if any NEXT configurations have reached
+* their activation date and need to be promoted to CURRENT.
+*/
+var ConfigActivationScheduler = class {
+	log = $logger();
+	store = $inject(ConfigStore);
+	/**
+	* Check for scheduled configurations every minute.
+	*/
+	checkActivations = $scheduler({
+		name: "config-activation-check",
+		description: "Checks for scheduled configurations that should be activated",
+		interval: [1, "minute"],
+		lock: true,
+		handler: async () => {
+			this.log.debug("Checking for scheduled config activations");
+			await this.store.activateScheduledConfigs();
+		}
+	});
+};
+
 //#endregion
 //#region ../../src/api-parameters/primitives/$config.ts
 var ConfigPrimitive = class extends Primitive {
+	log = $logger();
+	store = $inject(ConfigStore);
+	/** Internal atom key for state management */
+	atomKey;
+	/** Schema hash for migration detection */
+	schemaHash;
+	/** Whether we're currently syncing (to avoid loops) */
+	syncing = false;
+	/** Whether initial load has completed */
+	loaded = false;
+	/**
+	* Configuration name (uses property key if not specified).
+	*/
 	get name() {
 		return this.options.name || this.config.propertyKey;
 	}
+	/**
+	* The TypeBox schema for this configuration.
+	*/
 	get schema() {
 		return this.options.schema;
 	}
+	/**
+	* Get the current configuration value.
+	*/
 	get current() {
-		return this.options.default;
+		return this.alepha.store.get(this.atomKey) ?? this.options.default;
 	}
-	get next() {}
+	/**
+	* Get a specific field from the current configuration.
+	*/
 	get(key) {
 		return this.current[key];
 	}
 	/**
-	* Apply a new configuration object.
+	* Set a new configuration value.
+	*
+	* @param value - The new configuration value
+	* @param options - Optional settings (activation date, creator info, etc.)
+	*/
+	async set(value, options = {}) {
+		await this.store.save(this.name, value, this.schemaHash, {
+			activationDate: options.activationDate,
+			changeDescription: options.changeDescription,
+			tags: options.tags,
+			creatorId: options.user?.id,
+			creatorName: options.user?.name ?? options.user?.email
+		});
+		const now = /* @__PURE__ */ new Date();
+		if (!options.activationDate || options.activationDate <= now) {
+			this.syncing = true;
+			try {
+				this.alepha.store.set(this.atomKey, value);
+			} finally {
+				this.syncing = false;
+			}
+		}
+	}
+	/**
+	* Subscribe to configuration changes.
+	*/
+	sub(fn) {
+		return this.alepha.events.on("state:mutate", { callback: ({ key, value }) => {
+			if (key === this.atomKey) fn(value);
+		} });
+	}
+	/**
+	* Reload configuration from database.
+	* Called when scheduled config activates or sync message received.
 	*/
-	async set(value, options) {}
-	sub(fn) {}
+	async reload() {
+		const value = await this.store.load(this.name);
+		if (value !== null) {
+			this.syncing = true;
+			try {
+				this.alepha.store.set(this.atomKey, value, { skipEvents: true });
+			} finally {
+				this.syncing = false;
+			}
+		}
+	}
+	/**
+	* Update from sync message (called by ConfigStore).
+	* Uses skipEvents to avoid infinite loops.
+	*/
+	async updateFromSync(content) {
+		this.syncing = true;
+		try {
+			this.alepha.store.set(this.atomKey, content, { skipEvents: true });
+		} finally {
+			this.syncing = false;
+		}
+	}
+	/**
+	* Get version history for this configuration.
+	*/
+	async getHistory() {
+		return this.store.getHistory(this.name);
+	}
+	/**
+	* Rollback to a specific version.
+	*/
+	async rollback(version, options) {
+		await this.store.rollback(this.name, version, {
+			changeDescription: options?.changeDescription,
+			creatorId: options?.user?.id,
+			creatorName: options?.user?.name ?? options?.user?.email
+		});
+		await this.reload();
+	}
+	/**
+	* Hook to load initial value from database on start.
+	*/
+	onStart = $hook({
+		on: "start",
+		handler: async () => {
+			await this.loadInitial();
+		}
+	});
+	/**
+	* Called after primitive creation to initialize.
+	*/
+	onInit() {
+		this.atomKey = `config:${this.name}`;
+		this.schemaHash = this.calculateSchemaHash();
+		this.store.register(this);
+		this.alepha.store.set(this.atomKey, this.options.default, { skipEvents: true });
+		this.alepha.events.on("state:mutate", {
+			caller: this.config.service,
+			callback: async ({ key, value, prevValue }) => {
+				if (key !== this.atomKey) return;
+				if (this.syncing) return;
+				if (JSON.stringify(value) === JSON.stringify(prevValue)) return;
+				this.log.debug("Config state mutated, persisting to database", { name: this.name });
+				await this.store.save(this.name, value, this.schemaHash);
+			}
+		});
+	}
+	/**
+	* Load initial value from database.
+	*/
+	async loadInitial() {
+		if (this.loaded) return;
+		const value = await this.store.load(this.name);
+		if (value !== null) {
+			this.syncing = true;
+			try {
+				this.alepha.store.set(this.atomKey, value, { skipEvents: true });
+			} finally {
+				this.syncing = false;
+			}
+		}
+		this.loaded = true;
+	}
+	/**
+	* Calculate a hash of the schema for migration detection.
+	*/
+	calculateSchemaHash() {
+		const schemaJson = JSON.stringify(this.options.schema);
+		let hash = 0;
+		for (let i = 0; i < schemaJson.length; i++) {
+			const char = schemaJson.charCodeAt(i);
+			hash = (hash << 5) - hash + char;
+			hash = hash & hash;
+		}
+		return hash.toString(16);
+	}
 };
 const $config = (options) => {
 	return createPrimitive(ConfigPrimitive, options);
 };
+$config[KIND] = ConfigPrimitive;
 
 //#endregion
 //#region ../../src/api-parameters/index.ts
 /**
-* Provides parameter management API endpoints for Alepha applications.
+* Provides versioned configuration management for Alepha applications.
+*
+* Features:
+* - Type-safe, versioned configuration with `$config` primitive
+* - Schema validation with auto-migration detection
+* - Scheduled activation (FUTURE, NEXT, CURRENT, EXPIRED statuses)
+* - PostgreSQL persistence with full version history
+* - Cross-instance synchronization via topic
+* - Tree view support via dot-notation naming
+* - REST API for configuration management
+* - Automatic activation scheduler
+*
+* @example
+* ```ts
+* import { Alepha } from "alepha";
+* import { AlephaApiParameters } from "alepha/api-parameters";
+*
+* const alepha = Alepha.create();
+* alepha.with(AlephaApiParameters);
 *
-* This module includes configuration parameter storage, retrieval,
-* and dynamic application settings management.
+* // Then use $config in your services:
+* class AppConfig {
+*   features = $config({
+*     name: "app.features.flags",
+*     schema: t.object({
+*       enableBeta: t.boolean(),
+*       maxUploadSize: t.number()
+*     }),
+*     default: { enableBeta: false, maxUploadSize: 10485760 }
+*   });
+* }
+* ```
 *
 * @module alepha.api.parameters
 */
 const AlephaApiParameters = $module({
 	name: "alepha.api.parameters",
-	services: []
+	services: [
+		ConfigStore,
+		ConfigController,
+		ConfigActivationScheduler
+	]
 });
 
 //#endregion
-export { $config, AlephaApiParameters, ConfigPrimitive, parameters };
+export { $config, AlephaApiParameters, ConfigActivationScheduler, ConfigController, ConfigPrimitive, ConfigStore, parameters };
 //# sourceMappingURL=index.js.map