import type { Asset, AssetGuid, Result } from '@forgeax/engine-types';
import { PackageId } from './guid.js';
import { type PluginAssetSource } from './plugin-asset.js';
import type { ScriptablePackSceneComponentInput } from './scriptable-pack.js';
/** Values deliberately stay finite and serialisable at the authoring boundary. */
export type PackParameterScalar = boolean | number | string;
export type PackParameterValue = PackParameterScalar | readonly number[] | AssetGuid;
export type PackParameterType = 'bool' | 'u32' | 'i32' | 'f32' | 'f64' | 'string' | 'enum' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'asset-guid';
export declare const PACK_PARAMETER_TYPES: readonly ["bool", "u32", "i32", "f32", "f64", "string", "enum", "vec2", "vec3", "vec4", "color", "asset-guid"];
export interface PackParameterDefinition<TName extends string = string, TType extends PackParameterType = PackParameterType, TDefault extends PackParameterValue = PackParameterValue> {
    readonly name: TName;
    readonly type: TType;
    readonly default: TDefault;
    readonly minimum?: number;
    readonly maximum?: number;
    /** Closed choices are required for `enum` and forbidden for other types. */
    readonly values?: readonly PackParameterScalar[];
    /** Optional authoring-only kind constraint for asset GUID parameters. */
    readonly kind?: Asset['kind'];
}
export type PackParameterValueFor<T extends PackParameterType> = T extends 'bool' ? boolean : T extends 'u32' | 'i32' | 'f32' | 'f64' ? number : T extends 'string' | 'enum' ? string : T extends 'vec2' ? readonly [number, number] : T extends 'vec3' ? readonly [number, number, number] : T extends 'vec4' | 'color' ? readonly [number, number, number, number] : T extends 'asset-guid' ? AssetGuid : never;
export type PackParameterValues<TParameters extends readonly PackParameterDefinition[]> = Readonly<{
    [TParameter in TParameters[number] as TParameter['name']]: TParameter extends {
        readonly type: infer TType extends PackParameterType;
    } ? TType extends 'enum' ? TParameter extends {
        readonly values: readonly (infer TValue)[];
    } ? Extract<TValue, string> : string : PackParameterValueFor<TType> : never;
}>;
export interface PackAuthoringError {
    readonly code: PackAuthoringErrorCode;
    readonly expected: string;
    readonly hint: string;
    readonly actual?: string;
    readonly detail: Readonly<Record<string, unknown>>;
}
export type PackAuthoringErrorCode = 'pack-package-id-invalid' | 'pack-package-id-collision' | 'pack-source-key-invalid' | 'pack-guid-collision' | 'pack-parent-not-found' | 'pack-parent-cycle' | 'pack-parent-has-no-parameters' | 'pack-parameter-invalid' | 'pack-content-dependency-stalled' | 'pack-output-reference-missing' | 'pack-output-reference-conflict' | 'pack-output-not-materialized' | 'asset-not-ready' | 'pack-source-revision-conflict' | 'pack-source-path-invalid' | 'pack-source-not-found' | 'pack-source-mutation-unsupported' | 'pack-source-write-failed';
export interface PackBuildReadContext {
    readByGuid<TAsset extends PackOutput = Asset>(guid: AssetGuid): Promise<Result<TAsset, unknown>>;
}
export interface PackBuildContextWithoutParameters extends PackBuildReadContext {
    readonly packageId: PackageId;
}
export interface PackBuildContextWithParameters<TParameters extends readonly PackParameterDefinition[]> extends PackBuildReadContext {
    readonly packageId: PackageId;
    readonly values: PackParameterValues<TParameters>;
}
export type PackBuildContext<TParameters extends readonly PackParameterDefinition[] | undefined> = TParameters extends readonly PackParameterDefinition[] ? PackBuildContextWithParameters<TParameters> : PackBuildContextWithoutParameters;
/** Build-only custom source. The host derives identity and invokes the kind's NativeCooker. */
export interface PackCookSource {
    readonly kind: string;
    readonly execution: 'cooked';
    readonly source: unknown;
}
export type PackOutput = Asset | PluginAssetSource | PackCookSource;
export type PackOutputMap = Readonly<Record<string, PackOutput>>;
export type PackBuildResult<TError = unknown> = Result<PackOutputMap, TError> | Promise<Result<PackOutputMap, TError>>;
export interface ScriptablePackRuntime {
    /** Complete asset read closure, including dependencies of non-default parameter branches. */
    readonly dependencies: readonly string[];
}
interface PackDefinitionBase {
    readonly schemaVersion: '2.0.0';
    readonly packageId: PackageId;
    readonly name?: string;
    readonly runtime?: ScriptablePackRuntime;
    /** Neutral component schemas used only to externalize SceneAsset refs at cook time. */
    readonly sceneComponents?: readonly ScriptablePackSceneComponentInput[];
}
export type ScriptablePackDefinition<TParameters extends readonly PackParameterDefinition[] | undefined = undefined> = PackDefinitionBase & (TParameters extends readonly PackParameterDefinition[] ? {
    readonly parameters: TParameters;
    readonly build: (context: PackBuildContextWithParameters<TParameters>) => PackBuildResult;
} : {
    readonly build: (context: PackBuildContextWithoutParameters) => PackBuildResult;
});
export type PackParameterList = readonly [PackParameterDefinition, ...PackParameterDefinition[]];
type NonEmptyParameters = PackParameterList;
type NoParameterPackInput = PackDefinitionBase & {
    readonly parameters?: never;
    readonly build: (context: PackBuildContextWithoutParameters) => PackBuildResult;
};
type ScriptablePackDefinitionInput<TParameters extends NonEmptyParameters> = PackDefinitionBase & {
    readonly parameters: TParameters;
    readonly build: (context: PackBuildContextWithParameters<TParameters>) => PackBuildResult;
};
/** Convert a UUID literal into the distinct Pack-level identity brand. */
export declare function definePackageId(value: string | PackageId): PackageId;
/**
 * Define the only executable authoring shape. A missing `parameters` property
 * is meaningful: its build context has no `values` member.
 */
