import { n as StateEmbedder, l as SubspaceTrajectory, L as Logger, M as Middleware, V as VectorN, j as ManifoldProvider } from '../interfaces-BPfVSRPt.js';

interface GrassmannianMiddlewareOpts<S> {
    /** Embedder to convert state → vector. Same as kinematicsMiddleware. */
    embedder: StateEmbedder<S>;
    /**
     * Number of recent embeddings to keep in the sliding window.
     * The subspace is extracted from this window each step.
     * Larger windows = more stable subspace, slower to react.
     * Smaller windows = more responsive, noisier.
     * Default: 10.
     */
    windowSize?: number;
    /**
     * Number of principal components (subspace dimension k).
     * If omitted, auto-selects to explain ≥ 80% of variance.
     */
    subspaceDim?: number;
    /**
     * Optional reference trajectory for comparison.
     * If provided, the middleware compares the current subspace to
     * `trajectory.referenceAt(ctx.step)` each step and computes
     * geodesic distance, principal angles, and steering direction.
     *
     * If omitted, the middleware only extracts and reports the current
     * subspace (no comparison, no drift detection).
     */
    trajectory?: SubspaceTrajectory;
    /**
     * Geodesic distance threshold for drift detection.
     * When the distance to the reference subspace exceeds this value,
     * `isDrifting` is set to true.
     *
     * Only meaningful when `trajectory` is provided.
     * If omitted, drift detection is disabled (isDrifting always false).
     */
    driftThreshold?: number;
    /**
     * Action to take when drift is detected.
     * - `'warn'` — annotate `isDrifting: true` in metadata, do not halt (default)
     * - `'halt'` — return `'halt'` to stop the control loop
     */
    driftAction?: 'warn' | 'halt';
    /**
     * Whether to compute the log map (steering direction) when a reference
     * trajectory is provided. The log map gives the tangent vector pointing
     * from the current subspace toward the reference.
     *
     * Default: true (when trajectory is provided).
     * Set to false to save computation if you only need distance/angles.
     */
    computeSteering?: boolean;
    /** Optional logger for Grassmannian telemetry. */
    logger?: Logger;
}
/**
 * Advanced middleware that performs Grassmannian subspace tracking each step.
 *
 * It embeds the current state, maintains a sliding window of recent embeddings,
 * extracts a subspace via SVD, and optionally compares it to a reference
 * trajectory on the Grassmannian manifold.
 *
 * Writes `ctx.metadata['grassmannian']` with a `GrassmannianSnapshot` containing:
 * - Current subspace basis and extraction quality
 * - Principal angles and geodesic distance to reference (if trajectory provided)
 * - Steering direction via log map (if enabled)
 * - Drift detection (if threshold configured)
 *
 * **Ordering:** Can be stacked independently of `kinematicsMiddleware` and
 * `manifoldMiddleware`. They observe different things and write to different
 * metadata channels.
 */
declare function grassmannianMiddleware<S>(opts: GrassmannianMiddlewareOpts<S>): Middleware<S>;

/**
 * Kinematics data attached to `ctx.metadata['kinematics']` each step.
 */
interface KinematicsSnapshot {
    position: VectorN;
    velocity: VectorN;
    error: VectorN;
    errorMagnitude: number;
    correctionMagnitude: number;
    coherenceAngleDeg: number;
    isStable: boolean;
    stepIndex: number;
}
/**
 * Correction info attached to `ctx.metadata['kinematicsCorrection']` when drift is detected.
 */
