lootforge 0.3.0

package/dist/providers/types-core.d.ts

@@ -0,0 +1,514 @@
+export declare const PROVIDER_NAMES: readonly ["openai", "nano", "local"];
+export declare const KNOWN_STYLE_PRESETS: readonly ["pixel-art-16bit", "topdown-painterly-sci-fi"];
+export declare const POST_PROCESS_ALGORITHMS: readonly ["nearest", "lanczos3"];
+export declare const TARGET_KINDS: readonly ["sprite", "tile", "background", "effect", "spritesheet"];
+export declare const CONTROL_MODES: readonly ["canny", "depth", "openpose"];
+export declare const GENERATION_MODES: readonly ["text", "edit-first"];
+export declare const WRAP_GRID_TOPOLOGY_MODES: readonly ["self", "one-to-one", "many-to-many"];
+export declare const FACING_DIRECTIONS: readonly ["left", "right"];
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+export type ProviderSelection = ProviderName | "auto";
+export type ProviderFeature = "image-generation" | "transparent-background" | "image-edits" | "multi-candidate" | "controlnet";
+export type KnownStylePreset = (typeof KNOWN_STYLE_PRESETS)[number];
+export type PostProcessAlgorithm = (typeof POST_PROCESS_ALGORITHMS)[number];
+export type NormalizedOutputFormat = "png" | "jpeg" | "webp";
+export type TargetKind = (typeof TARGET_KINDS)[number];
+export type ControlMode = (typeof CONTROL_MODES)[number];
+export type GenerationMode = (typeof GENERATION_MODES)[number];
+export type WrapGridTopologyMode = (typeof WRAP_GRID_TOPOLOGY_MODES)[number];
+export type FacingDirection = (typeof FACING_DIRECTIONS)[number];
+export type PaletteMode = "exact" | "max-colors";
+export interface ProviderCapabilities {
+    readonly name: ProviderName;
+    readonly defaultOutputFormat: NormalizedOutputFormat;
+    readonly supportedOutputFormats: ReadonlySet<NormalizedOutputFormat>;
+    readonly supportsTransparentBackground: boolean;
+    readonly supportsEdits: boolean;
+    readonly supportsControlNet: boolean;
+    readonly maxCandidates: number;
+    readonly defaultConcurrency: number;
+    readonly minDelayMs: number;
+}
+export declare const PROVIDER_CAPABILITIES: Record<ProviderName, ProviderCapabilities>;
+export interface PromptSpec {
+    primary: string;
+    useCase?: string;
+    stylePreset?: string;
+    scene?: string;
+    subject?: string;
+    style?: string;
+    composition?: string;
+    lighting?: string;
+    palette?: string;
+    materials?: string;
+    constraints?: string;
+    negative?: string;
+}
+export interface PalettePolicy {
+    mode: PaletteMode;
+    colors?: string[];
+    maxColors?: number;
+    dither?: number;
+    strict?: boolean;
+}
+export interface CoarseToFinePolicy {
+    enabled?: boolean;
+    promoteTopK?: number;
+    minDraftScore?: number;
+    requireDraftAcceptance?: boolean;
+}
+export interface AgenticRetryPolicy {
+    enabled?: boolean;
+    maxRetries?: number;
+}
+export interface GenerationPolicy {
+    size?: string;
+    /** Accepts "transparent", "opaque", or any custom value. */
+    background?: string;
+    outputFormat?: string;
+    quality?: string;
+    draftQuality?: string;
+    finalQuality?: string;
+    highQuality?: boolean;
+    hiresFix?: {
+        enabled?: boolean;
+        upscale?: number;
+        denoiseStrength?: number;
+    };
+    candidates?: number;
+    maxRetries?: number;
+    fallbackProviders?: ProviderName[];
+    providerConcurrency?: number;
+    rateLimitPerMinute?: number;
+    vlmGate?: VlmGatePolicy;
+    coarseToFine?: CoarseToFinePolicy;
+    agenticRetry?: AgenticRetryPolicy;
+}
+export interface VlmGatePolicy {
+    threshold?: number;
+    rubric?: string;
+}
+export interface TrimOperation {
+    enabled?: boolean;
+    threshold?: number;
+}
+export interface PadOperation {
+    pixels: number;
+    extrude?: boolean;
+    background?: string;
+}
+export interface QuantizeOperation {
+    colors: number;
+    dither?: number;
+}
+export interface OutlineOperation {
+    size: number;
+    color?: string;
+}
+export interface ResizeVariant {
+    name: string;
+    width: number;
+    height: number;
+    algorithm?: PostProcessAlgorithm;
+}
+export interface ResizeVariantsOperation {
+    variants: ResizeVariant[];
+}
+export interface PixelPerfectOperation {
+    enabled?: boolean;
+    scale?: number;
+}
+export interface SmartCropOperation {
+    enabled?: boolean;
+    mode?: "alpha-bounds" | "center";
+    padding?: number;
+}
+export interface VariantOutputsOperation {
+    raw?: boolean;
+    pixel?: boolean;
+    styleRef?: boolean;
+    layerColor?: boolean;
+    layerMatte?: boolean;
+}
+export interface PostProcessOperations {
+    trim?: TrimOperation;
+    pad?: PadOperation;
+    quantize?: QuantizeOperation;
+    outline?: OutlineOperation;
+    resizeVariants?: ResizeVariantsOperation;
+    pixelPerfect?: PixelPerfectOperation;
+    smartCrop?: SmartCropOperation;
+    emitVariants?: VariantOutputsOperation;
+}
+export interface PostProcessPolicy {
+    resizeTo?: {
+        width: number;
+        height: number;
+    };
+    algorithm?: PostProcessAlgorithm;
+    stripMetadata?: boolean;
+    pngPaletteColors?: number;
+    operations?: PostProcessOperations;
+}
+export interface TargetEditInput {
+    path: string;
+    role?: "base" | "mask" | "reference";
+    fidelity?: "low" | "medium" | "high";
+}
+export interface TargetEditSpec {
+    mode?: "edit" | "iterate";
+    instruction?: string;
+    inputs?: TargetEditInput[];
+    preserveComposition?: boolean;
+}
+export interface RegenerationSource {
+    mode: "selection-lock" | "selection-lock-edit";
+    selectionLockPath: string;
+    selectionLockGeneratedAt?: string;
+    lockInputHash: string;
+    lockSelectedOutputPath: string;
+}
+export interface AuxiliaryMapPolicy {
+    normalFromHeight?: boolean;
+    specularFromLuma?: boolean;
+    aoFromLuma?: boolean;
+}
+export interface TargetScoreWeights {
+    readability?: number;
+    fileSize?: number;
+    consistency?: number;
+    clip?: number;
+    lpips?: number;
+    ssim?: number;
+}
+export interface ConsistencyGroupScoringPolicy {
+    warningThreshold?: number;
+    penaltyThreshold?: number;
+    penaltyWeight?: number;
+}
+export interface SeamHealPolicy {
+    enabled?: boolean;
+    stripPx?: number;
+    strength?: number;
+}
+export interface WrapGridPolicy {
+    columns: number;
+    rows: number;
+    seamThreshold?: number;
+    seamStripPx?: number;
+    topology?: WrapGridTopologyPolicy;
+}
+export interface WrapGridTopologyPolicy {
+    mode: WrapGridTopologyMode;
+    maxMismatchRatio?: number;
+    colorTolerance?: number;
+}
+export interface VisualStylePolicy {
+    lineContrastMin?: number;
+    shadingBandCountMax?: number;
+    uiRectilinearityMin?: number;
+}
+export interface PlannedTarget {
+    id: string;
+    kind?: string;
+    out: string;
+    templateId?: string;
+    dependsOn?: string[];
+    styleReferenceFrom?: string[];
+    atlasGroup?: string | null;
+    styleKitId?: string;
+    styleReferenceImages?: string[];
+    loraPath?: string;
+    loraStrength?: number;
+    consistencyGroup?: string;
+    consistencyGroupScoring?: ConsistencyGroupScoringPolicy;
+    visualStylePolicy?: VisualStylePolicy;
+    generationMode?: GenerationMode;
+    evaluationProfileId?: string;
+    scoringProfile?: string;
+    controlImage?: string;
+    controlMode?: ControlMode;
+    facing?: FacingDirection;
+    scoreWeights?: TargetScoreWeights;
+    tileable?: boolean;
+    seamThreshold?: number;
+    seamStripPx?: number;
+    alphaHaloRiskMax?: number;
+    alphaStrayNoiseMax?: number;
+    alphaEdgeSharpnessMin?: number;
+    mattingHiddenRgbLeakMax?: number;
+    mattingMaskConsistencyMin?: number;
+    mattingSemiTransparencyRatioMax?: number;
+    packTextureBudgetMB?: number;
+    spritesheetSilhouetteDriftMax?: number;
+    spritesheetAnchorDriftMax?: number;
+    spritesheetIdentityDriftMax?: number;
+    spritesheetPoseDriftMax?: number;
+    spritesheetWalkLowerBodyMotionMin?: number;
+    spritesheetWalkFootMotionMin?: number;
+    spritesheetWalkFootToUpperMotionRatioMin?: number;
+    seamHeal?: SeamHealPolicy;
+    wrapGrid?: WrapGridPolicy;
+    palette?: PalettePolicy;
+    generationDisabled?: boolean;
+    catalogDisabled?: boolean;
+    spritesheet?: {
+        sheetTargetId: string;
+        isSheet?: boolean;
+        animations?: {
+            name: string;
+            count: number;
+            fps?: number;
+            loop?: boolean;
+            facing?: FacingDirection;
+            pivot?: {
+                x: number;
+                y: number;
+            };
+        }[];
+        animationName?: string;
+        facing?: FacingDirection;
+        frameIndex?: number;
+        frameCount?: number;
+        fps?: number;
+        loop?: boolean;
+        pivot?: {
+            x: number;
+            y: number;
+        };
+        /** When set, this target generates a wide strip image containing all frames
+         *  for the animation. After generation, the strip is sliced into individual
+         *  frame files at the paths listed in `frameOutputPaths`. */
+        stripGeneration?: {
+            frameCount: number;
+            /** Relative output paths (target.out style) for each frame in order. */
+            frameOutputPaths: string[];
+        };
+    };
+    acceptance?: {
+        size?: string;
+        alpha?: boolean;
+        maxFileSizeKB?: number;
+    };
+    runtimeSpec?: {
+        alphaRequired?: boolean;
+        previewWidth?: number;
+        previewHeight?: number;
+        anchorX?: number;
+        anchorY?: number;
+    };
+    promptSpec: PromptSpec;
+    generationPolicy?: GenerationPolicy;
+    postProcess?: PostProcessPolicy;
+    provider?: ProviderName;
+    model?: string;
+    edit?: TargetEditSpec;
+    regenerationSource?: RegenerationSource;
+    auxiliaryMaps?: AuxiliaryMapPolicy;
+}
+export interface PlannedTargetsIndex {
+    targets: PlannedTarget[];
+    generatedAt?: string;
+    manifestPath?: string;
+}
+export interface NormalizedGenerationPolicy {
+    size: string;
+    quality: string;
+    draftQuality?: string;
+    finalQuality?: string;
+    /** Accepts "transparent", "opaque", or any custom value. */
+    background: string;
+    outputFormat: NormalizedOutputFormat;
+    highQuality?: boolean;
+    hiresFix?: {
+        enabled?: boolean;
+        upscale?: number;
+        denoiseStrength?: number;
+    };
+    candidates: number;
+    maxRetries?: number;
+    fallbackProviders: ProviderName[];
+    providerConcurrency?: number;
+    rateLimitPerMinute?: number;
+    vlmGate?: VlmGatePolicy;
+    coarseToFine?: {
+        enabled: boolean;
+        promoteTopK: number;
+        minDraftScore?: number;
+        requireDraftAcceptance: boolean;
+    };
+    agenticRetry?: {
+        enabled: boolean;
+        maxRetries: number;
+    };
+}
+export interface PolicyNormalizationIssue {
+    level: "warning" | "error";
+    code: string;
+    message: string;
+}
+export interface ProviderPolicyNormalizationResult {
+    policy: NormalizedGenerationPolicy;
+    issues: PolicyNormalizationIssue[];
+}
+export interface ProviderJob {
+    id: string;
+    provider: ProviderName;
+    model: string;
+    targetId: string;
+    targetOut: string;
+    prompt: string;
+    outPath: string;
+    inputHash: string;
+    size: string;
+    quality: string;
+    background: string;
+    outputFormat: NormalizedOutputFormat;
+    candidateCount: number;
+    maxRetries: number;
+    fallbackProviders: ProviderName[];
+    providerConcurrency?: number;
+    rateLimitPerMinute?: number;
+    target: PlannedTarget;
+}
+export interface ProviderCandidateOutput {
+    outputPath: string;
+    bytesWritten: number;
+}
+export interface CandidateScoreRecord {
+    outputPath: string;
+    score: number;
+    passedAcceptance: boolean;
+    reasons: string[];
+    stage?: "draft" | "refine" | "autocorrect";
+    promoted?: boolean;
+    sourceOutputPath?: string;
+    autoCorrectAttempt?: number;
+    components?: Record<string, number>;
+    metrics?: Record<string, number>;
+    vlm?: CandidateVlmScore;
+    warnings?: string[];
+    selected?: boolean;
+}
+export interface CandidateVlmScore {
+    score: number;
+    threshold: number;
+    maxScore: number;
+    passed: boolean;
+    reason: string;
+    rubric?: string;
+    evaluator: "command" | "http";
+}
+export interface ProviderRunResult {
+    jobId: string;
+    provider: ProviderName;
+    model: string;
+    targetId: string;
+    prompt?: string;
+    outputPath: string;
+    bytesWritten: number;
+    inputHash: string;
+    startedAt: string;
+    finishedAt: string;
+    skipped?: boolean;
+    candidateOutputs?: ProviderCandidateOutput[];
+    candidateScores?: CandidateScoreRecord[];
+    coarseToFine?: {
+        enabled: boolean;
+        draftQuality: string;
+        finalQuality: string;
+        promoteTopK: number;
+        minDraftScore?: number;
+        requireDraftAcceptance: boolean;
+        draftCandidateCount: number;
+        promoted: {
+            outputPath: string;
+            score: number;
+            passedAcceptance: boolean;
+            refinedOutputPath?: string;
+        }[];
+        discarded: {
+            outputPath: string;
+            score: number;
+            passedAcceptance: boolean;
+            reason: string;
+        }[];
+        skippedReason?: string;
+        warnings?: string[];
+    };
+    agenticRetry?: {
+        enabled: boolean;
+        maxRetries: number;
+        attempted: number;
+        succeeded: boolean;
+        skippedReason?: string;
+        attempts: {
+            attempt: number;
+            sourceOutputPath: string;
+            outputPath: string;
+            retryOutputPath: string;
+            critique: string;
+            triggeredBy: string[];
+            scoreBefore: number;
+            scoreAfter: number;
+            passedBefore: boolean;
+            passedAfter: boolean;
+            reasonsBefore: string[];
+            reasonsAfter: string[];
+        }[];
+    };
+    styleReferenceLineage?: {
+        source: "style-kit" | "target-output";
+        reference: string;
+        sourceTargetId?: string;
+        resolvedPath?: string;
+    }[];
+    generationMode?: GenerationMode;
+    edit?: TargetEditSpec;
+    regenerationSource?: RegenerationSource;
+    warnings?: string[];
+}
+export interface ProviderPrepareContext {
+    outDir: string;
+    imagesDir: string;
+    now?: () => Date;
+}
+export interface ProviderRunContext extends ProviderPrepareContext {
+    fetchImpl?: typeof fetch;
+}
+export interface ProviderEditJob {
+    id: string;
+    provider: ProviderName;
+    model: string;
+    targetId: string;
+    instruction: string;
+    inputs: TargetEditInput[];
+    outPath: string;
+    inputHash: string;
+}
+export type ProviderEditContext = ProviderRunContext;
+export interface GenerationProvider {
+    readonly name: ProviderName;
+    readonly capabilities: ProviderCapabilities;
+    prepareJobs(targets: PlannedTarget[], ctx: ProviderPrepareContext): ProviderJob[] | Promise<ProviderJob[]>;
+    runJob(job: ProviderJob, ctx: ProviderRunContext): Promise<ProviderRunResult>;
+    runEditJob?(job: ProviderEditJob, ctx: ProviderEditContext): Promise<ProviderRunResult>;
+    supports(feature: ProviderFeature): boolean;
+    normalizeError(error: unknown): ProviderError;
+}
+export interface ProviderErrorInit {
+    provider: ProviderName;
+    code: string;
+    message: string;
+    cause?: unknown;
+    actionable?: string;
+    status?: number;
+}
+export declare class ProviderError extends Error {
+    readonly provider: ProviderName;
+    readonly code: string;
+    readonly actionable?: string;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(init: ProviderErrorInit);
+}

