@forinda/kickjs 5.16.0 → 5.18.0-alpha.0

package/dist/index-frSEHiL_.d.mts

@@ -1,796 +0,0 @@
-
-import { s as InjectionToken, t as Container } from "./container-TWOUyR_0.mjs";
-import { r as ExecutionContext } from "./execution-context-B4cfhivz.mjs";
-import { t as AnyContributorRegistration } from "./context-decorator-DDZ30BIW.mjs";
-import { r as AppAdapter } from "./adapter-CkpcZwzZ.mjs";
-import { r as AppModuleEntry, t as AppModule } from "./app-module-BTzb-Vd6.mjs";
-import { t as KickPlugin } from "./plugin-BQCn6zyj.mjs";
-//#region src/core/define-plugin.d.ts
-/**
- * Options passed to {@link definePlugin}. Mirrors the spec in
- * `architecture.md` §21.3.1 + §21.2.2 (Phase A "lite").
- */
-interface DefinePluginOptions<TConfig> {
-  /** Stable identity used for logging, `dependsOn` lookups, and `.scoped()` namespacing. */
-  name: string;
-  /** Optional plugin version — surfaced to DevTools and `kick add` compatibility checks (Phase B). */
-  version?: string;
-  /**
-   * Peer-version ranges this plugin needs from the framework or other
-   * plugins. Recorded as metadata; runtime enforcement lands in §21.4.4.
-   */
-  requires?: {
-    kickjs?: string;
-  };
-  /** Default config merged under any caller overrides. */
-  defaults?: Partial<TConfig>;
-  /** Builds the underlying {@link KickPlugin} from the resolved config. */
-  build(config: TConfig, ctx: BuildContext): Omit<KickPlugin, 'name'>;
-}
-/**
- * Hook context handed to a plugin/adapter `build` function. `name` is the
- * resolved instance name (the bare definition name for the bare call,
- * or `${defName}:${scope}` for `.scoped()`). `scoped` is the discriminator
- * authors use to namespace DI tokens or resource keys.
- */
-interface BuildContext {
-  name: string;
-  scoped: boolean;
-}
-/**
- * Async-config form of a plugin or adapter — `inject` lists DI tokens to
- * resolve from the container, then `useFactory` produces the config.
- *
- * Plugins resolve this lazily inside `onReady`, so any module/adapter/
- * middleware/contributor a plugin contributes via `build` is **not
- * available** when `.async()` is used. Use the bare/`.scoped()` form for
- * plugins that need to register modules or middleware.
- */
-interface PluginAsyncOptions<TConfig> {
-  inject?: ReadonlyArray<unknown>;
-  useFactory(...deps: any[]): TConfig | Promise<TConfig>;
-}
-/**
- * Factory returned by {@link definePlugin}. Callable form is the singleton
- * (`AuthPlugin(config)`); `.scoped()` and `.async()` are the multi-instance
- * and deferred-config forms.
- */
-interface PluginFactory<TConfig> {
-  (config?: Partial<TConfig>): KickPlugin;
-  scoped(scopeName: string, config?: Partial<TConfig>): KickPlugin;
-  async(opts: PluginAsyncOptions<TConfig>): KickPlugin;
-  /** Read-only access to the original definition — useful for DevTools introspection. */
-  readonly definition: Readonly<DefinePluginOptions<TConfig>>;
-}
-/**
- * Build a {@link KickPlugin} factory from a typed definition. See
- * `architecture.md` §21.2.2 for the design rationale.
- *
- * @example
- * ```ts
- * const FlagsPlugin = definePlugin<FlagsConfig>({
- *   name: 'FlagsPlugin',
- *   defaults: { defaultTtl: 60_000 },
- *   build(config) {
- *     return {
- *       register(container) {
- *         container.registerInstance(FLAGS, makeProvider(config))
- *       },
- *     }
- *   },
- * })
- *
- * bootstrap({ plugins: [FlagsPlugin({ provider: launchDarkly })] })
- * ```
- */
-declare function definePlugin<TConfig = Record<string, unknown>>(options: DefinePluginOptions<TConfig>): PluginFactory<TConfig>;
-//#endregion
-//#region src/core/define-module.d.ts
-/**
- * Options passed to {@link defineModule}. Mirrors {@link DefineAdapterOptions}
- * and {@link DefinePluginOptions} so adopters learn one mental model
- * across all three primitives.
- *
- * The optional `TExtra` generic lets a module ship public methods
- * beyond the standard {@link AppModule} contract — they're preserved
- * on the returned module instance so external callers (tests, sibling
- * modules) can invoke them directly.
- */
-interface DefineModuleOptions<TConfig, TExtra = unknown> {
-  /**
-   * Stable identity surfaced in diagnostics, route logs, and
-   * `.scoped()` namespacing. Required because boot-time error
-   * messages reference modules by name — anonymous modules make
-   * cycles + missing-dep errors hard to localize.
-   */
-  name: string;
-  /** Optional version string surfaced in diagnostics. */
-  version?: string;
-  /**
-   * Optional kickjs version constraint. Enforced by the framework
-   * when implemented; today it lives on the definition for
-   * documentation and forward compatibility.
-   */
-  requires?: {
-    kickjs?: string;
-  };
-  /**
-   * Default config merged with overrides at instantiation time
-   * (`MyModule({ field: x })`). Call-site overrides win.
-   */
-  defaults?: Partial<TConfig>;
-  /**
-   * Build the AppModule shape from the resolved config and context.
-   * `ctx.name` is the resolved instance name (the bare definition
-   * name for the default call, or `${name}:${scope}` for
-   * `.scoped()`); `ctx.scoped` discriminates so the build function
-   * can branch on namespacing if needed.
-   *
-   * Return any extension methods alongside the standard
-   * {@link AppModule} surface — they're typed via `TExtra` and stay
-   * accessible on the resulting instance.
-   */
-  build(config: TConfig, ctx: BuildContext): AppModule & TExtra;
-}
-/**
- * Factory returned by {@link defineModule}. Mirrors {@link AdapterFactory}
- * — call (`MyModule({...})`), scope (`MyModule.scoped('public', {...})`),
- * inspect (`MyModule.definition`).
- *
- * `.async()` is intentionally **not** part of the module factory
- * surface. Module config has no async-resolution window: `register()`
- * and `routes()` both run synchronously during bootstrap, before any
- * adapter `beforeStart` hook fires. Adopters that need async-resolved
- * config push it into an adapter (which has `beforeStart`), then
- * inject the resolved value into the module via DI tokens.
- */
-interface ModuleFactory<TConfig, TExtra = unknown> {
-  (config?: Partial<TConfig>): AppModule & TExtra;
-  scoped(scopeName: string, config?: Partial<TConfig>): AppModule & TExtra;
-  readonly definition: Readonly<DefineModuleOptions<TConfig, TExtra>>;
-}
-/**
- * Build an {@link AppModule} factory from a typed definition. Pairs
- * with {@link defineAdapter}, {@link definePlugin}, and
- * {@link defineContextDecorator} as the fourth `define*` primitive
- * — adopters write modules the same way they write adapters and
- * plugins.
- *
- * The returned factory produces real {@link AppModule} instances
- * that drop into `bootstrap({ modules })` directly. The legacy
- * class form (`class TasksModule implements AppModule { ... }`) keeps
- * working — `bootstrap` accepts either shape.
- *
- * @example
- * ```ts
- * interface TasksConfig {
- *   scope: 'public' | 'admin'
- * }
- *
- * const TasksModule = defineModule<TasksConfig>({
- *   name: 'TasksModule',
- *   defaults: { scope: 'public' },
- *   build: (config, { name }) => ({
- *     register(container) {
- *       container.registerInstance(`tasks:scope:${name}`, config.scope)
- *     },
- *     routes() {
- *       return { path: `/${config.scope}/tasks`, router: buildTasksRouter() }
- *     },
- *     contributors() {
- *       return [LoadTenant.registration]
- *     },
- *   }),
- * })
- *
- * bootstrap({
- *   modules: [
- *     TasksModule(),                              // public scope (defaults)
- *     TasksModule.scoped('admin', { scope: 'admin' }),
- *   ],
- * })
- * ```
- */
-declare function defineModule<TConfig = Record<string, unknown>, TExtra = unknown>(options: DefineModuleOptions<TConfig, TExtra>): ModuleFactory<TConfig, TExtra>;
-//#endregion
-//#region src/core/define-modules.d.ts
-/**
- * Chainable registry returned by {@link defineModules}. Extends
- * `Array<AppModuleEntry>` so it drops into `bootstrap({ modules })`
- * unchanged — the framework loader already iterates the array, so a
- * `ModuleList` IS a valid `modules` value with no special handling.
- *
- * The added affordance is `.mount(module)` returning `this` so
- * adopters can build the list fluently:
- *
- * ```ts
- * const modules = defineModules()
- *   .mount(HelloModule())
- *   .mount(AdminModule())
- *
- * bootstrap({ modules })
- * ```
- *
- * **Why not just use a plain array?** Two reasons. First, the
- * fluent shape reads more naturally for module-list construction —
- * adopters used to `definePlugin().scoped(...)` / `defineAdapter(...)`
- * see the same call-then-call pattern. Second, the registry is the
- * stable extension point: a future `.use(module)` for non-HTTP
- * modules (queues, cron, workers) lands as a method on `ModuleList`
- * without breaking the `Array<AppModuleEntry>` superclass contract.
- */
-declare class ModuleList extends Array<AppModuleEntry> {
-  /**
-   * Append a module to the list. Returns `this` for chaining.
-   *
-   * Accepts both class form (`SomeModule extends AppModule`) and
-   * `defineModule` factory output — same as the underlying
-   * `bootstrap({ modules })` array. The framework loader
-   * discriminates `typeof entry === 'function'` at boot.
-   */
-  mount(module: AppModuleEntry): this;
-}
-/**
- * Build a {@link ModuleList} for the application. Optional vararg
- * lets adopters seed the list inline; subsequent `.mount()` calls
- * append.
- *
- * @example
- * ```ts
- * import { bootstrap, defineModules } from '@forinda/kickjs'
- * import { HelloModule } from './modules/hello/hello.module'
- * import { AdminModule } from './modules/admin/admin.module'
- *
- * // Fluent — most common
- * const modules = defineModules()
- *   .mount(HelloModule())
- *   .mount(AdminModule())
- *
- * // Or seeded inline + chained
- * const modules2 = defineModules(HelloModule()).mount(AdminModule())
- *
- * await bootstrap({ modules })
- * ```
- *
- * The returned value is an `AppModuleEntry[]` subclass — `bootstrap`
- * accepts it directly without any special-casing. For conditional /
- * dynamic registration at bootstrap time (env flags, runtime config,
- * tenant lists), use the `setup(registry)` callback on `bootstrap`
- * instead — both surfaces compose.
- */
-declare function defineModules(...initial: AppModuleEntry[]): ModuleList;
-//#endregion
-//#region src/core/kick-error.d.ts
-/**
- * Structured framework error with code, cause, and actionable fix hint.
- *
- * The goal is "the developer who hits this knows what to do next." A
- * cryptic `Error('No binding found for: UserService')` becomes a
- * multi-line explanation pointing at the likely cause, the exact code
- * change to apply, and a docs link.
- *
- * `.message` carries the full multi-line plain-text body so Node's
- * default `Error.toString()` and unhandled-exception printing still
- * surface the helpful version. Call {@link formatKickError} to render a
- * colorized version for terminals.
- *
- * Per-error factories live in `kick-errors.ts` — those are the public
- * entry points framework code uses. `KickError` is exported so adopters
- * can build their own structured errors using the same shape.
- */
-interface KickErrorInit {
-  /** Short stable identifier (e.g. `KICK001`, `NO_PROVIDER`). */
-  code: string;
-  /** One-line headline. */
-  summary: string;
-  /** Multi-line explanation of why this happened. */
-  cause?: string;
-  /** Multi-line actionable fix — show exact code if possible. */
-  fix?: string;
-  /** Absolute URL to the docs page that covers this error. */
-  docsUrl?: string;
-  /** Arbitrary structured fields for log consumers / debug tooling. */
-  context?: Record<string, unknown>;
-}
-declare class KickError extends Error {
-  readonly code: string;
-  readonly summary: string;
-  readonly cause?: string;
-  readonly fix?: string;
-  readonly docsUrl?: string;
-  readonly context?: Record<string, unknown>;
-  constructor(init: KickErrorInit);
-}
-interface FormatKickErrorOptions {
-  /**
-   * Render ANSI colour codes. Defaults to TTY detection (`NO_COLOR` /
-   * `FORCE_COLOR` env vars honoured). Pass `false` for log files,
-   * structured loggers, or HTTP response bodies.
-   */
-  color?: boolean;
-}
-/**
- * Render a {@link KickErrorInit} (or {@link KickError} instance) into a
- * multi-line human-readable string. Identical layout regardless of
- * colour — the colour flag only toggles ANSI codes.
- */
-declare function formatKickError(err: KickErrorInit | KickError, options?: FormatKickErrorOptions): string;
-//#endregion
-//#region src/core/metadata.d.ts
-/**
- * Typed utilities for reflect-metadata operations.
- *
- * Replaces scattered Reflect.defineMetadata/getMetadata calls with a single
- * source of truth. If we later move to Stage 3 decorators or a WeakMap-based
- * store, only this file changes — all 24+ consumer files stay untouched.
- *
- * Keys may be symbols, strings, or `InjectionToken<T>` objects produced by
- * `createToken()`. Using `createToken` is the preferred pattern because the
- * token's phantom type flows through the helpers, enabling type-safe reads.
- */
-type MetaKey = symbol | string | InjectionToken<unknown>;
-/** Set metadata on a class (or prototype for property decorators) */
-declare function setClassMeta<T>(key: MetaKey, value: T, target: object): void;
-/** Set metadata on a specific method */
-declare function setMethodMeta<T>(key: MetaKey, value: T, target: object, method: string): void;
-/** Get metadata from a class, returning `fallback` if not set */
-declare function getClassMeta<T>(key: MetaKey, target: object, fallback: T): T;
-/** Get metadata from a specific method, returning `fallback` if not set */
-declare function getMethodMeta<T>(key: MetaKey, target: object, method: string, fallback: T): T;
-/** Check if metadata exists on a class */
-declare function hasClassMeta(key: MetaKey, target: object): boolean;
-/** Get metadata from a class with no default (returns undefined if absent) */
-declare function getClassMetaOrUndefined<T>(key: MetaKey, target: object): T | undefined;
-/** Get metadata from a method with no default (returns undefined if absent) */
-declare function getMethodMetaOrUndefined<T>(key: MetaKey, target: object, method: string): T | undefined;
-/** Append items to an array stored in class metadata */
-declare function pushClassMeta<T>(key: MetaKey, target: object, ...items: T[]): void;
-/** Append items to an array stored in method metadata */
-declare function pushMethodMeta<T>(key: MetaKey, target: object, method: string, ...items: T[]): void;
-/** Set a key/value in a Map stored in class metadata */
-declare function setInMetaMap<K, V>(key: MetaKey, target: object, mapKey: K, mapValue: V): void;
-/** Get a Map from class metadata (returns empty Map if absent) */
-declare function getMetaMap<K, V>(key: MetaKey, target: object): Map<K, V>;
-/** Set a key/value in a Record stored in class metadata */
-declare function setInMetaRecord<V>(key: MetaKey, target: object, recKey: string | number, recValue: V): void;
-/** Get a Record from class metadata (returns empty object if absent) */
-declare function getMetaRecord<V>(key: MetaKey, target: object): Record<string | number, V>;
-//#endregion
-//#region src/core/circuit-breaker.d.ts
-/**
- * Circuit Breaker pattern for external service calls.
- *
- * Protects your application from cascading failures when downstream
- * services are unhealthy by short-circuiting requests after a
- * configurable failure threshold.
- *
- * @example
- * ```ts
- * const breaker = new CircuitBreaker('payment-api', {
- *   failureThreshold: 5,
- *   resetTimeout: 30_000,
- * })
- *
- * const result = await breaker.execute(() => fetch('https://payment.example.com/charge'))
- * ```
- */
-type CircuitBreakerState = 'closed' | 'open' | 'half_open';
-interface CircuitBreakerOptions {
-  /** Number of consecutive failures before the circuit opens. */
-  failureThreshold: number;
-  /** Milliseconds to wait before transitioning from OPEN to HALF_OPEN. */
-  resetTimeout: number;
-  /** Max requests allowed in HALF_OPEN state before deciding (default 1). */
-  halfOpenMax?: number;
-}
-interface CircuitBreakerStats {
-  failures: number;
-  successes: number;
-  state: CircuitBreakerState;
-  lastFailure?: Date;
-}
-/**
- * Error thrown when the circuit is open and calls are being rejected.
- */
-declare class CircuitOpenError extends Error {
-  readonly breakerName: string;
-  constructor(breakerName: string);
-}
-declare class CircuitBreaker {
-  readonly name: string;
-  private state;
-  private failures;
-  private successes;
-  private halfOpenAttempts;
-  private lastFailure?;
-  private openedAt?;
-  private readonly failureThreshold;
-  private readonly resetTimeout;
-  private readonly halfOpenMax;
-  constructor(name: string, options: CircuitBreakerOptions);
-  /**
-   * Execute an async function through the circuit breaker.
-   * Throws `CircuitOpenError` if the circuit is open.
-   */
-  execute<T>(fn: () => Promise<T>): Promise<T>;
-  /** Returns the current circuit state. */
-  getState(): CircuitBreakerState;
-  /** Returns current statistics. */
-  getStats(): CircuitBreakerStats;
-  /** Manually reset the circuit breaker to CLOSED state. */
-  reset(): void;
-  private onSuccess;
-  private onFailure;
-  private maybeTransitionToHalfOpen;
-}
-//#endregion
-//#region src/core/context-errors.d.ts
-/**
- * Errors thrown by the Context Contributor pipeline.
- *
- * All three are startup-time errors raised during pipeline build (topo-sort
- * + validation), not per-request — a misconfigured app fails to boot rather
- * than fails a request. Per the locked design in `architecture.md` §20.4,
- * the pipeline is validated once when each route is mounted and the
- * resolved order is cached on the route.
- */
-/**
- * A contributor declared `dependsOn: ['<key>']` but no other contributor
- * (at any precedence level) produces that key for the same route.
- *
- * @example
- * ```text
- * MissingContributorError: Missing context contributor 'tenant' required by 'project' on route GET /projects/:id
- *     declared at src/contributors/load-project.ts:42:18
- * ```
- */
-declare class MissingContributorError extends Error {
-  readonly key: string;
-  readonly dependent: string;
-  readonly route?: string;
-  readonly dependentDefinedAt?: string;
-  constructor(key: string, dependent: string, route?: string, dependentDefinedAt?: string);
-}
-/**
- * Topo-sort detected a cycle in `dependsOn` declarations. The `cycle` field
- * lists the keys in the order they form the loop, with the first key
- * repeated at the end so the path reads naturally.
- *
- * @example
- * ```text
- * ContributorCycleError: Cycle in context contributors on route GET /projects/:id: tenant → project → tenant
- * ```
- */
-declare class ContributorCycleError extends Error {
-  readonly cycle: readonly string[];
-  readonly route?: string;
-  constructor(cycle: readonly string[], route?: string);
-}
-/**
- * Two contributors at the same precedence level both produce the same key
- * for the same route. Precedence resolution (method > class > module >
- * adapter > global, per architecture.md §20.4) silently drops
- * lower-precedence duplicates; this error fires only when ties occur
- * within a single level — e.g., two method-level decorators declaring
- * `key: 'tenant'`.
- *
- * `sources` is best-effort identifying labels for each conflicting
- * registration (typically the decorator's call site or registering
- * module/adapter name).
- *
- * @example
- * ```text
- * DuplicateContributorError: Duplicate context contributor for key 'tenant' at the same precedence level. Sources: LoadTenantFromHeader, LoadTenantFromSubdomain
- * ```
- */
-declare class DuplicateContributorError extends Error {
-  readonly key: string;
-  readonly sources: readonly string[];
-  constructor(key: string, sources: readonly string[]);
-}
-//#endregion
-//#region src/core/contributor-pipeline.d.ts
-/**
- * Where a contributor was registered, ordered by precedence
- * (lower index wins). Mirrors `architecture.md` §20.4.
- *
- * Levels (highest → lowest precedence):
- * - `'method'` — `@LoadX` on a controller method.
- * - `'class'`  — `@LoadX` on a controller class.
- * - `'module'` — returned by `AppModule.contributors?()`. Per-module scope.
- * - `'adapter'` — returned by `AppAdapter.contributors?()`. Cross-cutting, applies
- *   to every module's routes.
- * - `'global'` — `ApplicationOptions.contributors`. App-wide default.
- */
-type ContributorSource = 'method' | 'class' | 'module' | 'adapter' | 'global';
-/**
- * Input row to {@link buildPipeline}. Pairs a registration with its origin
- * so dedup can apply the precedence rule and diagnostic errors can name
- * the offending site.
- *
- * `registration` is the type-erased {@link AnyContributorRegistration}
- * — the runner doesn't care about each registration's narrow `D` /
- * `Ctx` shape, and adopters frequently mix HTTP / transport-agnostic
- * contributors in the same `externalSources` / `contributors()`
- * array. The narrow generics from `defineContextDecorator` survive
- * at the *definition* site (where `resolve` is typed); they're erased
- * here so collections compose without `as any` casts.
- */
-interface SourcedRegistration {
-  registration: AnyContributorRegistration;
-  source: ContributorSource;
-  /** Human label surfaced in DuplicateContributorError messages. */
-  label?: string;
-}
-/**
- * Resolved, validated, topo-sorted pipeline ready for execution.
- *
- * `contributors` is in execution order — every entry's `dependsOn`
- * keys appear earlier. `keys` is the set of all keys this pipeline
- * produces; the runner uses it for fast existence checks and the
- * builder uses it for missing-dep validation.
- */
-interface ContributorPipeline {
-  readonly contributors: readonly AnyContributorRegistration[];
-  readonly keys: ReadonlySet<string>;
-}
-interface BuildPipelineOptions {
-  /** Optional route identifier surfaced in diagnostic errors (e.g., 'GET /projects/:id'). */
-  route?: string;
-}
-/**
- * Build, validate, and topo-sort a contributor pipeline.
- *
- * Pipeline:
- *
- * 1. Group sources by precedence (method > class > module > adapter > global).
- * 2. Within each precedence level, two contributors with the same `key`
- *    raise {@link DuplicateContributorError}.
- * 3. Across levels, the highest-precedence contributor wins each key
- *    (lower-precedence duplicates are silently dropped — that is the
- *    documented override mechanism, not an error).
- * 4. Every key referenced by `dependsOn` must be produced by the
- *    surviving set, otherwise {@link MissingContributorError}.
- * 5. Kahn's algorithm topo-sorts the survivors. Any nodes left after
- *    the queue drains form a cycle → {@link ContributorCycleError}
- *    with a reconstructed path.
- *
- * Pure function — no DI, no I/O. Safe to call once at startup per
- * route and cache the result.
- */
-declare function buildPipeline(sources: readonly SourcedRegistration[], options?: BuildPipelineOptions): ContributorPipeline;
-//#endregion
-//#region src/core/contributor-runner.d.ts
-interface RunContributorsOptions {
-  /** Pre-built, validated, topo-sorted pipeline. */
-  pipeline: ContributorPipeline;
-  /** The execution context contributors read from and write into. */
-  ctx: ExecutionContext;
-  /** DI container used to resolve declared `deps`. */
-  container: Container;
-}
-/**
- * Execute a built {@link ContributorPipeline} against an {@link ExecutionContext}.
- *
- * Sequential — one contributor at a time, in the topo order chosen at
- * pipeline-build time. Per `architecture.md` §20.10, V1 does not run
- * contributors in parallel even within the same topo level; that is a
- * V2 follow-up gated on profiling.
- *
- * ## Error matrix (architecture.md §20.9)
- *
- * | resolve outcome | optional | onError defined | runner behaviour                                 |
- * |-----------------|----------|-----------------|--------------------------------------------------|
- * | throws          | true     | —               | skip; `ctx.get(key)` remains undefined           |
- * | throws          | false    | yes             | call hook; returned value (if any) stored        |
- * | throws          | false    | no              | propagate the original error                     |
- * | hook throws     | —        | yes             | propagate the new error                          |
- * | hook returns    | —        | yes             | undefined/void → skip; value → `ctx.set(key, v)` |
- * | resolves        | —        | —               | `ctx.set(key, value)`                            |
- *
- * Container.resolve() throwing while building `deps` is treated as a
- * resolve-side throw and flows through the same matrix — adopters who
- * need different behaviour for missing-DI vs. data-lookup failures can
- * wrap the container access inside their own `resolve()`.
- */
-declare function runContributors(options: RunContributorsOptions): Promise<void>;
-//#endregion
-//#region src/core/mount-sort.d.ts
-/**
- * Topological sort for plugins and adapters with `dependsOn` declarations.
- *
- * Mirrors the algorithm used by the Context Contributor pipeline
- * (`contributor-pipeline.ts:topoSort`) but operates on a name-keyed
- * `MountSortItem` shape rather than a `ContributorRegistration`. Kept
- * standalone instead of factored generic so that:
- *
- * 1. The contributor pipeline doesn't need refactoring (risk reduction).
- * 2. The error classes can carry plugin/adapter-specific diagnostic
- *    fields (`kind`, `dependent`) without bending the contributor types.
- */
-/**
- * A plugin or adapter that participates in dependency-ordered mounting.
- * Both `KickPlugin` and `AppAdapter` satisfy this shape via their `name`
- * and `dependsOn` fields.
- */
-interface MountSortItem {
-  /** Unique mount name within the plugin/adapter set being sorted. */
-  name: string;
-  /**
-   * Other plugin/adapter names that must mount before this one. Cycles
-   * and missing names fail at boot — same fail-fast contract as the
-   * Context Contributor pipeline (architecture.md §20.4).
-   */
-  dependsOn?: readonly string[];
-}
-/** What kind of mount set the sort is operating on — surfaces in error messages. */
-type MountKind = 'plugin' | 'adapter';
-/**
- * Two items in the same mount set declared the same `name`. Plugin/adapter
- * names must be unique so `dependsOn` references resolve unambiguously.
- */
-declare class DuplicateMountNameError extends Error {
-  readonly kind: MountKind;
-  readonly mountName: string;
-  constructor(kind: MountKind, mountName: string);
-}
-/**
- * A `dependsOn` entry references a plugin/adapter that isn't in the
- * current set. The dependency might not be installed, might be misspelled,
- * or might live in a different mount set (plugin referencing an adapter,
- * or vice versa — they sort independently).
- */
-declare class MissingMountDepError extends Error {
-  readonly kind: MountKind;
-  readonly missing: string;
-  readonly dependent: string;
-  constructor(kind: MountKind, missing: string, dependent: string);
-}
-/**
- * The `dependsOn` declarations form a cycle. Boot fails so the cycle
- * can't poison live traffic. The `cycle` field reports one path through
- * the offending nodes for diagnostics — formatted `A → B → C → A`.
- */
-declare class MountCycleError extends Error {
-  readonly kind: MountKind;
-  readonly cycle: readonly string[];
-  constructor(kind: MountKind, cycle: readonly string[]);
-}
-/**
- * Topologically sort `items` so every item with `dependsOn: ['X']` mounts
- * after `X`. Items without `dependsOn` keep their input order via Kahn's
- * algorithm with a FIFO queue seeded in input order — preserves the
- * historical "plugins/adapters mount in declaration order" behaviour for
- * any set that doesn't use `dependsOn`.
- *
- * @param items - mountable items, e.g. plugins or adapters
- * @param kind - 'plugin' | 'adapter', used in error messages
- * @returns a new array in valid mount order
- * @throws {DuplicateMountNameError} two items share a name
- * @throws {MissingMountDepError} a `dependsOn` references an unknown name
- * @throws {MountCycleError} the dep graph contains a cycle
- */
-declare function mountSort<T extends MountSortItem>(items: readonly T[], kind: MountKind): T[];
-//#endregion
-//#region src/core/define-adapter.d.ts
-/**
- * Options passed to {@link defineAdapter}. Mirrors {@link DefinePluginOptions}
- * exactly — see `architecture.md` §21.3.4 for the definePlugin/defineAdapter
- * symmetry rationale.
- *
- * The optional `TExtra` generic lets an adapter ship public methods
- * beyond the standard {@link AppAdapter} contract — they're preserved
- * on the returned adapter instance so external callers (tests, peer
- * adapters) can invoke them directly. See `OtelAdapter.applyRedaction`
- * for the canonical use case.
- */
-interface DefineAdapterOptions<TConfig, TExtra = unknown> {
-  /**
-   * Stable identity used for logging, `dependsOn` lookups, and `.scoped()`
-   * namespacing. Required for adapters that participate in `dependsOn`
-   * sort — error messages reference adapters by name.
-   */
-  name: string;
-  version?: string;
-  requires?: {
-    kickjs?: string;
-  };
-  defaults?: Partial<TConfig>;
-  build(config: TConfig, ctx: BuildContext): Omit<AppAdapter, 'name'> & TExtra;
-}
-/**
- * Async-config form of an adapter. Identical shape to `PluginAsyncOptions`
- * but resolved during `beforeStart` (the earliest async hook in
- * `AppAdapter`) — meaning `middleware()` and `contributors()` from the inner
- * adapter are **not** picked up. Use the bare/`.scoped()` form when you need
- * those.
- */
-interface AdapterAsyncOptions<TConfig> {
-  inject?: ReadonlyArray<unknown>;
-  useFactory(...deps: any[]): TConfig | Promise<TConfig>;
-}
-/**
- * Factory returned by {@link defineAdapter}. Same surface as
- * {@link PluginFactory} (call / `.scoped()` / `.async()`) so adopters learn
- * one mental model for both primitives. Returned instances carry both
- * the standard {@link AppAdapter} contract and any `TExtra` extension
- * methods the `build` function exposed.
- */
-interface AdapterFactory<TConfig, TExtra = unknown> {
-  (config?: Partial<TConfig>): AppAdapter & TExtra;
-  scoped(scopeName: string, config?: Partial<TConfig>): AppAdapter & TExtra;
-  async(opts: AdapterAsyncOptions<TConfig>): AppAdapter;
-  readonly definition: Readonly<DefineAdapterOptions<TConfig, TExtra>>;
-}
-/**
- * Build an {@link AppAdapter} factory from a typed definition. See
- * `architecture.md` §21.3.4 for migration guidance — most first-party
- * adapter packages collapse to a single `defineAdapter()` call after this
- * lands.
- *
- * @example
- * ```ts
- * const TenantAdapter = defineAdapter<TenantConfig>({
- *   name: 'TenantAdapter',
- *   defaults: { strategy: 'header', required: true },
- *   build: (config) => ({
- *     middleware: () => [tenantResolverMiddleware(config)],
- *     beforeStart: ({ container }) => registerTenantFactory(container, config),
- *   }),
- * })
- *
- * bootstrap({
- *   adapters: [
- *     TenantAdapter({ strategy: 'subdomain' }),
- *     TenantAdapter.scoped('shard-eu', { headerName: 'x-eu-tenant' }),
- *   ],
- * })
- * ```
- */
-declare function defineAdapter<TConfig = Record<string, unknown>, TExtra = unknown>(options: DefineAdapterOptions<TConfig, TExtra>): AdapterFactory<TConfig, TExtra>;
-//#endregion
-//#region src/core/asset-keys.d.ts
-type AssetKeyStrategy = 'auto' | 'strip' | 'with-extension';
-interface AssetKeyPair {
-  /** Source-relative path the file was discovered at. */
-  rel: string;
-  /** Final logical key for the manifest, including the namespace prefix. */
-  key: string;
-}
-interface GroupAssetKeysOptions {
-  /**
-   * Strategy applied to this namespace. Default `'auto'`.
-   *
-   * Adopters override per-namespace via `assetMap.<ns>.keys` in
-   * kick.config.ts when they want uniform behaviour (e.g. always
-   * include the extension regardless of collisions).
-   */
-  strategy?: AssetKeyStrategy;
-}
-interface GroupAssetKeysResult {
-  pairs: AssetKeyPair[];
-  /**
-   * Number of collision groups resolved by keeping extensions.
-   * Surfaces as an informational log ("auto-resolved N collisions")
-   * so adopters know whether they're relying on auto-mode or not.
-   * Always 0 for `'strip'` (overwrites) and `'with-extension'`
-   * (extensions always preserved, no collision possible).
-   */
-  collisionGroupsResolved: number;
-}
-/**
- * Compute final manifest keys for a namespace's discovered paths,
- * given the chosen strategy. Pure function — no fs / config / globals
- * involved.
- *
- * @param namespace assetMap key — e.g. `'mails'`, `'pages'`.
- * @param paths source-relative file paths (POSIX separators) discovered
- *              under the namespace's `src` directory.
- * @param opts grouping options.
- */
-declare function groupAssetKeys(namespace: string, paths: readonly string[], opts?: GroupAssetKeysOptions): GroupAssetKeysResult;
-/** Strip the final extension from a path. `'mails/welcome.ejs'` → `'mails/welcome'`. */
-declare function stripExt(path: string): string;
-//#endregion
-export { defineModule as $, CircuitBreakerStats as A, pushMethodMeta as B, buildPipeline as C, CircuitBreaker as D, MissingContributorError as E, getMetaRecord as F, FormatKickErrorOptions as G, setInMetaMap as H, getMethodMeta as I, formatKickError as J, KickError as K, getMethodMetaOrUndefined as L, getClassMeta as M, getClassMetaOrUndefined as N, CircuitBreakerOptions as O, getMetaMap as P, ModuleFactory as Q, hasClassMeta as R, SourcedRegistration as S, DuplicateContributorError as T, setInMetaRecord as U, setClassMeta as V, setMethodMeta as W, defineModules as X, ModuleList as Y, DefineModuleOptions as Z, RunContributorsOptions as _, groupAssetKeys as a, ContributorPipeline as b, AdapterFactory as c, DuplicateMountNameError as d, BuildContext as et, MissingMountDepError as f, mountSort as g, MountSortItem as h, GroupAssetKeysResult as i, definePlugin as it, CircuitOpenError as j, CircuitBreakerState as k, DefineAdapterOptions as l, MountKind as m, AssetKeyStrategy as n, PluginAsyncOptions as nt, stripExt as o, MountCycleError as p, KickErrorInit as q, GroupAssetKeysOptions as r, PluginFactory as rt, AdapterAsyncOptions as s, AssetKeyPair as t, DefinePluginOptions as tt, defineAdapter as u, runContributors as v, ContributorCycleError as w, ContributorSource as x, BuildPipelineOptions as y, pushClassMeta as z };
-//# sourceMappingURL=index-frSEHiL_.d.mts.map