/**
 * Scoped-config shared vokabulár (BFR-AM-004). Egy fájlban a szorosan összetartozó típusok
 * (a `*.interface.ts` az egy-export-per-file konvenció ismert kivétele — mint a FAM `fam-config.interface.ts`).
 *
 * **Domain-agnosztikus:** a bedrock CSAK a generikus resolve-precedencia engine-t + a tárolást adja;
 * a konkrét kulcs-katalógus, a kulcs-típusok és a default-ok a fogyasztó projekté (pl. FAM
 * `CONFIG_CATALOG`). Ezért a `value` itt `unknown`, a `key` `string`, és a `builtinDefault`-ot a
 * hívó adja át (nincs beépített katalógus).
 */

/**
 * Egy scoped-config érték generikus típusa. A típushelyesség a FOGYASZTÓ felelőssége (a bedrock nem
 * validál séma-szinten — a `value` Mongoose `Mixed`). A `null` megengedett (pl. "nincs plafon").
 */
export type DyNTS_ScopedConfigValue =
  number | string | boolean | string[] | null | { [key: string]: unknown };

/**
 * A precedencia-feloldás forrás-szintje. A `resolve` ezt adja vissza, hogy a fogyasztó átlátható módon
 * tudja, **honnan** jön egy érték (`builtin` = a hívó által átadott `builtinDefault`).
 */
export type DyNTS_ScopedConfigResolvedFrom = 'scope' | 'table' | 'global' | 'builtin';

/**
 * Egy canonical scope-referencia a `scopePath`-ban (BFR-AM-004). A `scopeId` a logikai scope-azonosító
 * (a fogyasztó adja, pl. egy `FAM_Scope._id`); a feloldás a path **levéből** (utolsó elem) indul a
 * gyökér (első elem) felé — a legmélyebb találat nyer.
 */
export interface DyNTS_ScopedConfigScopeRef {
  /** A scope logikai azonosítója (a `DyNTS_ScopedConfig.scopeId`-vel egyezik). */
  scopeId: string;
}

/**
 * A `resolve(key, ctx)` / `resolveAll(ctx)` kontextusa (BFR-AM-004). A `table` + `scopePath` nélkül
 * csak a global + builtin szint értelmezett. A `scopePath` canonical formában érkezik (a fogyasztó
 * read/write-path-ja oldotta fel) — a config-engine nyers stringgel NEM dolgozik.
 */
export interface DyNTS_ScopedConfigResolveContext {
  /** Melyik logikai tár szintjén oldjuk fel (a table + scope ág; nélküle csak global+builtin). */
  table?: string;

  /** Canonical scope-lánc (gyökér→levél); a feloldás a **levéből** indul a gyökér felé. */
  scopePath?: DyNTS_ScopedConfigScopeRef[];
}

/**
 * Egy feloldott config-érték a forrás-szinttel (BFR-AM-004). Átlátható: jelzi, melyik szintről jött
 * az effektív érték + ki állította be (audit). A `builtin` esetén csak a `value` + `resolvedFrom` van.
 */
export interface DyNTS_ScopedConfigResolvedValue<T = DyNTS_ScopedConfigValue> {
  /** A feloldott effektív érték. */
  value: T;

  /** A forrás-szint (`scope`/`table`/`global`/`builtin`). */
  resolvedFrom: DyNTS_ScopedConfigResolvedFrom;

  /** Ha `resolvedFrom='scope'`, melyik scope-entitásról (a legmélyebb találat). */
  scopeId?: string;

  /** Ki/mi állította be (a forrás-rekordról; `builtin` esetén nincs). */
  setBy?: string;

  /** Beállítás-részlet (pl. preset-név / CLI-user), ha van. */
  setByDetail?: string;
}

/**
 * A `resolve(key, opts)` opciói (BFR-AM-004). A `builtinDefault` a hívó által átadott fallback —
 * ha egyik DB-szinten sincs érték, ezt adja vissza `resolvedFrom='builtin'`-nal (a bedrock nem
 * tart beépített katalógust). Ha nincs `builtinDefault` és nincs DB-érték, az érték `undefined`.
 */
export interface DyNTS_ScopedConfigResolveOptions<T = DyNTS_ScopedConfigValue> {
  /** Melyik logikai tár szintjén oldjuk fel (a table + scope ág). */
  table?: string;

  /** Canonical scope-lánc (gyökér→levél); a feloldás a **levéből** indul a gyökér felé. */
  scopePath?: DyNTS_ScopedConfigScopeRef[];

  /** A hívó által átadott builtin fallback (a katalógus a fogyasztóé). */
  builtinDefault?: T;
}

/**
 * A `set(level, key, value, opts)` opció-objektuma (BFR-AM-004). A `level`+`tableScope`+`scopeId` adja
 * a feloldási-kulcsot; az audit-mezők (`setBy`/`setByDetail`/`note`) a felülírás-history-hez.
 */
export interface DyNTS_ScopedConfigSetOptions {
  /** `level='table'|'scope'` esetén kötelező: melyik logikai tár. */
  tableScope?: string;

  /** `level='scope'` esetén kötelező: a scope-entitás logikai azonosítója. */
  scopeId?: string;

  /** Ki/mi állította be (audit; default `'system'`). */
  setBy?: string;

  /** Beállítás-részlet (pl. preset-név / CLI-user). */
  setByDetail?: string;

  /** Opcionális indoklás. */
  note?: string;

  /** A hibák / write-ok `issuer`-e. */
  issuer?: string;
}