package/dist/providers/types-core.js

@@ -0,0 +1,60 @@
+export const PROVIDER_NAMES = ["openai", "nano", "local"];
+export const KNOWN_STYLE_PRESETS = ["pixel-art-16bit", "topdown-painterly-sci-fi"];
+export const POST_PROCESS_ALGORITHMS = ["nearest", "lanczos3"];
+export const TARGET_KINDS = ["sprite", "tile", "background", "effect", "spritesheet"];
+export const CONTROL_MODES = ["canny", "depth", "openpose"];
+export const GENERATION_MODES = ["text", "edit-first"];
+export const WRAP_GRID_TOPOLOGY_MODES = ["self", "one-to-one", "many-to-many"];
+export const FACING_DIRECTIONS = ["left", "right"];
+const SUPPORTED_FORMATS = new Set(["png", "jpeg", "webp"]);
+export const PROVIDER_CAPABILITIES = {
+    openai: {
+        name: "openai",
+        defaultOutputFormat: "png",
+        supportedOutputFormats: SUPPORTED_FORMATS,
+        supportsTransparentBackground: true,
+        supportsEdits: true,
+        supportsControlNet: false,
+        maxCandidates: 8,
+        defaultConcurrency: 2,
+        minDelayMs: 250,
+    },
+    nano: {
+        name: "nano",
+        defaultOutputFormat: "png",
+        supportedOutputFormats: SUPPORTED_FORMATS,
+        supportsTransparentBackground: false,
+        supportsEdits: true,
+        supportsControlNet: false,
+        maxCandidates: 4,
+        defaultConcurrency: 2,
+        minDelayMs: 350,
+    },
+    local: {
+        name: "local",
+        defaultOutputFormat: "png",
+        supportedOutputFormats: SUPPORTED_FORMATS,
+        supportsTransparentBackground: true,
+        supportsEdits: true,
+        supportsControlNet: true,
+        maxCandidates: 8,
+        defaultConcurrency: 2,
+        minDelayMs: 100,
+    },
+};
+export class ProviderError extends Error {
+    provider;
+    code;
+    actionable;
+    status;
+    constructor(init) {
+        super(init.message);
+        this.name = "ProviderError";
+        this.provider = init.provider;
+        this.code = init.code;
+        this.actionable = init.actionable;
+        this.status = init.status;
+        this.cause = init.cause;
+    }
+}
+//# sourceMappingURL=types-core.js.map