interface CorrectionInfo {
    vector: VectorN;
    magnitude: number;
    log: string;
}
interface KinematicsMiddlewareOpts<S> {
    /** Embedder to convert state → vector. */
    embedder: StateEmbedder<S>;
    /** Goal embedding vector (used as origin for physics). */
    goalEmbedding: number[];
    /** PID controller parameters. */
    pid?: {
        Kp?: number;
        Ki?: number;
        Kd?: number;
        stabilityThreshold?: number;
    };
    /** Physics engine (EKF) parameters. */
    physics?: {
        processNoise?: number;
        measureNoise?: number;
    };
    /**
     * v3.0: Optional corpus geometry provider for manifold-aware control.
     *
     * When provided, the PID controller uses the **normal component** of the
     * EKF velocity (v_normal — off-manifold drift) as its error signal instead
     * of the raw physics error. This means the controller only corrects for
     * drift off the data manifold, not for valid on-manifold exploration.
     *
     * Requires the same `ManifoldProvider` used by `manifoldMiddleware`.
     */
    manifold?: {
        provider: ManifoldProvider;
        /** Number of neighbors for local PCA. Default: 50. */
        k?: number;
        /** Number of principal components for tangent space. Default: auto (80% variance). */
        topK?: number;
    };
    /** Optional logger for kinematics telemetry. */
    logger?: Logger;
}
/**
 * Advanced middleware that detects semantic drift using an EKF physics engine
 * and PID controller.
 *
 * Each step, it embeds the state into a vector, updates the physics model,
 * and computes a correction signal. Results are stored in `ctx.metadata`:
 *
 * - `metadata['kinematics']` — `KinematicsSnapshot` with position, velocity, error, etc.
 * - `metadata['kinematicsCorrection']` — `CorrectionInfo` (only when drift detected).
 *
 * The middleware **observes and annotates** — it does not halt or override actions.
 * Downstream middleware or the agent can read the correction to decide how to respond.
 */
declare function kinematicsMiddleware<S>(opts: KinematicsMiddlewareOpts<S>): Middleware<S>;

interface ManifoldMiddlewareOpts<S> {
    /** Embedder to convert state → vector. */
    embedder: StateEmbedder<S>;
    /** Corpus geometry provider (vector DB, embedding store, etc.). */
    manifold: ManifoldProvider;
    /** Number of neighbors for local PCA. Default: 50. */
    k?: number;
    /**
     * Number of principal components for tangent space.
     * If omitted, auto-selects to explain 80% of variance.
     */
    topK?: number;
    /**
     * Distance threshold for drift detection. When the nearest neighbor
     * distance exceeds this value, the agent is considered to be drifting
     * off the manifold (in a "data desert").
     *
     * If omitted, drift detection is disabled (isDrifting always false).
     */
    driftThreshold?: number;
    /**
     * Action to take when drift is detected.
     * - `'warn'` — annotate `isDrifting: true` in metadata, do not halt (default)
     * - `'halt'` — return `'halt'` to stop the control loop
     */
    driftAction?: 'warn' | 'halt';
    /** Optional logger for manifold telemetry. */
    logger?: Logger;
}
/**
 * Advanced middleware that performs Riemannian manifold analysis each step.
 *
 * It embeds the current state, queries the ManifoldProvider for k nearest
 * neighbors, runs local PCA to compute the tangent/normal decomposition,
 * and annotates `ctx.metadata['manifold']` with a `ManifoldSnapshot`.
 *
 * **Velocity source:** If `kinematicsMiddleware` is stacked before this
 * middleware, the EKF-filtered velocity from `metadata['kinematics']` is
 * used. Otherwise, raw velocity is computed as (current - previous embedding).
 *
 * The middleware **observes and annotates** by default. When `driftThreshold`
 * is set, it can also detect when the agent enters a "data desert" (no nearby
 * corpus data). The `driftAction` option controls whether this triggers a
 * halt or just a warning annotation in metadata.
 *
 * **Ordering:** Stack this middleware AFTER `kinematicsMiddleware` so that
 * the filtered velocity is available.
 */
declare function manifoldMiddleware<S>(opts: ManifoldMiddlewareOpts<S>): Middleware<S>;

export { type CorrectionInfo, type GrassmannianMiddlewareOpts, type KinematicsMiddlewareOpts, type KinematicsSnapshot, type ManifoldMiddlewareOpts, grassmannianMiddleware, kinematicsMiddleware, manifoldMiddleware };