export declare function definePack(definition: NoParameterPackInput): ScriptablePackDefinition<undefined>;
export declare function definePack<const TParameters extends NonEmptyParameters>(definition: ScriptablePackDefinitionInput<TParameters>): ScriptablePackDefinition<TParameters>;
/** Union used only at orchestration boundaries that accept either source form. */
export type AnyScriptablePackDefinition = ScriptablePackDefinition<PackParameterList> | ScriptablePackDefinition<undefined>;
export interface ScriptablePackSourceMeta {
    readonly schemaVersion: '2.0.0';
    readonly kind: 'scriptable-pack-source';
    readonly packageId: string;
    readonly source: string;
    readonly parameters?: readonly Readonly<Record<string, unknown>>[];
    readonly runtime?: ScriptablePackRuntime;
}
/** Ephemeral scan evidence; it intentionally contains no output GUID table. */
export declare function projectScriptablePackMeta(definition: AnyScriptablePackDefinition, sourcePath: string): ScriptablePackSourceMeta;
/** Runtime validation used by the isolated module loader and source scanner. */
export declare function validatePackDefinition(value: unknown, sourcePath?: string): Result<ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined>, PackAuthoringError>;
export declare function hasPackParameters(value: ScriptablePackDefinition | unknown): value is ScriptablePackDefinition<NonEmptyParameters>;
/** Resolve defaults plus a sparse instance override with shallow replacement. */
export declare function resolvePackParameterValues(definition: ScriptablePackDefinition<NonEmptyParameters>, overrides?: unknown, inheritedValues?: Readonly<Record<string, PackParameterValue>>): Result<PackParameterValues<NonEmptyParameters>, PackAuthoringError>;
export interface DirectPackJsonAsset {
    readonly kind: string;
    readonly payload: Readonly<Record<string, unknown>>;
    readonly refs: readonly string[];
    readonly name?: string;
    readonly artifacts?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
}
export interface DirectPackJson {
    readonly schemaVersion: '3.0.0';
    readonly packageId: string;
    /** Plugin source refs derive from $asset markers; other kinds supply refs. */
    readonly assets: Readonly<Record<string, Omit<DirectPackJsonAsset, 'refs'> & {
        readonly refs?: readonly string[];
    }>>;
}
export interface PackInstanceJson {
    readonly schemaVersion: '3.0.0';
    readonly packageId: string;
    readonly parent: string;
    readonly values: Readonly<Record<string, unknown>>;
}
export interface ParsedDirectPackJson {
    readonly format: 'direct';
    readonly schemaVersion: '3.0.0';
    readonly packageId: PackageId;
    readonly assets: Readonly<Record<string, DirectPackJsonAsset>>;
}
export interface ParsedPackInstanceJson {
    readonly format: 'instance';
    readonly schemaVersion: '3.0.0';
    readonly packageId: PackageId;
    readonly parent: PackageId;
    readonly values: Readonly<Record<string, unknown>>;
}
export type ParsedPackJson = ParsedDirectPackJson | ParsedPackInstanceJson;
/** Parse the two mutually exclusive v3 pack.json branches. */
export declare function parsePackSourceJson(value: unknown): Result<ParsedPackJson, PackAuthoringError>;
export interface DirectPackAssetProjection extends DirectPackJsonAsset {
    readonly guid: string;
    readonly sourceKey: string;
}
export interface DirectPackProjection {
    readonly packageId: string;
    readonly assets: readonly DirectPackAssetProjection[];
}
/** Add the computed GUIDs needed by the ordinary Pack v2 publication path. */
export declare function projectDirectPackJson(value: ParsedDirectPackJson): DirectPackProjection;
export interface PackParameterRootSubject {
    readonly format: 'source';
    readonly packageId: PackageId;
    readonly parameters: readonly PackParameterDefinition[];
}
export interface PackParameterInstanceSubject {
    readonly format: 'instance';
    readonly packageId: PackageId;
    readonly parent: PackageId;
    readonly values: Readonly<Record<string, unknown>>;
}
export interface PackDirectSubject {
    readonly format: 'direct';
    readonly packageId: PackageId;
}
export type PackParameterInheritanceSubject = PackParameterRootSubject | PackParameterInstanceSubject | PackDirectSubject;
export interface ResolvedPackParameterInheritance {
    readonly packageId: PackageId;
    readonly rootPackageId: PackageId;
    readonly values: Readonly<Record<string, PackParameterValue>>;
    readonly parentChain: readonly string[];
    readonly parameters: readonly PackParameterDefinition[];
}
export type PackParameterSubjectReader = (packageId: PackageId) => PackParameterInheritanceSubject | undefined | Promise<PackParameterInheritanceSubject | undefined>;
/** Resolve one finite parent chain. Every instance keeps its own packageId. */
export declare function resolvePackParameterInheritance(subject: PackParameterInheritanceSubject, readParent: PackParameterSubjectReader): Promise<Result<ResolvedPackParameterInheritance, PackAuthoringError>>;
export declare const PACK_AUTHORING_OPERATION_IDS: readonly ["asset.list", "asset.inspect", "asset.resolve", "asset.verify", "asset-source.create", "asset-source.clone", "asset-source.import", "asset-source.create-instance", "asset-source.apply-values", "asset-source.rebuild", "asset-source.cold-cook"];
export type PackAuthoringOperationId = (typeof PACK_AUTHORING_OPERATION_IDS)[number];
export interface PackAuthoringOperation {
    readonly requestId: string;
    readonly expectedRevision?: string;
    readonly operation: PackAuthoringOperationId;
    readonly subject?: string;
    readonly sourcePath?: string;
    readonly sourceRoot?: string;
    readonly targetPath?: string;
    readonly packageId?: string;
    /** Parent package identity used by asset-source.create-instance. */
    readonly parentPackageId?: string;
    /** JSON-facing alias accepted by adapters at the operation boundary. */
    readonly parent?: string;
    readonly sourceKey?: string;
    readonly values?: Readonly<Record<string, unknown>>;
    /** `pack.ts` or `pack.json`; omitted defaults to the target extension. */
    readonly format?: 'pack.ts' | 'pack.json';
    /** Direct v3 entries for asset-source.create. */
    readonly initialAssets?: Readonly<Record<string, DirectPackJsonAsset>>;
    /** Explicit non-empty parameter declarations for a generated pack.ts scaffold. */
    readonly parameters?: readonly Readonly<Record<string, unknown>>[];
    /** Required proof level for asset.resolve. */
    readonly require?: 'identity' | 'present' | 'ready';
}
export type PackAuthoringResolutionStatus = 'identity' | 'present' | 'ready';
export interface PackAuthoringOperationResult {
    readonly operation: PackAuthoringOperationId;
    readonly requestId: string;
    readonly schemaVersion?: 'asset-verification-v1';
    readonly sourcePath?: string;
    readonly targetPath?: string;
    readonly revision?: string;
    readonly packageId?: string;
    readonly parentPackageId?: string;
    readonly sourceKey?: string;
    readonly guid?: string;
    readonly format?: 'pack.ts' | 'pack.json' | 'direct' | 'instance';
    readonly status?: PackAuthoringResolutionStatus;
    readonly kind?: string;
    readonly parameters?: readonly Readonly<Record<string, unknown>>[];
    readonly values?: Readonly<Record<string, unknown>>;
    /** Authored payload of the selected direct Pack output, never the whole source. */
    readonly payload?: Readonly<Record<string, unknown>>;
    readonly effectiveValues?: Readonly<Record<string, unknown>>;
    readonly parentChain?: readonly string[];
    readonly assets?: readonly Readonly<Record<string, unknown>>[];
    readonly sources?: readonly Readonly<Record<string, unknown>>[];
    readonly capabilities?: readonly PackAuthoringOperationId[];
    readonly snapshot?: {
        readonly sourceCount: number;
        readonly assetCount: number;
    };
    /** Bounded source/output facts for read-only verification consumers. */
    readonly scope?: {
        readonly sourceCount: number;
        readonly assetCount: number;
        readonly sourcePaths: readonly string[];
        readonly omittedSourceCount: number;
        readonly assetLimit: number;
        readonly truncated: boolean;
        readonly scriptablePackSourceCount: number;
        readonly scriptablePackSources: readonly {
            readonly sourcePath: string;
            readonly packageId: string;
            readonly output: 'unproduced';
            readonly reason: 'producer-not-run';
        }[];
        readonly omittedScriptablePackSourceCount: number;
    };
    readonly summary?: {
        readonly assetCount: number;
        readonly emittedAssetCount: number;
        readonly materialCount: number;
        readonly unproducedAssetCount: number;
        readonly unknownAssetCount: number;
        readonly unmaterializedScriptablePackCount: number;
    };
}
export interface PackAuthoringGatewayPort<TResult = unknown> {
    execute(operation: PackAuthoringOperation): Promise<Result<TResult, PackAuthoringError>>;
}
/** One idempotent gateway wrapper shared by Editor and CLI adapters. */
export declare function createPackAuthoringGateway<TResult = unknown>(port: PackAuthoringGatewayPort<TResult>): PackAuthoringGatewayPort<TResult>;
export declare const PACK_AUTHORING_OPERATION_DESCRIPTORS: readonly {
    id: PackAuthoringOperationId;
    domain: "asset" | "session";
    readOnly: boolean;
    requiresRevision: boolean;
}[];
export {};
//# sourceMappingURL=pack-authoring.d.ts.map