package/dist/providers/types-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-core.js","sourceRoot":"","sources":["../../src/providers/types-core.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,iBAAiB,EAAE,0BAA0B,CAAU,CAAC;AAC5F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,SAAS,EAAE,UAAU,CAAU,CAAC;AACxE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,CAAU,CAAC;AAC/F,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,YAAY,CAAU,CAAC;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,cAAc,CAAU,CAAC;AACxF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAU,CAAC;AAgC5D,MAAM,iBAAiB,GAAwC,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhG,MAAM,CAAC,MAAM,qBAAqB,GAA+C;IAC/E,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,mBAAmB,EAAE,KAAK;QAC1B,sBAAsB,EAAE,iBAAiB;QACzC,6BAA6B,EAAE,IAAI;QACnC,aAAa,EAAE,IAAI;QACnB,kBAAkB,EAAE,KAAK;QACzB,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,UAAU,EAAE,GAAG;KAChB;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,mBAAmB,EAAE,KAAK;QAC1B,sBAAsB,EAAE,iBAAiB;QACzC,6BAA6B,EAAE,KAAK;QACpC,aAAa,EAAE,IAAI;QACnB,kBAAkB,EAAE,KAAK;QACzB,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,UAAU,EAAE,GAAG;KAChB;IACD,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,mBAAmB,EAAE,KAAK;QAC1B,sBAAsB,EAAE,iBAAiB;QACzC,6BAA6B,EAAE,IAAI;QACnC,aAAa,EAAE,IAAI;QACnB,kBAAkB,EAAE,IAAI;QACxB,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,UAAU,EAAE,GAAG;KAChB;CACF,CAAC;AA0gBF,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAe;IACvB,IAAI,CAAS;IACb,UAAU,CAAU;IACpB,MAAM,CAAU;IAGzB,YAAY,IAAuB;QACjC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;CACF"}

