/**
 * Per-model relation-cache middleware (ADR-012).
 *
 * A model may declare `cacheMiddlewarePrepare` / `cacheMiddlewareConsume` on its
 * `withResourceful` options. Whenever an instance of that model is cached as a 1:1
 * relation, the `prepare` pipeline runs over the snapshot just before it is encoded
 * and written, and the `consume` pipeline runs over the decoded snapshot just before
 * it is rehydrated — the symmetric inverse. Each is built into an `@nhtio/middleware`
 * chain-of-responsibility pipeline whose handlers mutate `context.value`.
 *
 * The middleware belongs to the related (cached) model, so whoever loads that model
 * through a cached relation transparently runs its middleware (e.g. field encryption).
 *
 * `@nhtio/middleware` is imported as a VALUE only; the public types below are local
 * (structural) so the package's bundled `.d.ts` surface does not pull in
 * `@nhtio/middleware`'s declarations.
 *
 * @module
 */
import type { LucidModel } from '@adonisjs/lucid/types/model';
/** Advances the cache-middleware chain to the next handler. */
export type CacheMiddlewareNext = () => Promise<unknown> | unknown;
/** The phase a cache-middleware pipeline runs in. */
export type CacheMiddlewarePhase = 'prepare' | 'consume';
/**
 * Mutable context threaded through a model's cache-middleware pipeline. Handlers
 * read the metadata and transform `value` in place (or reassign it).
 */
export interface CacheMiddlewareContext {
    /** `'prepare'` before writing to the cache, `'consume'` after reading from it. */
    readonly phase: CacheMiddlewarePhase;
    /** The (related) model whose snapshot is being cached. */
    readonly model: LucidModel;
    /** The relation name the snapshot is being cached under. */
    readonly relation: string;
    /** The canonical cache key. */
    readonly key: string;
    /** The snapshot under transformation; handlers mutate or replace this. */
    value: Record<string, unknown>;
}
/** A single cache-middleware handler (chain-of-responsibility; must call `next`). */
export type CacheMiddlewareHandler = (context: CacheMiddlewareContext, next: CacheMiddlewareNext) => void | Promise<void>;
/** User-supplied cache middleware: one handler or an ordered list of handlers. */
export type CacheMiddlewareInput = CacheMiddlewareHandler | CacheMiddlewareHandler[];
/** The runner returned by a {@link CacheMiddlewarePipeline}. */
export interface CacheMiddlewareRunner {
    run(executor: (handler: CacheMiddlewareHandler, next: CacheMiddlewareNext) => Promise<unknown>): Promise<void>;
}
/**
 * A built, reusable cache-middleware pipeline. Structurally a `@nhtio/middleware`
 * `Middleware`, but typed via this local interface so the package's public types do
 * NOT pull `@nhtio/middleware`'s declarations into the bundled `.d.ts` surface.
 */
export interface CacheMiddlewarePipeline {
    runner(): CacheMiddlewareRunner;
}
/**
 * Builds a reusable `@nhtio/middleware` pipeline from user-supplied handler(s).
 * Returns `null` when nothing is configured so callers can skip the run entirely.
 *
 * @param input - A single handler, an array of handlers, or undefined.
 * @returns The built pipeline, or `null` when there are no handlers.
 */
export declare const buildCacheMiddleware: (input?: CacheMiddlewareInput) => CacheMiddlewarePipeline | null;
/**
 * Runs a model's cache-middleware pipeline over a snapshot and returns the
 * (possibly transformed) value. A `null` pipeline is a no-op passthrough.
 *
 * @param pipeline - The pre-built pipeline (or `null` when the model declares none).
 * @param context - The mutable context handed to each handler.
 * @returns The transformed snapshot (`context.value`).
 */
export declare const runCacheMiddleware: (pipeline: CacheMiddlewarePipeline | null, context: CacheMiddlewareContext) => Promise<Record<string, unknown>>;