alepha 0.13.5 → 0.13.7

package/dist/api-parameters/index.d.ts

@@ -1,34 +1,120 @@
-import * as alepha1 from "alepha";
-import { Primitive, Static, TObject } from "alepha";
-import * as alepha_orm0 from "alepha/orm";
+import * as alepha317 from "alepha";
+import { KIND, Primitive, Static, TObject } from "alepha";
+import * as alepha_server0 from "alepha/server";
+import { DateTimeProvider } from "alepha/datetime";
+import * as alepha_logger1 from "alepha/logger";
+import * as alepha_orm14 from "alepha/orm";
+import * as alepha_topic0 from "alepha/topic";
+import * as alepha_scheduler0 from "alepha/scheduler";
 import { UserAccount } from "alepha/security";
 
 //#region ../../src/api-parameters/entities/parameters.d.ts
-declare const parameters: alepha_orm0.EntityPrimitive<alepha1.TObject<{
-  id: alepha_orm0.PgAttr<alepha_orm0.PgAttr<alepha1.TString, typeof alepha_orm0.PG_PRIMARY_KEY>, typeof alepha_orm0.PG_DEFAULT>;
-  createdAt: alepha_orm0.PgAttr<alepha_orm0.PgAttr<alepha1.TString, typeof alepha_orm0.PG_CREATED_AT>, typeof alepha_orm0.PG_DEFAULT>;
-  updatedAt: alepha_orm0.PgAttr<alepha_orm0.PgAttr<alepha1.TString, typeof alepha_orm0.PG_UPDATED_AT>, typeof alepha_orm0.PG_DEFAULT>;
-  name: alepha1.TString;
-  content: alepha1.TRecord<string, alepha1.TAny>;
-  tags: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
-  creatorId: alepha1.TOptional<alepha1.TString>;
-  creatorName: alepha1.TOptional<alepha1.TString>;
-  activationDate: alepha1.TString;
+/**
+ * Parameter status values.
+ *
+ * - EXPIRED: Past version, no longer active
+ * - CURRENT: Currently active version
+ * - NEXT: Scheduled to become active (closest future date)
+ * - FUTURE: Scheduled for activation after NEXT
+ */
+type ParameterStatus = "expired" | "current" | "next" | "future";
+/**
+ * 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)
+ */
+declare const parameters: alepha_orm14.EntityPrimitive<alepha317.TObject<{
+  id: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_PRIMARY_KEY>, typeof alepha_orm14.PG_DEFAULT>;
+  createdAt: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_CREATED_AT>, typeof alepha_orm14.PG_DEFAULT>;
+  updatedAt: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_UPDATED_AT>, typeof alepha_orm14.PG_DEFAULT>;
+  /**
+   * Configuration name using dot notation for tree hierarchy.
+   * Examples: "app.features", "app.pricing.tiers", "system.limits"
+   */
+  name: alepha317.TString;
+  /**
+   * The configuration content as JSON.
+   */
+  content: alepha317.TRecord<string, alepha317.TAny>;
+  /**
+   * Schema version hash for detecting schema changes.
+   * Used for auto-migration when schema evolves.
+   */
+  schemaHash: alepha317.TString;
+  /**
+   * Current status of this parameter version.
+   */
+  status: alepha_orm14.PgAttr<alepha317.TUnsafe<"expired" | "current" | "next" | "future">, typeof alepha_orm14.PG_DEFAULT>;
+  /**
+   * When this version should become active.
+   * Default is immediate (now).
+   */
+  activationDate: alepha317.TString;
+  /**
+   * When this version was deactivated (became expired).
+   * Null if still active or scheduled.
+   */
+  expiredAt: alepha317.TOptional<alepha317.TString>;
+  /**
+   * Version number for this configuration.
+   * Auto-incremented per config name.
+   */
+  version: alepha317.TInteger;
+  /**
+   * Optional description of changes in this version.
+   */
+  changeDescription: alepha317.TOptional<alepha317.TString>;
+  /**
+   * Optional tags for filtering/categorization.
+   */
+  tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+  /**
+   * Creator user ID (if available).
+   */
+  creatorId: alepha317.TOptional<alepha317.TString>;
+  /**
+   * Creator display name for audit trail.
+   */
+  creatorName: alepha317.TOptional<alepha317.TString>;
+  /**
+   * Previous content before this change (for rollback reference).
+   */
+  previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+  /**
+   * Migration log if schema changed.
+   */
+  migrationLog: alepha317.TOptional<alepha317.TString>;
 }>>;
-type ParameterEntity = Static<typeof parameters.schema>;
+type Parameter = Static<typeof parameters.schema>;
+type ParameterInsert = Omit<Parameter, "id" | "createdAt" | "updatedAt">;
 //#endregion
 //#region ../../src/api-parameters/primitives/$config.d.ts
 /**
- * Creates a configuration parameter primitive for managing application settings.
+ * Creates a versioned configuration primitive for managing application settings.
+ *
+ * Provides type-safe, versioned configuration with:
+ * - Schema validation with auto-migration detection
+ * - Default values for initial state
+ * - 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 (e.g., "app.features.flags")
  *
- * Provides type-safe, versioned configuration with schema validation, default values,
- * and scheduled activation. Useful for feature flags, system parameters, and runtime settings.
+ * Integrates with Alepha's atom system for state management:
+ * - Uses `alepha.set(atom, value)` for mutations
+ * - Listens to `state:mutate` events to detect changes
+ * - Auto-persists changes to database
+ * - Syncs across instances via topic
  *
  * @example
  * ```ts
  * class AppConfig {
  *   features = $config({
- *     name: "feature-flags",
+ *     name: "app.features.flags",
  *     schema: t.object({
  *       enableBeta: t.boolean(),
  *       maxUploadSize: t.number()
@@ -36,48 +122,640 @@ type ParameterEntity = Static<typeof parameters.schema>;
  *     default: { enableBeta: false, maxUploadSize: 10485760 }
  *   });
  *
- *   async updateFeatures() {
+ *   async enableBeta() {
+ *     // Immediate activation
+ *     await this.features.set({ enableBeta: true, maxUploadSize: 20971520 });
+ *   }
+ *
+ *   async scheduleBetaRelease() {
+ *     // Schedule for future activation
  *     await this.features.set(
  *       { enableBeta: true, maxUploadSize: 20971520 },
- *       { user: currentUser, activationDate: tomorrow }
+ *       { activationDate: new Date('2024-03-01') }
  *     );
  *   }
  * }
  * ```
  */
 interface ConfigPrimitiveOptions<T extends TObject> {
+  /**
+   * Configuration name using dot notation for tree hierarchy.
+   * Examples: "app.features", "app.pricing.tiers", "system.limits"
+   */
   name?: string;
+  /**
+   * Human-readable description of the configuration.
+   */
   description?: string;
+  /**
+   * TypeBox schema defining the configuration structure.
+   */
   schema: T;
+  /**
+   * Default value used when no configuration exists in database.
+   */
   default: Static<T>;
 }
 declare class ConfigPrimitive<T extends TObject> extends Primitive<ConfigPrimitiveOptions<T>> {
+  protected readonly log: alepha_logger1.Logger;
+  protected readonly store: ConfigStore;
+  /** Internal atom key for state management */
+  protected atomKey: string;
+  /** Schema hash for migration detection */
+  protected schemaHash: string;
+  /** Whether we're currently syncing (to avoid loops) */
+  protected syncing: boolean;
+  /** Whether initial load has completed */
+  protected loaded: boolean;
+  /**
+   * Configuration name (uses property key if not specified).
+   */
   get name(): string;
+  /**
+   * The TypeBox schema for this configuration.
+   */
   get schema(): T;
+  /**
+   * Get the current configuration value.
+   */
   get current(): Static<T>;
-  get next(): Static<T> | undefined;
+  /**
+   * Get a specific field from the current configuration.
+   */
   get<Key extends keyof Static<T>>(key: Key): Static<T>[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.)
+   */
+  set(value: Static<T>, options?: SetConfigOptions): Promise<void>;
+  /**
+   * Subscribe to configuration changes.
+   */
+  sub(fn: (curr: Static<T>) => void): () => void;
+  /**
+   * Reload configuration from database.
+   * Called when scheduled config activates or sync message received.
+   */
+  reload(): Promise<void>;
+  /**
+   * Update from sync message (called by ConfigStore).
+   * Uses skipEvents to avoid infinite loops.
+   */
+  updateFromSync(content: unknown): Promise<void>;
+  /**
+   * Get version history for this configuration.
+   */
+  getHistory(): Promise<{
+    expiredAt?: string | undefined;
+    changeDescription?: string | undefined;
+    tags?: string[] | undefined;
+    creatorId?: string | undefined;
+    creatorName?: string | undefined;
+    previousContent?: Record<string, any> | undefined;
+    migrationLog?: string | undefined;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    content: Record<string, any>;
+    schemaHash: string;
+    status: "expired" | "current" | "next" | "future";
+    activationDate: string;
+    version: number;
+  }[]>;
+  /**
+   * Rollback to a specific version.
+   */
+  rollback(version: number, options?: SetConfigOptions): Promise<void>;
+  /**
+   * Hook to load initial value from database on start.
+   */
+  protected readonly onStart: alepha317.HookPrimitive<"start">;
+  /**
+   * Called after primitive creation to initialize.
+   */
+  protected onInit(): void;
+  /**
+   * Load initial value from database.
    */
-  set(value: Static<T>, options: {
-    user?: UserAccount;
-    activationDate?: Date;
-  }): Promise<void>;
-  sub(fn: (curr: Static<T>) => void): void;
+  protected loadInitial(): Promise<void>;
+  /**
+   * Calculate a hash of the schema for migration detection.
+   */
+  protected calculateSchemaHash(): string;
+}
+declare const $config: {
+  <T extends TObject>(options: ConfigPrimitiveOptions<T>): ConfigPrimitive<T>;
+  [KIND]: typeof ConfigPrimitive;
+};
+interface SetConfigOptions {
+  /**
+   * User making the change (for audit trail).
+   */
+  user?: Pick<UserAccount, "id" | "email" | "name">;
+  /**
+   * When this configuration should become active.
+   * Default is immediate (now).
+   */
+  activationDate?: Date;
+  /**
+   * Description of the change.
+   */
+  changeDescription?: string;
+  /**
+   * Tags for filtering/categorization.
+   */
+  tags?: string[];
+}
+//#endregion
+//#region ../../src/api-parameters/services/ConfigStore.d.ts
+/**
+ * Payload for config sync events across instances.
+ */
+interface ConfigSyncPayload {
+  name: string;
+  version: number;
+  content: unknown;
+  status: ParameterStatus;
+  instanceId: string;
+}
+/**
+ * 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
+ */
+declare class ConfigStore {
+  protected readonly log: alepha_logger1.Logger;
+  protected readonly dateTimeProvider: DateTimeProvider;
+  protected readonly repo: alepha_orm14.Repository<TObject<{
+    id: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_PRIMARY_KEY>, typeof alepha_orm14.PG_DEFAULT>;
+    createdAt: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_CREATED_AT>, typeof alepha_orm14.PG_DEFAULT>;
+    updatedAt: alepha_orm14.PgAttr<alepha_orm14.PgAttr<alepha317.TString, typeof alepha_orm14.PG_UPDATED_AT>, typeof alepha_orm14.PG_DEFAULT>;
+    name: alepha317.TString;
+    content: alepha317.TRecord<string, alepha317.TAny>;
+    schemaHash: alepha317.TString;
+    status: alepha_orm14.PgAttr<alepha317.TUnsafe<"expired" | "current" | "next" | "future">, typeof alepha_orm14.PG_DEFAULT>;
+    activationDate: alepha317.TString;
+    expiredAt: alepha317.TOptional<alepha317.TString>;
+    version: alepha317.TInteger;
+    changeDescription: alepha317.TOptional<alepha317.TString>;
+    tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+    creatorId: alepha317.TOptional<alepha317.TString>;
+    creatorName: alepha317.TOptional<alepha317.TString>;
+    previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+    migrationLog: alepha317.TOptional<alepha317.TString>;
+  }>>;
+  /** Unique identifier for this instance (to avoid self-updates) */
+  protected readonly instanceId: `${string}-${string}-${string}-${string}-${string}`;
+  /** In-memory cache of registered configs */
+  protected readonly configs: Map<string, ConfigPrimitive<any>>;
+  /** Topic for cross-instance synchronization */
+  readonly syncTopic: alepha_topic0.TopicPrimitive<{
+    payload: TObject<{
+      name: alepha317.TString;
+      version: alepha317.TInteger;
+      content: alepha317.TRecord<string, alepha317.TAny>;
+      status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+      instanceId: alepha317.TString;
+    }>;
+  }>;
+  /**
+   * Register a config primitive with the store.
+   */
+  register(config: ConfigPrimitive<any>): void;
+  /**
+   * Load the current config value from database.
+   * Returns the current or next version if no current exists.
+   */
+  load<T extends TObject>(name: string): Promise<Static<T> | null>;
+  /**
+   * 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.)
+   */
+  save<T extends TObject>(name: string, content: Static<T>, schemaHash: string, options?: SaveConfigOptions): Promise<Parameter>;
+  /**
+   * Get all versions of a config.
+   */
+  getHistory(name: string): Promise<Parameter[]>;
+  /**
+   * Get a specific version of a config.
+   */
+  getVersion(name: string, version: number): Promise<Parameter | null>;
+  /**
+   * Rollback to a previous version by creating a new version with old content.
+   */
+  rollback(name: string, targetVersion: number, options?: SaveConfigOptions): Promise<Parameter>;
+  /**
+   * Get all configs by status.
+   */
+  getByStatus(status: ParameterStatus): Promise<Parameter[]>;
+  /**
+   * 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: string): {
+    content: unknown;
+    isDefault: boolean;
+  } | null;
+  /**
+   * Get config info including current value with default fallback.
+   */
+  getCurrentWithDefault(name: string): Promise<{
+    current: Parameter | null;
+    next: Parameter | null;
+    defaultValue: unknown | null;
+    currentValue: unknown | null;
+    schema: TObject | null;
+  }>;
+  /**
+   * Get all unique config names (for tree view).
+   */
+  getConfigNames(): Promise<string[]>;
+  /**
+   * Build a tree structure from config names for UI.
+   * Includes both database configs and registered (but not yet saved) configs.
+   */
+  getConfigTree(): Promise<ConfigTreeNode[]>;
+  /**
+   * Check and activate scheduled configs that are due.
+   * Should be called periodically (e.g., via scheduler).
+   */
+  activateScheduledConfigs(): Promise<void>;
+  /**
+   * Transition config statuses when a new current is activated.
+   */
+  protected transitionStatuses(name: string, now: Date): Promise<void>;
+  /**
+   * Recalculate statuses based on activation dates.
+   */
+  protected recalculateStatuses(name: string): Promise<void>;
+  /**
+   * Publish sync event to other instances.
+   */
+  protected publishSync(name: string, version: number, content: unknown, status: ParameterStatus): Promise<void>;
+  /**
+   * Handle incoming sync message from other instances.
+   */
+  protected handleSyncMessage(payload: ConfigSyncPayload): Promise<void>;
+  /**
+   * Build tree structure from dot-notation names.
+   */
+  protected buildTree(names: string[]): ConfigTreeNode[];
+}
+interface SaveConfigOptions {
+  activationDate?: Date;
+  changeDescription?: string;
+  tags?: string[];
+  creatorId?: string;
+  creatorName?: string;
+}
+interface ConfigTreeNode {
+  name: string;
+  path: string;
+  isLeaf: boolean;
+  children: ConfigTreeNode[];
+}
+//#endregion
+//#region ../../src/api-parameters/controllers/ConfigController.d.ts
+/**
+ * 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
+ */
+declare class ConfigController {
+  protected readonly store: ConfigStore;
+  /**
+   * Get tree structure of all configuration names.
+   * Useful for admin UI navigation.
+   */
+  getConfigTree: alepha_server0.ActionPrimitiveFn<{
+    response: alepha317.TArray<any>;
+  }>;
+  /**
+   * List all unique configuration names.
+   */
+  listConfigNames: alepha_server0.ActionPrimitiveFn<{
+    response: alepha317.TObject<{
+      names: alepha317.TArray<alepha317.TString>;
+    }>;
+  }>;
+  /**
+   * Get configurations by status.
+   */
+  getByStatus: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+    }>;
+    response: alepha317.TObject<{
+      configs: alepha317.TArray<alepha317.TObject<{
+        id: alepha317.TString;
+        createdAt: alepha317.TString;
+        updatedAt: alepha317.TString;
+        name: alepha317.TString;
+        content: alepha317.TRecord<string, alepha317.TAny>;
+        schemaHash: alepha317.TString;
+        status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+        activationDate: alepha317.TString;
+        expiredAt: alepha317.TOptional<alepha317.TString>;
+        version: alepha317.TInteger;
+        changeDescription: alepha317.TOptional<alepha317.TString>;
+        tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+        creatorId: alepha317.TOptional<alepha317.TString>;
+        creatorName: alepha317.TOptional<alepha317.TString>;
+        previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+        migrationLog: alepha317.TOptional<alepha317.TString>;
+      }>>;
+    }>;
+  }>;
+  /**
+   * Get version history for a specific configuration.
+   */
+  getHistory: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+    }>;
+    response: alepha317.TObject<{
+      versions: alepha317.TArray<alepha317.TObject<{
+        id: alepha317.TString;
+        createdAt: alepha317.TString;
+        updatedAt: alepha317.TString;
+        name: alepha317.TString;
+        content: alepha317.TRecord<string, alepha317.TAny>;
+        schemaHash: alepha317.TString;
+        status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+        activationDate: alepha317.TString;
+        expiredAt: alepha317.TOptional<alepha317.TString>;
+        version: alepha317.TInteger;
+        changeDescription: alepha317.TOptional<alepha317.TString>;
+        tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+        creatorId: alepha317.TOptional<alepha317.TString>;
+        creatorName: alepha317.TOptional<alepha317.TString>;
+        previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+        migrationLog: alepha317.TOptional<alepha317.TString>;
+      }>>;
+    }>;
+  }>;
+  /**
+   * 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: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+    }>;
+    response: alepha317.TObject<{
+      current: alepha317.TOptional<alepha317.TObject<{
+        id: alepha317.TString;
+        createdAt: alepha317.TString;
+        updatedAt: alepha317.TString;
+        name: alepha317.TString;
+        content: alepha317.TRecord<string, alepha317.TAny>;
+        schemaHash: alepha317.TString;
+        status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+        activationDate: alepha317.TString;
+        expiredAt: alepha317.TOptional<alepha317.TString>;
+        version: alepha317.TInteger;
+        changeDescription: alepha317.TOptional<alepha317.TString>;
+        tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+        creatorId: alepha317.TOptional<alepha317.TString>;
+        creatorName: alepha317.TOptional<alepha317.TString>;
+        previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+        migrationLog: alepha317.TOptional<alepha317.TString>;
+      }>>;
+      next: alepha317.TOptional<alepha317.TObject<{
+        id: alepha317.TString;
+        createdAt: alepha317.TString;
+        updatedAt: alepha317.TString;
+        name: alepha317.TString;
+        content: alepha317.TRecord<string, alepha317.TAny>;
+        schemaHash: alepha317.TString;
+        status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+        activationDate: alepha317.TString;
+        expiredAt: alepha317.TOptional<alepha317.TString>;
+        version: alepha317.TInteger;
+        changeDescription: alepha317.TOptional<alepha317.TString>;
+        tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+        creatorId: alepha317.TOptional<alepha317.TString>;
+        creatorName: alepha317.TOptional<alepha317.TString>;
+        previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+        migrationLog: alepha317.TOptional<alepha317.TString>;
+      }>>;
+      defaultValue: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+      currentValue: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+      schema: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+    }>;
+  }>;
+  /**
+   * Get a specific version of a configuration.
+   */
+  getVersion: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+      version: alepha317.TInteger;
+    }>;
+    response: alepha317.TObject<{
+      config: alepha317.TOptional<alepha317.TObject<{
+        id: alepha317.TString;
+        createdAt: alepha317.TString;
+        updatedAt: alepha317.TString;
+        name: alepha317.TString;
+        content: alepha317.TRecord<string, alepha317.TAny>;
+        schemaHash: alepha317.TString;
+        status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+        activationDate: alepha317.TString;
+        expiredAt: alepha317.TOptional<alepha317.TString>;
+        version: alepha317.TInteger;
+        changeDescription: alepha317.TOptional<alepha317.TString>;
+        tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+        creatorId: alepha317.TOptional<alepha317.TString>;
+        creatorName: alepha317.TOptional<alepha317.TString>;
+        previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+        migrationLog: alepha317.TOptional<alepha317.TString>;
+      }>>;
+    }>;
+  }>;
+  /**
+   * Create a new configuration version.
+   */
+  createVersion: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+    }>;
+    body: alepha317.TObject<{
+      content: alepha317.TRecord<string, alepha317.TAny>;
+      schemaHash: alepha317.TString;
+      activationDate: alepha317.TOptional<alepha317.TString>;
+      changeDescription: alepha317.TOptional<alepha317.TString>;
+      tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+    }>;
+    response: alepha317.TObject<{
+      id: alepha317.TString;
+      createdAt: alepha317.TString;
+      updatedAt: alepha317.TString;
+      name: alepha317.TString;
+      content: alepha317.TRecord<string, alepha317.TAny>;
+      schemaHash: alepha317.TString;
+      status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+      activationDate: alepha317.TString;
+      expiredAt: alepha317.TOptional<alepha317.TString>;
+      version: alepha317.TInteger;
+      changeDescription: alepha317.TOptional<alepha317.TString>;
+      tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+      previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+      migrationLog: alepha317.TOptional<alepha317.TString>;
+    }>;
+  }>;
+  /**
+   * Rollback to a previous version.
+   */
+  rollback: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+    }>;
+    body: alepha317.TObject<{
+      targetVersion: alepha317.TInteger;
+      changeDescription: alepha317.TOptional<alepha317.TString>;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+    }>;
+    response: alepha317.TObject<{
+      id: alepha317.TString;
+      createdAt: alepha317.TString;
+      updatedAt: alepha317.TString;
+      name: alepha317.TString;
+      content: alepha317.TRecord<string, alepha317.TAny>;
+      schemaHash: alepha317.TString;
+      status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+      activationDate: alepha317.TString;
+      expiredAt: alepha317.TOptional<alepha317.TString>;
+      version: alepha317.TInteger;
+      changeDescription: alepha317.TOptional<alepha317.TString>;
+      tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+      previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+      migrationLog: alepha317.TOptional<alepha317.TString>;
+    }>;
+  }>;
+  /**
+   * Activate a scheduled version immediately.
+   */
+  activateNow: alepha_server0.ActionPrimitiveFn<{
+    params: alepha317.TObject<{
+      name: alepha317.TString;
+    }>;
+    body: alepha317.TObject<{
+      version: alepha317.TInteger;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+    }>;
+    response: alepha317.TObject<{
+      id: alepha317.TString;
+      createdAt: alepha317.TString;
+      updatedAt: alepha317.TString;
+      name: alepha317.TString;
+      content: alepha317.TRecord<string, alepha317.TAny>;
+      schemaHash: alepha317.TString;
+      status: alepha317.TUnsafe<"expired" | "current" | "next" | "future">;
+      activationDate: alepha317.TString;
+      expiredAt: alepha317.TOptional<alepha317.TString>;
+      version: alepha317.TInteger;
+      changeDescription: alepha317.TOptional<alepha317.TString>;
+      tags: alepha317.TOptional<alepha317.TArray<alepha317.TString>>;
+      creatorId: alepha317.TOptional<alepha317.TString>;
+      creatorName: alepha317.TOptional<alepha317.TString>;
+      previousContent: alepha317.TOptional<alepha317.TRecord<string, alepha317.TAny>>;
+      migrationLog: alepha317.TOptional<alepha317.TString>;
+    }>;
+  }>;
+  /**
+   * Trigger activation check for all scheduled configs.
+   * Normally called by a scheduler, but exposed for manual triggering.
+   */
+  checkScheduled: alepha_server0.ActionPrimitiveFn<{
+    response: alepha317.TObject<{
+      message: alepha317.TString;
+    }>;
+  }>;
+}
+//#endregion
+//#region ../../src/api-parameters/schedulers/ConfigActivationScheduler.d.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.
+ */
+declare class ConfigActivationScheduler {
+  protected readonly log: alepha_logger1.Logger;
+  protected readonly store: ConfigStore;
+  /**
+   * Check for scheduled configurations every minute.
+   */
+  checkActivations: alepha_scheduler0.SchedulerPrimitive;
 }
-declare const $config: <T extends TObject>(options: ConfigPrimitiveOptions<T>) => ConfigPrimitive<T>;
 //#endregion
 //#region ../../src/api-parameters/index.d.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
  */
-declare const AlephaApiParameters: alepha1.Service<alepha1.Module>;
+declare const AlephaApiParameters: alepha317.Service<alepha317.Module>;
 //#endregion
-export { $config, AlephaApiParameters, ConfigPrimitive, ConfigPrimitiveOptions, ParameterEntity, parameters };
+export { $config, AlephaApiParameters, ConfigActivationScheduler, ConfigController, ConfigPrimitive, ConfigPrimitiveOptions, ConfigStore, ConfigSyncPayload, ConfigTreeNode, Parameter, ParameterInsert, ParameterStatus, SaveConfigOptions, SetConfigOptions, parameters };
 //# sourceMappingURL=index.d.ts.map