package/dist/providers/types.d.ts

@@ -0,0 +1,4 @@
+export * from "./types-core.js";
+export * from "./prompt.js";
+export * from "./policy.js";
+export * from "./job.js";

package/dist/providers/types.js

@@ -0,0 +1,5 @@
+export * from "./types-core.js";
+export * from "./prompt.js";
+export * from "./policy.js";
+export * from "./job.js";
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/service/generationRequest.d.ts

@@ -0,0 +1,58 @@
+import { type ProviderSelection } from "../providers/types.js";
+export declare const CANONICAL_GENERATION_REQUEST_VERSION = "v1";
+export interface CanonicalGenerationRequestInput {
+    manifestPath?: string;
+    manifest?: Record<string, unknown>;
+    outDir?: string;
+    provider?: ProviderSelection;
+    targetIds?: string[];
+    skipLocked?: boolean;
+    selectionLockPath?: string;
+}
+export interface CanonicalGenerationRequestEnvelope {
+    requestId?: string | number;
+    request: CanonicalGenerationRequestInput;
+}
+export interface CanonicalGenerationRequestResult {
+    requestId?: string | number;
+    mappingVersion: string;
+    normalizedRequest: {
+        outDir: string;
+        manifestPath: string;
+        manifestSource: "inline" | "path";
+        provider: ProviderSelection;
+        targetIds: string[];
+        skipLocked: boolean;
+        selectionLockPath?: string;
+    };
+    plan: {
+        targets: number;
+        warnings: number;
+        targetsIndexPath: string;
+    };
+    generate: {
+        runId: string;
+        jobs: number;
+        imagesDir: string;
+        provenancePath: string;
+        targetsIndexPath: string;
+    };
+}
+export interface CanonicalGenerationRequestContext {
+    defaultOutDir?: string;
+}
+export declare class CanonicalGenerationRequestError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, options: {
+        code: string;
+        status: number;
+    });
+}
+export declare function getCanonicalGenerationRequestContract(): {
+    version: string;
+    endpoint: string;
+    summary: string;
+    fields: Record<string, string>;
+};
+export declare function runCanonicalGenerationRequest(payload: unknown, context: CanonicalGenerationRequestContext): Promise<CanonicalGenerationRequestResult>;