/**
 * Shared canonical package materialization helpers.
 *
 * @experimental This API is unstable and may change without notice.
 */
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as HttpClient from "effect/unstable/http/HttpClient";
import type { AppError, AppErrorCode } from "../app-error/index.js";
import type { Version, VersionRange } from "../version-constraints/version-constraints.js";
import type { ExtensionName, ExtensionType } from "./common.js";
import type { Handle } from "./handle.js";
import { type TreeIntegrity } from "./materialized-tree.js";
export declare const canonicalMaterializationPaths: (canonicalPath: string) => {
    stagingPath: string;
    backupPath: string;
};
export interface RecoverCanonicalDirectoryArgs {
    readonly baseDir: string;
    readonly canonicalPath: string;
}
/** Recover or clean sibling replacement state before any fallible source work. */
export declare const recoverCanonicalDirectory: (args: RecoverCanonicalDirectoryArgs) => Effect.Effect<void, AppError, Path.Path | FileSystem.FileSystem>;
export interface ReplaceCanonicalDirectoryArgs<R> {
    readonly baseDir: string;
    readonly canonicalPath: string;
    readonly populate: (stagingPath: string) => Effect.Effect<void, AppError, R>;
    readonly validate?: (stagingPath: string) => Effect.Effect<void, AppError, R>;
}
export interface ReplaceCanonicalDirectoryWithInspectionArgs<A, R> extends ReplaceCanonicalDirectoryArgs<R> {
    readonly inspect: (stagingPath: string) => Effect.Effect<A, AppError, R>;
}
export interface CanonicalDirectoryInspection<A> {
    readonly canonicalPath: string;
    readonly inspection: A;
}
export interface CreateCanonicalDirectoryArgs<R> extends ReplaceCanonicalDirectoryArgs<R> {
    /** Human-readable create-only subject used in collision diagnostics. */
    readonly subject: string;
    /** Type-defined files that must exist in the complete staged package. */
    readonly requiredFiles?: ReadonlyArray<string>;
}
/**
 * Publish a complete canonical tree from a sibling staging directory. Recovery
 * restores a prior tree left in the sibling backup by abrupt process death;
 * incomplete staging is never made eligible for reuse.
 */
export declare const replaceCanonicalDirectoryWithInspection: <A, R>(args: ReplaceCanonicalDirectoryWithInspectionArgs<A, R>) => Effect.Effect<CanonicalDirectoryInspection<A>, AppError, FileSystem.FileSystem | Path.Path | R>;
export declare const replaceCanonicalDirectory: <R>(args: ReplaceCanonicalDirectoryArgs<R>) => Effect.Effect<string, AppError, FileSystem.FileSystem | Path.Path | R>;
/**
 * Publish one create-only authored package without ever populating its
 * canonical directory in place. Interrupted sibling state is resolved before
 * the collision check while the caller holds the workspace mutation lock.
 */
export declare const createCanonicalDirectory: <R>(args: CreateCanonicalDirectoryArgs<R>) => Effect.Effect<string, AppError, FileSystem.FileSystem | Path.Path | R>;
export interface RegistryPackageMaterializationMessages {
    readonly integrityMismatchDetail: string;
}
export interface CanReuseInstalledPackageArgs {
    /**
     * Canonical installed tree for this extension. Always the workspace location
     * the extension is installed to — never a staging destination, whose absence
     * would make every install look like a first install.
     */
    readonly installedPath: string;
    /** Caller demanded an unconditional re-materialization. */
    readonly force: boolean;
    /** Exact version requested by the ref being installed. */
    readonly refVersion: string;
    /** The ref carries a pinned archive integrity (registry-resolved). */
    readonly hasIntegrity: boolean;
    /** Resolved version recorded in the current lockfile entry, when any. */
    readonly lockedVersion?: string;
    readonly existsFailureDetail: (installedPath: string) => string;
}
export interface CanReuseExternalPackageArgs {
    readonly installedPath: string;
    readonly force: boolean;
    readonly existsFailureDetail: (installedPath: string) => string;
}
/** Preserve an existing external canonical tree unless refresh was explicitly requested. */
export declare const canReuseExternalPackage: (args: CanReuseExternalPackageArgs) => Effect.Effect<boolean, AppError, FileSystem.FileSystem>;
/**
 * Decide whether the installed tree already satisfies the requested ref, so no
 * archive needs to be fetched or written.
 *
 * Callers that stage into a temporary directory must call this against the
 * canonical installed path before staging: the decision is about the installed
 * tree, while `materializeRegistryPackage` only answers where bytes go.
 */
export declare const canReuseInstalledPackage: (args: CanReuseInstalledPackageArgs) => Effect.Effect<boolean, AppError, FileSystem.FileSystem>;
export interface MaterializeRegistryPackageArgs {
    readonly baseDir: string;
    /**
     * Canonical installed path for this extension. Bytes always land in a sibling
     * staging directory first and are swapped in after validation.
     */
    readonly destinationPath: string;
    readonly sourceLocation: URL;
    readonly owner: Handle;
    readonly type: ExtensionType;
    readonly name: ExtensionName;
    readonly version: Version | VersionRange;
    readonly integrity: Option.Option<string>;
    readonly messages: RegistryPackageMaterializationMessages;
    readonly validate?: (stagingPath: string) => Effect.Effect<void, AppError, FileSystem.FileSystem | Path.Path>;
}
export interface MaterializedPackage {
    readonly canonicalPath: string;
    readonly treeIntegrity: TreeIntegrity;
}
/**
 * Fetch, verify, and extract a registry package into `destinationPath`.
 *
 * Always writes. Whether new bytes are needed at all is
 * `canReuseInstalledPackage`'s decision, which the caller makes against the
 * canonical installed path before choosing a destination.
 */
export declare const materializeRegistryPackageWithTreeIntegrity: (args: MaterializeRegistryPackageArgs) => Effect.Effect<MaterializedPackage, AppError, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
export declare const materializeRegistryPackage: (args: MaterializeRegistryPackageArgs) => Effect.Effect<string, AppError, Path.Path | FileSystem.FileSystem | HttpClient.HttpClient>;
export interface MaterializeExternalPackageArgs {
    readonly baseDir: string;
    readonly canonicalPath: string;
    readonly sourceLocation: string;
    readonly copyFailureCode: AppErrorCode;
    readonly copyFailureDetail: (canonicalPath: string) => string;
    readonly validate?: (stagingPath: string) => Effect.Effect<void, AppError, FileSystem.FileSystem | Path.Path>;
}
export declare const materializeExternalPackageWithTreeIntegrity: (args: MaterializeExternalPackageArgs) => Effect.Effect<MaterializedPackage, AppError, FileSystem.FileSystem | Path.Path>;
export declare const materializeExternalPackage: (args: MaterializeExternalPackageArgs) => Effect.Effect<string, AppError, Path.Path | FileSystem.FileSystem>;
//# sourceMappingURL=package-materialization.d.ts.map