@bendyline/gezel-inference 1.0.6 → 1.0.7

package/dist/models/weight-facts.js

@@ -148,10 +148,13 @@ export function imageCatalogWeightFiles(manifest) {
 }
 /** The weight files of an installed sd-cpp model, headers read from disk. */
 export async function localSdCppWeightFiles(model) {
-    const entries = [
+    return localWeightFiles([
         { component: sdCppMainComponent(model.weightsKind), path: model.weightsPath },
         ...model.auxiliaryFiles.map((a) => ({ component: a.role, path: a.path })),
-    ];
+    ]);
+}
+/** Weight files on disk, priced from their headers where they are safetensors. */
+export async function localWeightFiles(entries) {
     const out = [];
     for (const entry of entries) {
         const format = weightFileFormat(entry.path);

package/dist/providers/ds4/build-provider.js

@@ -123,7 +123,7 @@ export async function buildDs4Provider(opts) {
     // This tier assumes DeepSeek-V4's small resident footprint. A model whose
     // non-routed weights are much larger caps it further via the catalog's
     // `ds4.maxLaunchCtx`; see `resolveDs4LaunchCtx` below.
-    const totalRamBytes = (await import('node:os')).totalmem();
+    const totalRamBytes = (await import('../../system/host-memory.js')).totalMemoryBytes();
     const totalRamGb = totalRamBytes / 1024 ** 3;
     const ramTieredCtx = ds4RamTieredContext(totalRamBytes);
     const ds4ConstrainedToolNoSignalMs = (() => {

package/dist/providers/ds4/residency.js

@@ -1,5 +1,5 @@
-import { totalmem } from 'node:os';
 import { DS4_FULL_RESIDENCY_HEADROOM_BYTES, LLAMA_CPP_VISION_COMPUTE_BYTES, LLAMA_CPP_WEIGHTS_MULTIPLIER, ds4FitsFullResidency, } from '@bendyline/gezel';
+import { totalMemoryBytes } from '../../system/host-memory.js';
 const GB = 1024 ** 3;
 export { DS4_FULL_RESIDENCY_HEADROOM_BYTES };
 /**
@@ -43,7 +43,7 @@ export function ds4BaseResidentBytes(opts) {
 export function canUseDs4FullResidency(opts = {}) {
     return ds4FitsFullResidency({
         modelSizeBytes: opts.modelSizeBytes,
-        totalRamBytes: opts.totalRamBytes ?? totalmem(),
+        totalRamBytes: opts.totalRamBytes ?? totalMemoryBytes(),
         companionBytes: opts.companionBytes,
         platform: opts.platform ?? process.platform,
         arch: opts.arch ?? process.arch,
@@ -82,7 +82,7 @@ export function shouldUseDs4SsdStreaming(opts = {}) {
  * state + the cache cannot consume the runtime/OS reserve.
  */
 export function planDs4ExpertCache(opts) {
-    const totalRamBytes = opts.totalRamBytes ?? totalmem();
+    const totalRamBytes = opts.totalRamBytes ?? totalMemoryBytes();
     const catalogCacheBytes = opts.catalogCacheBytes ?? 0;
     const fixedResidentBytes = Math.max(0, (opts.catalogResidentBytes ?? 0) - catalogCacheBytes);
     const fallbackGb = totalRamBytes >= 120 * GB ? 64 : totalRamBytes >= 88 * GB ? 48 : 32;

package/dist/providers/image/img2img-support.d.ts

@@ -1,5 +1,7 @@
 /**
- * Per-model img2img capability resolution for the local sd-cpp engine.
+ * Per-model image-editing capability for the local sd-cpp engine: whether a
+ * model re-noises a source (img2img), reads sources as references beside an
+ * instruction, or cannot use one. The img2img half first.
  *
  * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
  * `init_images` for any loaded model, but whether the *architecture*
@@ -37,4 +39,37 @@ export interface Img2ImgSupportVerdict {
     /** Human-readable reason, set only when unsupported. */
     reason?: string;
 }
+/**
+ * Models that edit by reading source pictures as references beside an
+ * instruction (sd-server's `extra_images`), rather than re-noising one. The
+ * same ladder as above: a catalog `referenceImages` declaration persisted at
+ * pull time wins, then this map, which is how installs that predate the
+ * field learn it.
+ *
+ * FLUX.2 Klein: verified on the pinned engine (native sd-cpp master-975) on
+ * an RTX Spark, 2026-10-27, recoloring, adding an object and composing two
+ * sources at 4 steps in 12 s.
+ */
+export declare const MODEL_REFERENCE_EDIT_SUPPORT: Map<string, {
+    maxImages: number;
+    editOnly?: boolean;
+}>;
+export interface ImageEditCapabilityInput extends Img2ImgSupportInput {
+    /** Explicit `referenceImages` from catalog/installed metadata. */
+    referenceImages?: {
+        max: number;
+    } | undefined;
+    /** Explicit `editOnly` from catalog/installed metadata. */
+    editOnly?: boolean | undefined;
+}
+export interface ImageEditCapability {
+    /** Absent when the model cannot use a source picture at all. */
+    editMode?: 'reference' | 'img2img';
+    /** Sources one edit takes: the reference limit, or 1 for img2img. */
+    maxSourceImages?: number;
+    editOnly: boolean;
+    /** Why the model cannot edit; set only when `editMode` is absent. */
+    reason?: string;
+}
+export declare function resolveImageEditCapability(input: ImageEditCapabilityInput): ImageEditCapability;
 export declare function resolveImg2ImgSupport(input: Img2ImgSupportInput): Img2ImgSupportVerdict;

package/dist/providers/image/img2img-support.js

@@ -1,5 +1,7 @@
 /**
- * Per-model img2img capability resolution for the local sd-cpp engine.
+ * Per-model image-editing capability for the local sd-cpp engine: whether a
+ * model re-noises a source (img2img), reads sources as references beside an
+ * instruction, or cannot use one. The img2img half first.
  *
  * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
  * `init_images` for any loaded model, but whether the *architecture*
@@ -44,6 +46,33 @@ export const MODEL_IMG2IMG_SUPPORT = new Map([
     ['krea-2-turbo-q6', false],
     ['krea-2-turbo-q8', false],
 ]);
+/**
+ * Models that edit by reading source pictures as references beside an
+ * instruction (sd-server's `extra_images`), rather than re-noising one. The
+ * same ladder as above: a catalog `referenceImages` declaration persisted at
+ * pull time wins, then this map, which is how installs that predate the
+ * field learn it.
+ *
+ * FLUX.2 Klein: verified on the pinned engine (native sd-cpp master-975) on
+ * an RTX Spark, 2026-10-27, recoloring, adding an object and composing two
+ * sources at 4 steps in 12 s.
+ */
+export const MODEL_REFERENCE_EDIT_SUPPORT = new Map([
+    ['flux-2-klein-4b-q4', { maxImages: 3 }],
+    ['qwen-image-edit-2511-q4', { maxImages: 3, editOnly: true }],
+]);
+export function resolveImageEditCapability(input) {
+    const assessed = input.modelId ? MODEL_REFERENCE_EDIT_SUPPORT.get(input.modelId) : undefined;
+    const editOnly = input.editOnly ?? assessed?.editOnly ?? false;
+    const maxImages = input.referenceImages?.max ?? assessed?.maxImages;
+    if (maxImages !== undefined) {
+        return { editMode: 'reference', maxSourceImages: maxImages, editOnly };
+    }
+    const img2img = resolveImg2ImgSupport(input);
+    if (img2img.supported)
+        return { editMode: 'img2img', maxSourceImages: 1, editOnly };
+    return { editOnly, ...(img2img.reason ? { reason: img2img.reason } : {}) };
+}
 export function resolveImg2ImgSupport(input) {
     if (input.explicit !== undefined) {
         return input.explicit

package/dist/providers/image/local-engine.d.ts

@@ -21,6 +21,7 @@ export interface LocalImageEngineOptions {
 export declare class LocalImageEngine {
     private readonly opts;
     readonly pulls: ImageModelPullRegistry;
+    readonly loraPulls: ImageModelPullRegistry;
     private readonly lifecycle;
     constructor(opts: LocalImageEngineOptions);
     /** Whether this host can render at all: an engine binary, a server URL, or the mock. */

package/dist/providers/image/local-engine.js

@@ -1,6 +1,6 @@
 import { ProviderLifecycle } from '../provider-lifecycle.js';
 import { createLocalImageProvider } from './local-factory.js';
-import { ImageModelPullRegistry } from './pull-registry.js';
+import { ImageModelPullRegistry, imageLoraPullResolver } from './pull-registry.js';
 /**
  * Hosted inference's image engine: the local sd-server provider, built on
  * first use, plus the pulls that install its models. Reset drains in-flight
@@ -9,12 +9,17 @@ import { ImageModelPullRegistry } from './pull-registry.js';
 export class LocalImageEngine {
     opts;
     pulls;
+    loraPulls;
     // Only promise-returning operations can be tracked; a pull is an async
     // iterable and is cancelled through its own registry instead.
-    lifecycle = new ProviderLifecycle(new Set(['generate', 'deleteModel']));
+    lifecycle = new ProviderLifecycle(new Set(['generate', 'deleteModel', 'deleteLora']));
     constructor(opts) {
         this.opts = opts;
         this.pulls = new ImageModelPullRegistry({ imageProvider: this, catalog: opts.catalog });
+        this.loraPulls = new ImageModelPullRegistry({
+            resolve: imageLoraPullResolver(this, opts.catalog),
+            kind: 'image-lora',
+        });
     }
     /** Whether this host can render at all: an engine binary, a server URL, or the mock. */
     available() {
@@ -42,6 +47,7 @@ export class LocalImageEngine {
     }
     async shutdown() {
         this.pulls.clear();
+        this.loraPulls.clear();
         await this.lifecycle.reset();
     }
 }

package/dist/providers/image/local-factory.d.ts

@@ -15,6 +15,7 @@
  *      base URL (127.0.0.1:9081) and no supervisor. `health()` reports
  *      `not-configured` so the UI can say the engine is not installed.
  */
+import type { MediaWeightFile } from '@bendyline/gezel';
 import type { GpuArbiter } from '../gpu-arbiter.js';
 import type { NativeCapacityOptions } from '../native/device-capacity.js';
 import type { ImageProvider, InstalledImageModelInfo } from './types.js';
@@ -92,4 +93,12 @@ export interface ResolvedInstalledModel extends InstalledImageModelInfo {
  * encoder runs once per image, so GPUs lose nothing. `--diffusion-fa` means
  * `--flash-attn off,diffusion=on`, so that branch already leaves it off.
  */
-export declare function buildSdServerArgs(model: ResolvedInstalledModel, port: number): string[];
+export declare function buildSdServerArgs(model: ResolvedInstalledModel, port: number, opts?: {
+    loraDir?: string;
+}): string[];
+/**
+ * The LoRA files a render of `modelId` can hold at once (its fast mode and
+ * its largest style), priced like weights. Read when the engine launches, so
+ * a LoRA installed later counts from the next launch.
+ */
+export declare function launchedLoraWeightFiles(loraRoot: string, modelId: string): Promise<MediaWeightFile[]>;

package/dist/providers/image/local-factory.js

@@ -15,18 +15,18 @@
  *      base URL (127.0.0.1:9081) and no supervisor. `health()` reports
  *      `not-configured` so the UI can say the engine is not installed.
  */
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { imageMediaPool, sdServerLedgerClaim, sdServerRequirement, } from '../../models/image-fit.js';
 import { findModelRoot, listOverlayModelIds, modelStorageRoots, verifyReadOnlyModelPayload, } from '../../models/storage-roots.js';
-import { localSdCppWeightFiles } from '../../models/weight-facts.js';
+import { localSdCppWeightFiles, localWeightFiles } from '../../models/weight-facts.js';
 import { pressureIdleGraceMs } from '../native/capacity-broker.js';
 import { measuredCapacityBudget } from '../native/measured-budget.js';
 import { pickFreePort } from '../native/port.js';
 import { NativeEngineSupervisor } from '../native/supervisor.js';
 import { patientFetch } from '../patient-fetch.js';
 import { MockImageProvider } from './mock.js';
-import { MODEL_SAMPLE_STEP_DEFAULTS, StableDiffusionCppProvider, sdServerLoadProfile, } from './sd-cpp.js';
+import { MODEL_SAMPLE_STEP_DEFAULTS, StableDiffusionCppProvider, readInstalledLoras, sdServerLoadProfile, } from './sd-cpp.js';
 /**
  * Nothing to generate with: the person has to download a model first. Its
  * own type so a route can answer with the fix, not a bare 500, which reads
@@ -80,6 +80,8 @@ export async function createLocalImageProvider(opts) {
         // when it changes; resolveLaunch reads it on the next start.
         const launchState = { modelId: undefined };
         let launchedModel;
+        const loraRoots = modelStorageRoots({ home: opts.home, engine: 'sd-cpp-loras', env });
+        const loraDir = loraRoots.writableRoot;
         const supervisor = new NativeEngineSupervisor({
             capacity: {
                 ...sdServerCapacity(opts.home),
@@ -93,7 +95,10 @@ export async function createLocalImageProvider(opts) {
                     const requirement = sdServerRequirement({
                         modelId: launchedModel.id,
                         weightsKind: launchedModel.weightsKind,
-                        files: await localSdCppWeightFiles(launchedModel),
+                        files: [
+                            ...(await localSdCppWeightFiles(launchedModel)),
+                            ...(await launchedLoraWeightFiles(loraDir, launchedModel.id)),
+                        ],
                         pool: imageMediaPool(budget.kind),
                     });
                     return sdServerLedgerClaim(requirement, budget.fastBytes);
@@ -131,9 +136,11 @@ export async function createLocalImageProvider(opts) {
                 if (!model)
                     throw new NoLocalImageModelError();
                 launchedModel = model;
+                // sd-server ignores a LoRA folder that does not exist yet, then lists none.
+                await mkdir(loraDir, { recursive: true });
                 return {
                     command: binary,
-                    args: buildSdServerArgs(model, port),
+                    args: buildSdServerArgs(model, port, { loraDir }),
                     baseUrl: `http://127.0.0.1:${port}`,
                 };
             },
@@ -146,6 +153,7 @@ export async function createLocalImageProvider(opts) {
             storageRoots,
             supervisor,
             launchState,
+            loraRoots,
             fetchImpl: patientFetch(),
             ...(defaultLocalModelId ? { defaultModelId: defaultLocalModelId } : {}),
             ...(opts.arbiter ? { arbiter: opts.arbiter } : {}),
@@ -239,7 +247,7 @@ async function findFirstInstalledModel(storageRoots) {
  * encoder runs once per image, so GPUs lose nothing. `--diffusion-fa` means
  * `--flash-attn off,diffusion=on`, so that branch already leaves it off.
  */
-export function buildSdServerArgs(model, port) {
+export function buildSdServerArgs(model, port, opts = {}) {
     const args = [];
     if (model.weightsKind === 'diffusion-model') {
         args.push('--diffusion-model', model.weightsPath);
@@ -265,6 +273,25 @@ export function buildSdServerArgs(model, port) {
         args.push('--vae-tiling');
     if (profile.stepCache)
         args.push('--cache-mode', profile.stepCache);
+    if (profile.modelArgs)
+        args.push('--model-args', profile.modelArgs);
+    // At runtime for every model: a LoRA then changes per request without
+    // touching the weights. In auto mode an unquantized checkpoint (SD, SDXL)
+    // would merge it into the weights instead.
+    if (opts.loraDir)
+        args.push('--lora-model-dir', opts.loraDir, '--lora-apply-mode', 'at_runtime');
     args.push('--listen-ip', '127.0.0.1', '--listen-port', String(port));
     return args;
 }
+/**
+ * The LoRA files a render of `modelId` can hold at once (its fast mode and
+ * its largest style), priced like weights. Read when the engine launches, so
+ * a LoRA installed later counts from the next launch.
+ */
+export async function launchedLoraWeightFiles(loraRoot, modelId) {
+    const fitting = (await readInstalledLoras(loraRoot)).filter((l) => l.baseModels.includes(modelId));
+    const largest = (purpose) => fitting
+        .filter((l) => l.purpose === purpose)
+        .sort((a, b) => b.approxSizeBytes - a.approxSizeBytes)[0];
+    return localWeightFiles([largest('speed'), largest('style')].flatMap((l) => l ? [{ component: 'lora', path: join(loraRoot, l.id, l.filename) }] : []));
+}

package/dist/providers/image/mock.d.ts

@@ -4,19 +4,26 @@
  * colour is derived from a hash of the prompt so different prompts yield
  * visually different (but still trivially small) outputs.
  */
-import type { ImageEngineHealth, ImageGenerationInput, ImageGenerationOutput, ImageModelPullEvent, ImageModelPullSpec, ImageProvider, InstalledImageModelInfo } from './types.js';
+import type { ImageEngineHealth, ImageGenerationInput, ImageGenerationOutput, ImageLoraPullSpec, ImageModelPullEvent, ImageModelPullSpec, ImageProvider, InstalledImageLoraInfo, InstalledImageModelInfo } from './types.js';
 export declare class MockImageProvider implements ImageProvider {
     readonly name = "mock";
     private readonly installed;
+    private readonly loras;
     /** Internal counter driving deterministic seed generation on "random" seeds. */
     private nextSeed;
     constructor(opts?: {
         preinstalled?: InstalledImageModelInfo[];
+        loras?: InstalledImageLoraInfo[];
     });
     /** Number of input images received on the most recent generate(). Tests use this. */
     lastInputImageCount: number;
+    /** The most recent generate() input. Tests use this. */
+    lastInput: ImageGenerationInput | undefined;
     generate(input: ImageGenerationInput): Promise<ImageGenerationOutput>;
     listInstalledModels(): Promise<InstalledImageModelInfo[]>;
+    listLoras(): Promise<InstalledImageLoraInfo[]>;
+    pullLora(id: string, spec: ImageLoraPullSpec): AsyncIterable<ImageModelPullEvent>;
+    deleteLora(id: string): Promise<void>;
     pullModel(id: string, spec: ImageModelPullSpec, signal?: AbortSignal): AsyncIterable<ImageModelPullEvent>;
     deleteModel(id: string): Promise<void>;
     health(): Promise<ImageEngineHealth>;

package/dist/providers/image/mock.js

@@ -8,22 +8,33 @@ import { deflateSync } from 'node:zlib';
 export class MockImageProvider {
     name = 'mock';
     installed = new Map();
+    loras = new Map();
     /** Internal counter driving deterministic seed generation on "random" seeds. */
     nextSeed = 1;
     constructor(opts = {}) {
         for (const m of opts.preinstalled ?? []) {
             this.installed.set(m.id, m);
         }
+        for (const l of opts.loras ?? [])
+            this.loras.set(l.id, l);
     }
     /** Number of input images received on the most recent generate(). Tests use this. */
     lastInputImageCount = 0;
+    /** The most recent generate() input. Tests use this. */
+    lastInput;
     async generate(input) {
         this.lastInputImageCount = input.inputImages?.length ?? 0;
+        this.lastInput = input;
         const width = clamp(input.width ?? 16, 1, 512);
         const height = clamp(input.height ?? 16, 1, 512);
         const steps = clamp(input.steps ?? 1, 1, 100);
         const seed = input.seed ?? this.nextSeed++;
         const model = input.model ?? [...this.installed.keys()][0] ?? 'mock-model';
+        // Applied as the real engine applies them: installed, and fitting the model.
+        const loras = (input.loras ?? []).flatMap(({ id }) => {
+            const lora = this.loras.get(id);
+            return lora?.baseModels.includes(model) ? [{ id: lora.id, name: lora.name }] : [];
+        });
         const rgba = solidFill(width, height, colourForPrompt(input.prompt));
         const png = encodePng(rgba, width, height);
         return {
@@ -35,11 +46,45 @@ export class MockImageProvider {
                 widthPx: width,
                 heightPx: height,
                 durationMs: 1,
+                ...(loras.length > 0 ? { loras } : {}),
             },
         };
     }
     async listInstalledModels() {
-        return [...this.installed.values()];
+        return [...this.installed.values()].map((m) => {
+            const loras = [...this.loras.values()]
+                .filter((l) => l.baseModels.includes(m.id))
+                .map(({ id, name, purpose, steps }) => ({
+                id,
+                name,
+                purpose,
+                ...(steps !== undefined ? { steps } : {}),
+            }));
+            return loras.length > 0 ? { ...m, loras } : m;
+        });
+    }
+    async listLoras() {
+        return [...this.loras.values()];
+    }
+    async *pullLora(id, spec) {
+        yield {
+            type: 'progress',
+            bytesWritten: spec.approxSizeBytes,
+            totalBytes: spec.approxSizeBytes,
+        };
+        this.loras.set(id, {
+            id,
+            name: spec.name,
+            purpose: spec.purpose,
+            ...(spec.render?.steps !== undefined ? { steps: spec.render.steps } : {}),
+            baseModels: spec.baseModels,
+            approxSizeBytes: spec.approxSizeBytes,
+            installedAt: new Date().toISOString(),
+        });
+        yield { type: 'done', id };
+    }
+    async deleteLora(id) {
+        this.loras.delete(id);
     }
     async *pullModel(id, spec, signal) {
         const total = spec.approxSizeBytes;

package/dist/providers/image/pull-registry.d.ts

@@ -34,6 +34,13 @@ type Listener = (event: ImageModelPullEvent) => void;
 export interface ImageProviderSource {
     current(): Promise<Pick<ImageProvider, 'pullModel'>>;
 }
+/** One download the registry runs: its expected size and the event stream. */
+export interface ImagePullJob {
+    totalBytes: number;
+    run(signal: AbortSignal): AsyncIterable<ImageModelPullEvent>;
+}
+/** Turns a catalog id into a pull, or `null` for an id the catalog lacks. */
+export type ImagePullResolver = (id: string) => Promise<ImagePullJob | null>;
 /**
  * Owns the lifecycle of every in-flight image-model pull.
  *
@@ -52,11 +59,18 @@ export interface ImageProviderSource {
 export declare class ImageModelPullRegistry {
     private readonly entries;
     private readonly controllers;
-    private readonly imageProvider;
-    private readonly catalog;
+    private readonly resolve;
+    private readonly kind;
+    /**
+     * Image models by default; `resolve` makes it a registry for another kind
+     * of download (LoRAs), whose ids then never share keys with models.
+     */
     constructor(opts: {
         imageProvider: ImageProviderSource;
         catalog: CatalogService;
+    } | {
+        resolve: ImagePullResolver;
+        kind: string;
     });
     /**
      * Start a pull for `id`. Idempotent — when a pull is already in flight
@@ -101,6 +115,14 @@ export declare class ImageModelPullRegistry {
 }
 export declare class UnknownImageModelError extends Error {
     readonly id: string;
-    constructor(id: string);
+    constructor(id: string, kind?: string);
 }
+/**
+ * LoRA pulls: the catalog's `image-lora` entries, installed by whichever
+ * provider owns the engine. A provider without LoRA support fails the pull
+ * with a plain message.
+ */
+export declare function imageLoraPullResolver(imageProvider: {
+    current(): Promise<Pick<ImageProvider, 'pullLora'>>;
+}, catalog: CatalogService): ImagePullResolver;
 export {};

package/dist/providers/image/pull-registry.js

@@ -25,11 +25,21 @@ const FINISHED_TTL_MS = 8_000;
 export class ImageModelPullRegistry {
     entries = new Map();
     controllers = new Map();
-    imageProvider;
-    catalog;
+    resolve;
+    kind;
+    /**
+     * Image models by default; `resolve` makes it a registry for another kind
+     * of download (LoRAs), whose ids then never share keys with models.
+     */
     constructor(opts) {
-        this.imageProvider = opts.imageProvider;
-        this.catalog = opts.catalog;
+        if ('resolve' in opts) {
+            this.resolve = opts.resolve;
+            this.kind = opts.kind;
+        }
+        else {
+            this.resolve = imageModelPullResolver(opts.imageProvider, opts.catalog);
+            this.kind = 'image-model';
+        }
     }
     /**
      * Start a pull for `id`. Idempotent — when a pull is already in flight
@@ -47,40 +57,21 @@ export class ImageModelPullRegistry {
         }
         // Resolve the catalog entry up-front so we can fail fast with a
         // proper 404 rather than emitting a 200 + error SSE for "unknown id".
-        const item = await this.catalog.get('image-model', id);
-        if (!item || item.manifest.kind !== 'image-model') {
-            throw new UnknownImageModelError(id);
-        }
-        const manifest = item.manifest;
+        const job = await this.resolve(id);
+        if (!job)
+            throw new UnknownImageModelError(id, this.kind);
         const snapshot = {
             id,
             startedAt: new Date().toISOString(),
             bytesWritten: 0,
-            totalBytes: manifest.approxSizeBytes +
-                manifest.auxiliaryFiles.reduce((n, f) => n + f.approxSizeBytes, 0),
+            totalBytes: job.totalBytes,
             finished: false,
         };
         const entry = { snapshot, listeners: new Set() };
         this.entries.set(id, entry);
         const controller = new AbortController();
         this.controllers.set(id, controller);
-        const spec = {
-            downloadUrl: manifest.downloadUrl,
-            sha256: manifest.sha256,
-            approxSizeBytes: manifest.approxSizeBytes,
-            name: manifest.name,
-            weightsKind: manifest.weightsKind,
-            ...(manifest.supportsImg2Img !== undefined
-                ? { supportsImg2Img: manifest.supportsImg2Img }
-                : {}),
-            auxiliaryFiles: manifest.auxiliaryFiles.map((aux) => ({
-                role: aux.role,
-                downloadUrl: aux.downloadUrl,
-                sha256: aux.sha256,
-                approxSizeBytes: aux.approxSizeBytes,
-            })),
-        };
-        void this.consume(id, spec, controller.signal);
+        void this.consume(id, job, controller.signal);
         return { snapshot: { ...snapshot }, alreadyRunning: false };
     }
     list() {
@@ -148,13 +139,12 @@ export class ImageModelPullRegistry {
         if (snapshot.finished && !snapshot.error)
             listener({ type: 'done', id: snapshot.id });
     }
-    async consume(id, spec, signal) {
+    async consume(id, job, signal) {
         const entry = this.entries.get(id);
         if (!entry)
             return;
         try {
-            const provider = await this.imageProvider.current();
-            for await (const event of provider.pullModel(id, spec, signal)) {
+            for await (const event of job.run(signal)) {
                 this.applyEvent(entry, event);
                 this.broadcast(entry, event);
                 if (event.type === 'done' || event.type === 'error')
@@ -171,7 +161,8 @@ export class ImageModelPullRegistry {
         finally {
             entry.snapshot.finished = true;
             // Drop the controller — cancel() should be a no-op once finished.
-            this.controllers.delete(id);
+            if (this.entries.get(id) === entry)
+                this.controllers.delete(id);
             // Keep the snapshot around briefly so a client mid-reconnect still
             // sees the terminal state on `list()` / `subscribe()`. Then garbage
             // collect.
@@ -184,6 +175,9 @@ export class ImageModelPullRegistry {
     }
     applyEvent(entry, event) {
         const s = entry.snapshot;
+        // Publish terminal state before generator cleanup can yield to a new subscriber.
+        if (event.type === 'done' || event.type === 'error')
+            s.finished = true;
         if (event.type === 'progress') {
             s.bytesWritten = event.bytesWritten;
             if (event.totalBytes !== undefined)
@@ -219,9 +213,77 @@ export class ImageModelPullRegistry {
 }
 export class UnknownImageModelError extends Error {
     id;
-    constructor(id) {
-        super(`unknown image-model: ${id}`);
+    constructor(id, kind = 'image-model') {
+        super(`unknown ${kind}: ${id}`);
         this.id = id;
         this.name = 'UnknownImageModelError';
     }
 }
+function imageModelPullResolver(imageProvider, catalog) {
+    return async (id) => {
+        const item = await catalog.get('image-model', id);
+        if (!item || item.manifest.kind !== 'image-model')
+            return null;
+        const manifest = item.manifest;
+        const spec = {
+            downloadUrl: manifest.downloadUrl,
+            sha256: manifest.sha256,
+            approxSizeBytes: manifest.approxSizeBytes,
+            name: manifest.name,
+            weightsKind: manifest.weightsKind,
+            ...(manifest.supportsImg2Img !== undefined
+                ? { supportsImg2Img: manifest.supportsImg2Img }
+                : {}),
+            ...(manifest.referenceImages ? { referenceImages: manifest.referenceImages } : {}),
+            ...(manifest.editOnly !== undefined ? { editOnly: manifest.editOnly } : {}),
+            auxiliaryFiles: manifest.auxiliaryFiles.map((aux) => ({
+                role: aux.role,
+                downloadUrl: aux.downloadUrl,
+                sha256: aux.sha256,
+                approxSizeBytes: aux.approxSizeBytes,
+            })),
+        };
+        return {
+            totalBytes: manifest.approxSizeBytes +
+                manifest.auxiliaryFiles.reduce((n, f) => n + f.approxSizeBytes, 0),
+            async *run(signal) {
+                const provider = await imageProvider.current();
+                yield* provider.pullModel(id, spec, signal);
+            },
+        };
+    };
+}
+/**
+ * LoRA pulls: the catalog's `image-lora` entries, installed by whichever
+ * provider owns the engine. A provider without LoRA support fails the pull
+ * with a plain message.
+ */
+export function imageLoraPullResolver(imageProvider, catalog) {
+    return async (id) => {
+        const item = await catalog.get('image-lora', id);
+        if (!item || item.manifest.kind !== 'image-lora')
+            return null;
+        const manifest = item.manifest;
+        const spec = {
+            downloadUrl: manifest.downloadUrl,
+            sha256: manifest.sha256,
+            approxSizeBytes: manifest.approxSizeBytes,
+            name: manifest.name,
+            baseModels: manifest.baseModels,
+            purpose: manifest.purpose,
+            strength: manifest.strength,
+            ...(manifest.prompt ? { prompt: manifest.prompt } : {}),
+            ...(manifest.render ? { render: manifest.render } : {}),
+        };
+        return {
+            totalBytes: manifest.approxSizeBytes,
+            async *run(signal) {
+                const provider = await imageProvider.current();
+                if (!provider.pullLora) {
+                    throw new Error('This image engine cannot add styles or fast mode.');
+                }
+                yield* provider.pullLora(id, spec, signal);
+            },
+        };
+    };
+}