@opensaas/stack-core 0.37.0 → 0.39.0

package/src/config/nav-count.ts

@@ -13,13 +13,12 @@ type CountDelegate = {
 
 /**
  * Whether a list's query access is **statically denied** — provably no session
- * can read any row without evaluating a session-dependent function.
+ * can read any row, without evaluating a session-dependent function.
  *
- * Mirrors the list view's `canDeleteList` static check (issue #733): query
- * access is statically denied when it is absent (deny-by-default, matching the
- * access engine) or the literal boolean `false`. A function — or `true` —
- * cannot be decided up front, so the count is fetched through the secured
- * context, which re-applies the real rule per row.
+ * Mirrors the list view's `canDeleteList` static check (issue #733): absent
+ * access is deny-by-default (matching the access engine), so only an explicit
+ * `false` counts as statically denied here — a function or `true` falls
+ * through to a real per-row check via the secured context.
  *
  * A statically-denied list must render no nav count at all: a `0` there would
  * imply "this list is empty" when the truth is "you may see none of it".
@@ -35,20 +34,13 @@ export function isListQueryStaticallyDenied(
 }
 
 /**
- * Resolve the access-scoped nav counts for the lists that opt in via
- * `ui.navCount` (issue #735).
+ * Resolve the access-scoped nav counts for lists that opt in via
+ * `ui.navCount` (issue #735). A list gets an entry only if it opts in, isn't
+ * a singleton (no meaningful count), and isn't {@link isListQueryStaticallyDenied}
+ * — everything else is omitted from the map, never zeroed.
  *
- * The returned map is keyed by list key and contains an entry **only** for a
- * list that:
- *
- * 1. opts in (`ui.navCount === true`) — no count query runs for any other list,
- * 2. is not a singleton (a single-record list has no meaningful count), and
- * 3. does not have statically-denied query access (see
- *    {@link isListQueryStaticallyDenied}).
- *
- * Each count is read through the secured `context.db`, whose `count` applies the
- * access filter, so the number reflects exactly what the current session may
- * see (a denied row is not counted). Counts are fetched concurrently.
+ * Each count is read through the secured `context.db`, so it reflects
+ * exactly what the current session may see.
  */
 export async function resolveNavCounts(
   context: AccessContext,

package/src/config/plugin-engine.ts

@@ -8,17 +8,12 @@ import type {
   BaseFieldConfig,
 } from './types.js'
 
-/**
- * Topological sort for plugin dependency resolution
- * Ensures plugins execute in correct order based on dependencies
- */
 function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
   const pluginMap = new Map<string, Plugin>()
   const visited = new Set<string>()
   const visiting = new Set<string>()
   const sorted: Plugin[] = []
 
-  // Build plugin map
   for (const plugin of plugins) {
     if (pluginMap.has(plugin.name)) {
       throw new Error(`Duplicate plugin name: ${plugin.name}`)
@@ -42,7 +37,6 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
 
     visiting.add(pluginName)
 
-    // Visit dependencies first
     if (plugin.dependencies) {
       for (const dep of plugin.dependencies) {
         visit(dep, [...path, pluginName])
@@ -54,7 +48,6 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
     sorted.push(plugin)
   }
 
-  // Visit all plugins
   for (const plugin of plugins) {
     visit(plugin.name)
   }
@@ -62,17 +55,12 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
   return sorted
 }
 
-/**
- * Merge hooks from extension into existing hooks
- * Combines hook arrays so multiple plugins can add hooks
- */
 function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined): Hooks | undefined {
   if (!extension) return existing
   if (!existing) return extension
 
   const merged: Partial<Hooks> = {}
 
-  // Merge resolveInput hooks (chain them, passing resolvedData through)
   if (existing.resolveInput || extension.resolveInput) {
     if (existing.resolveInput && extension.resolveInput) {
       merged.resolveInput = async (args) => {
@@ -85,7 +73,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge validateInput hooks (run both)
   if (existing.validateInput || extension.validateInput) {
     if (existing.validateInput && extension.validateInput) {
       merged.validateInput = async (args) => {
@@ -97,7 +84,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge beforeOperation hooks (run both in sequence)
   if (existing.beforeOperation || extension.beforeOperation) {
     if (existing.beforeOperation && extension.beforeOperation) {
       merged.beforeOperation = async (args) => {
@@ -109,7 +95,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge afterOperation hooks (run both in sequence)
   if (existing.afterOperation || extension.afterOperation) {
     if (existing.afterOperation && extension.afterOperation) {
       merged.afterOperation = async (args) => {
@@ -124,33 +109,24 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
   return Object.keys(merged).length > 0 ? (merged as Hooks) : undefined
 }
 
-/**
- * Execute plugins and transform config
- * Returns modified config with plugin data attached
- */
 export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasConfig> {
   if (!config.plugins || config.plugins.length === 0) {
     return config
   }
 
-  // Sort plugins by dependencies
   const sortedPlugins = sortPluginsByDependencies(config.plugins)
 
-  // Initialize mutable config state - preserve all config properties
   let currentConfig: OpenSaasConfig = {
     ...config,
     lists: { ...config.lists }, // Clone lists object to avoid mutating original
     _pluginData: {},
   }
 
-  // Field type registry (for third-party fields)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Registry must accept any field config builder
   const fieldTypeRegistry = new Map<string, (options?: unknown) => BaseFieldConfig<any>>()
 
-  // MCP tools registry
   const mcpToolsRegistry: McpCustomTool[] = []
 
-  // Execute each plugin
   for (const plugin of sortedPlugins) {
     const context: PluginContext = {
       config: currentConfig,
@@ -186,16 +162,13 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
           )
         }
 
-        // Deep merge fields
         const mergedFields = {
           ...existing.fields,
           ...extension.fields,
         }
 
-        // Merge hooks
         const mergedHooks = mergeHooks(existing.hooks, extension.hooks)
 
-        // Merge MCP config
         const mergedMcp = extension.mcp
           ? {
               ...existing.mcp,
@@ -233,11 +206,9 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
       },
     }
 
-    // Execute plugin init
     await plugin.init(context)
   }
 
-  // Store registered MCP tools in config (if any)
   if (mcpToolsRegistry.length > 0) {
     if (!currentConfig._pluginData) {
       currentConfig._pluginData = {}
@@ -245,8 +216,7 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
     currentConfig._pluginData.__mcpTools = mcpToolsRegistry
   }
 
-  // Store plugin instances in config for runtime access
-  // This allows context creation to call plugin.runtime() functions
+  // Stored so context creation can call each plugin's runtime() function.
   if (!currentConfig._plugins) {
     currentConfig._plugins = []
   }
@@ -255,9 +225,6 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
   return currentConfig
 }
 
-/**
- * Execute beforeGenerate hooks from plugins
- */
 export async function executeBeforeGenerateHooks(config: OpenSaasConfig): Promise<OpenSaasConfig> {
   if (!config.plugins || config.plugins.length === 0) {
     return config
@@ -274,9 +241,6 @@ export async function executeBeforeGenerateHooks(config: OpenSaasConfig): Promis
   return currentConfig
 }
 
-/**
- * Execute afterGenerate hooks from plugins
- */
 export async function executeAfterGenerateHooks(
   config: OpenSaasConfig,
   files: { prismaSchema: string; types: string; context: string; [key: string]: string },

package/src/config/types.ts

@@ -2,9 +2,6 @@ import type { AccessControl, FieldAccess } from '../access/types.js'
 import type { FilterSpec } from '../filter/types.js'
 import type { z } from 'zod'
 
-/**
- * Field configuration types
- */
 export type FieldType =
   'text' | 'integer' | 'checkbox' | 'timestamp' | 'password' | 'select' | 'relationship' | string // Allow custom field types from third-party packages
 
@@ -12,10 +9,7 @@ export type FieldType =
  * Field-level hook argument types (exported for user annotations)
  */
 
-/**
- * Arguments for field-level resolveInput hook
- * Used to transform field values before database write
- */
+/** Arguments for {@link FieldHooks.resolveInput}. */
 export type FieldResolveInputHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -39,10 +33,7 @@ export type FieldResolveInputHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level validate hook
- * Used for custom validation logic
- */
+/** Arguments for {@link FieldHooks.validate} (and its deprecated `validateInput` alias). */
 export type FieldValidateHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -76,10 +67,7 @@ export type FieldValidateHookArgs<
       addValidationError: (msg: string) => void
     }
 
-/**
- * Arguments for field-level beforeOperation hook
- * Used for side effects before database write
- */
+/** Arguments for {@link FieldHooks.beforeOperation}. */
 export type FieldBeforeOperationHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -109,10 +97,7 @@ export type FieldBeforeOperationHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level afterOperation hook
- * Used for side effects after database operation
- */
+/** Arguments for {@link FieldHooks.afterOperation}. */
 export type FieldAfterOperationHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -263,10 +248,7 @@ export type FieldAfterTransactionHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level resolveOutput hook
- * Used to transform field values after database read
- */
+/** Arguments for {@link FieldHooks.resolveOutput}. */
 export type FieldResolveOutputHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -507,10 +489,10 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
   defaultValue?: unknown
   hooks?: FieldHooks<TTypeInfo>
   /**
-   * Marks this field as virtual - not stored in database
-   * Virtual fields use resolveInput/resolveOutput hooks for computation
-   * They are excluded from Prisma schema and input types
-   * Only computed when explicitly selected/included in queries
+   * Marks this field as virtual — not stored in database, computed via
+   * `resolveInput`/`resolveOutput` hooks, and excluded from the Prisma
+   * schema and input types. Computed whenever the read is going to return
+   * it (ADR-0027) — not gated behind an explicit `include`/selection.
    */
   virtual?: boolean
   /**
@@ -877,6 +859,25 @@ export type DecimalField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfi
   isIndexed?: boolean | 'unique'
 }
 
+/**
+ * 64-bit integer field (Prisma `BigInt`, TypeScript `bigint`) — for values that
+ * overflow `integer()`'s 32-bit `Int` (e.g. a millisecond epoch).
+ *
+ * Wire representation (ADR-0029): `bigint` in application code, a decimal
+ * string over MCP — `bigint` is not JSON-serialisable, so the MCP handler
+ * renders it as a string rather than throwing.
+ */
+export type BigIntField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
+  type: 'bigInt'
+  defaultValue?: bigint | number | string
+  validation?: {
+    isRequired?: boolean
+    min?: bigint
+    max?: bigint
+  }
+  isIndexed?: boolean | 'unique'
+}
+
 export type CheckboxField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'checkbox'
 }
@@ -1358,20 +1359,8 @@ export type VirtualField<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo
  */
 export type FieldConfig = BaseFieldConfig<TypeInfo>
 
-/**
- * List configuration types
- */
-
-/**
- * Utility type to inject TypeInfo into a single field config
- * Extracts TInput and TOutput from BaseFieldConfig and reconstructs with new TypeInfo
- */
 type WithTypeInfo<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo>
 
-/**
- * Utility type to transform all fields in a record to inject TypeInfo
- * Maps over each field and applies WithTypeInfo transformation
- */
 export type FieldsWithTypeInfo<TTypeInfo extends TypeInfo> = {
   [key: string]: WithTypeInfo<TTypeInfo>
 }
@@ -1547,8 +1536,7 @@ export type ListAccessControl<T = any> =
     }
 
 /**
- * Hook arguments for resolveInput hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `resolveInput` hook.
  * - create: resolvedData is CreateInput, item is undefined
  * - update: resolvedData is UpdateInput, item is the existing record
  */
@@ -1575,8 +1563,7 @@ export type ResolveInputHookArgs<
     }
 
 /**
- * Hook arguments for validate hook (renamed from validateInput for Keystone compatibility)
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `validate` hook (renamed from `validateInput` for Keystone compatibility).
  * - create: resolvedData is CreateInput, item is undefined
  * - update: resolvedData is UpdateInput, item is the existing record
  * - delete: item is the item being deleted
@@ -1613,8 +1600,7 @@ export type ValidateHookArgs<
     }
 
 /**
- * Hook arguments for beforeOperation hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `beforeOperation` hook.
  * - create: has inputData and resolvedData, no item
  * - update: has inputData, resolvedData, and item
  * - delete: has item only
@@ -1647,8 +1633,7 @@ export type BeforeOperationHookArgs<
     }
 
 /**
- * Hook arguments for afterOperation hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `afterOperation` hook.
  * - create: has item, inputData, and resolvedData, no originalItem
  * - update: has item, originalItem, inputData, and resolvedData
  * - delete: has originalItem only
@@ -1848,14 +1833,20 @@ export type ListIndexFieldRef =
     }
 
 /**
- * A model-level composite `@@unique`/`@@index` constraint spanning two or
- * more of a list's own fields. See {@link ListConfig.db}'s `indexes` for the
- * full explanation and examples (#864).
+ * A model-level `@@unique`/`@@index` constraint spanning one or more of a
+ * list's own fields. See {@link ListConfig.db}'s `indexes` for the full
+ * explanation and examples (#864, #918).
  */
 export type ListIndex = {
   /**
    * The fields participating in this index/constraint, in declaration order.
    * OpenSaaS field names, not raw database column names.
+   *
+   * One or more fields — a named single-column constraint is as legitimate
+   * as a composite one, and is the form to reach for when a live table's
+   * constraint carries a name Prisma wouldn't derive on its own. Field-level
+   * `isIndexed` remains the sugar for the unnamed single-column case; this
+   * is the full form when a name or a sort direction is needed.
    */
   fields: ListIndexFieldRef[]
   /**
@@ -1949,31 +1940,40 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
      */
     timestamps?: boolean
     /**
-     * Model-level composite `@@unique`/`@@index` constraints spanning two or
-     * more of this list's own fields (#864).
+     * Model-level `@@unique`/`@@index` constraints spanning one or more of
+     * this list's own fields (#864, #918). See the [reference
+     * docs](https://stack.opensaas.au/docs/reference/config-api#dbindexes)
+     * for the full explanation, arity, and error conditions.
      *
-     * Field-level `isIndexed` (on a scalar or relationship field) can only
-     * ever produce a single-column index — it has no way to express a
-     * constraint or index that spans more than one column. `db.indexes` is
-     * that multi-column case: each entry names two or more of the list's own
-     * OpenSaaS field names, not raw database column names. The generator
-     * resolves each to its underlying Prisma column — a scalar field's own
-     * name (its Prisma field name is unaffected by `db.map`), or a
-     * relationship field's foreign key column (`<field>Id`) when this side
-     * owns it.
+     * Field-level `isIndexed` (on a scalar or relationship field) is the
+     * sugar for the unnamed single-column case. `db.indexes` is the full
+     * form — reach for it when a constraint needs a `name` (Prisma's `map:`,
+     * for adopting an existing live constraint), a `sort` direction, or spans
+     * more than one column. Arity is incidental: each entry names one or
+     * more of the list's own OpenSaaS field names, not raw database column
+     * names. The generator resolves each to its underlying Prisma column — a
+     * scalar field's own name (its Prisma field name is unaffected by
+     * `db.map`), or a relationship field's foreign key column (`<field>Id`)
+     * when this side owns it.
      *
-     * A composite **unique** is the load-bearing case: it's the
-     * database-level backstop for a business rule two concurrent writes could
-     * otherwise both slip past (e.g. "one booking per student per
-     * production") — something a hook's existence check cannot close on its
-     * own, and can't be retrofitted once duplicate rows exist. A composite
-     * **index** (non-unique) is the equivalent performance-only case (a hot
-     * multi-column lookup path).
+     * A **unique** entry is the load-bearing case: it's the database-level
+     * backstop for a business rule concurrent writes could otherwise both
+     * slip past (e.g. "one booking per student per production", or a
+     * single-column unique a live table already enforces under a name Prisma
+     * wouldn't derive) — something a hook's existence check cannot close on
+     * its own, and can't be retrofitted once duplicate rows exist. An
+     * **index** (non-unique) entry is the equivalent performance-only case
+     * (a hot lookup path).
      *
-     * An entry naming a field the list doesn't have, a virtual field, a
-     * to-many relationship, or the non-FK side of a one-to-one relationship
-     * fails `pnpm generate` with an error naming the list, the entry, and the
-     * bad field — it is never silently dropped or emitted as invalid Prisma.
+     * Two conditions fail `pnpm generate` with an error naming the list and
+     * the entry: an empty `fields` array, and a single-field entry that
+     * indexes the exact column a field-level `isIndexed` on the same list
+     * already indexes (the error also names that field and its `isIndexed`
+     * value — one of the two should be removed). An entry naming a field the
+     * list doesn't have, a virtual field, a to-many relationship, or the
+     * non-FK side of a one-to-one relationship fails the same way, naming
+     * the bad field too — no entry is ever silently dropped or emitted as
+     * invalid Prisma.
      *
      * @example One audition per student per production (composite unique)
      * ```typescript
@@ -2007,12 +2007,22 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
      * })
      * // Generates: @@index([identifier, createdAt(sort: Desc)], map: "AuthVerification_identifier_createdAt_idx")
      * ```
+     *
+     * @example Naming a single-column unique constraint (adopting a live table's existing name)
+     * ```typescript
+     * RateLimit: list({
+     *   fields: { key: text() }, // no isIndexed here — db.indexes owns this column instead
+     *   db: {
+     *     indexes: [{ fields: ['key'], unique: true, name: 'RateLimit_key_key' }],
+     *   },
+     * })
+     * // Generates: @@unique([key], map: "RateLimit_key_key")
+     * // Setting key's own isIndexed too would duplicate this constraint and
+     * // fail generation — one of the two must own the column.
+     * ```
      */
     indexes?: ListIndex[]
   }
-  /**
-   * MCP server configuration for this list
-   */
   mcp?: ListMcpConfig
   /**
    * Restricts this list to a single record (singleton pattern)
@@ -2319,9 +2329,6 @@ export type ListConfigInput<TTypeInfo extends TypeInfo> = Omit<ListConfig<TTypeI
   access?: ListAccessControl<TTypeInfo['item']>
 }
 
-/**
- * Database configuration
- */
 export type DatabaseConfig = {
   provider: 'postgresql' | 'mysql' | 'sqlite'
   /**
@@ -2540,9 +2547,6 @@ export type DatabaseConfig = {
   }
 }
 
-/**
- * Session configuration
- */
 export type SessionConfig = {
   // Uses `any` return type because session structure is user-defined and varies per application
   // The stack doesn't enforce a specific session shape - users can use NextAuth, Clerk, etc.
@@ -2550,9 +2554,6 @@ export type SessionConfig = {
   getSession: () => Promise<any>
 }
 
-/**
- * Theme preset options
- */
 export type ThemePreset = 'modern' | 'classic' | 'neon'
 
 /**
@@ -2648,14 +2649,8 @@ export type ThemeConfig = {
   shadows?: ThemeShadows
 }
 
-/**
- * UI configuration
- */
 export type UIConfig = {
   basePath?: string
-  /**
-   * Theme configuration for the admin UI
-   */
   theme?: ThemeConfig
 }
 
@@ -2698,18 +2693,12 @@ export type McpCustomTool = {
    * Unique name for the tool
    */
   name: string
-  /**
-   * Description of what the tool does
-   */
   description: string
   /**
    * Input schema (Zod schema)
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   inputSchema: any
-  /**
-   * Handler function that executes the tool
-   */
   handler: (args: {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     input: any
@@ -2717,9 +2706,6 @@ export type McpCustomTool = {
   }) => Promise<unknown>
 }
 
-/**
- * List-level MCP configuration
- */
 export type ListMcpConfig = {
   /**
    * Enable MCP tools for this list
@@ -2790,9 +2776,6 @@ export type McpAuthConfig =
        * Authentication type - custom auth provider
        */
       type: string
-      /**
-       * Additional auth-specific configuration
-       */
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Allows custom auth provider configuration
       [key: string]: any
     }
@@ -2920,15 +2903,17 @@ export type PluginContext = {
 
   /**
    * Add a new list to the config
-   * Throws error if list already exists (unless merge strategy used)
+   * Throws error if list already exists
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Plugin API must accept any list config
   addList: (name: string, listConfig: ListConfig<any>) => void
 
   /**
-   * Extend an existing list with additional fields, hooks, or access control
-   * Deep merges fields, hooks, and access control
-   * Throws error if list doesn't exist
+   * Extend an existing list with additional fields, hooks, or MCP config.
+   * Merges fields, hooks, and MCP config. Throws if the list doesn't exist,
+   * or if the extension sets operation-level `access` — access control
+   * belongs to whoever created the list, never a plugin extending it
+   * (ADR-0013).
    */
   extendList: (
     name: string,
@@ -3047,10 +3032,6 @@ export type Plugin = {
   }
 }
 
-/**
- * Main configuration type
- * Using interface instead of type to allow module augmentation
- */
 /**
  * Configurable generator output locations.
  *
@@ -3112,6 +3093,10 @@ export interface OutputConfig {
   buildTarget?: 'node'
 }
 
+/**
+ * Main configuration type.
+ * Uses an interface, not a type alias, so it can be extended via module augmentation.
+ */
 export interface OpenSaasConfig {
   db: DatabaseConfig
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Config must accept any list configuration