export type StageDef = {
    description: string;
    /**
     * Body keys whose value is itself a sub-pipeline (an array of stage
     * objects). The sentinel `"*"` means every value of the body object is a
     * sub-pipeline (used for `$facet`).
     */
    subPipelineFields: readonly string[];
    /**
     * Set on the *diagnostic / system* source stages (`$indexStats`,
     * `$currentOp`, …). These don't transform an incoming stream — they produce
     * one — so they must be the pipeline's first stage, and they differ by
     * *where* they legally run. jsmql surfaces a scope-encoding sugar
     * (`$$.indexStats()` collection, `$$$$.currentOp()` / `$$$$.shardedDataDistribution()`
     * cluster/server) driven entirely off this field; see
     * src/system-stage-translation.ts. Two tiers are in use — collection (`$$`)
     * and cluster/server (`$$$$`); the `currentOp` family runs on the admin
     * database, not the current one, so it's cluster-scoped, not `database`.
     * `options: false` marks the stages that take no options object
     * (`{ $indexStats: {} }`).
     */
    diagnostic?: {
        scope: "collection" | "database" | "cluster";
        options: boolean;
    };
    /**
     * Absolute positional constraint, knowable purely from pipeline shape:
     *   "first" — must sit at index 0 of whatever pipeline it appears in. Set on
     *             *source* stages that produce (not transform) documents and so
     *             ignore any incoming stream. The 9 `diagnostic` stages are also
     *             must-be-first — `stageMustBeFirst` derives that from
     *             `diagnostic`, so they do NOT repeat `position` here.
     *   "last"  — must be the final stage (a write / terminal stage).
     * Enforced for the literal stage forms (`{ $merge: … }`) by pipeline.ts; the
     * sugar forms (`$out` / `$$.indexStats()` / …) keep their own dedicated,
     * sugar-aware messages. See docs/specs/pipeline-validation.md.
     */
    position?: "first" | "last";
    /**
     * Sub-pipeline containers this stage may not appear inside. The container
     * kind is the stage that owns the sub-pipeline: "facet" (`$facet.*`),
     * "lookup" (`$lookup.pipeline`), "unionWith" (`$unionWith.pipeline`).
     * `$out`/`$merge` are forbidden in all three; the `$facet` forbidden-stage
     * list (per the MongoDB `$facet` reference) bans source/search/write stages
     * inside a facet sub-pipeline.
     */
    forbiddenIn?: readonly ("facet" | "lookup" | "unionWith")[];
};
export declare const STAGES: Record<string, StageDef>;
export declare function lookupStage(name: string): StageDef | undefined;
/**
 * Must this stage sit at index 0 of its pipeline? True for the explicit
 * `position: "first"` source stages AND for every diagnostic stage — a
 * diagnostic produces its own document stream (index/collection stats, running
 * ops, …) and ignores any input, so a non-first placement has no valid runtime
 * context. Deriving the diagnostics here keeps the literal-form check in step
 * with the sugar-form check (system-stage-translation.ts) off one source.
 */
export declare function stageMustBeFirst(def: StageDef): boolean;
/** Must this stage be the final stage of its pipeline (a write / terminal stage)? */
export declare function stageMustBeLast(def: StageDef): boolean;
/** Is this stage forbidden inside the given sub-pipeline container kind? */
export declare function stageForbiddenIn(def: StageDef, container: "facet" | "lookup" | "unionWith"): boolean;
//# sourceMappingURL=stages.d.ts.map