@howells/motif-sdk 7.2.0 → 7.3.0

package/dist/index.d.cts

@@ -253,6 +253,11 @@ export declare function validateCreativeDirection(creative: CreativeDirection |
  * are joined with `". "` and closed with a period. With no clauses the sanitized prompt is returned unchanged.
  */
 export declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
+/** The upscale factors an endpoint takes, from its fal OpenAPI schema. */
+interface ScaleRange {
+  max: number;
+  min: number;
+}
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -273,6 +278,7 @@ interface ImageSizeBounds {
   /** Both edges must be multiples of this. Motif uses 16 when absent. */
   multipleOf?: number;
 }
+/** ─── Queue Types ────────────────────────────────────────────── */
 interface JobStatus {
   error?: string;
   logs?: {
@@ -298,20 +304,20 @@ export declare class ImageSizeBoundsError extends Error {
   readonly bounds: ImageSizeBounds;
   constructor(model: string, aspect: AspectRatio, bounds: ImageSizeBounds);
 }
-/** Format presets that set aspect + resolution in one click */
-export declare const FORMAT_PRESETS: Record<string, {
-  label: string;
-  aspect: AspectRatio;
-  resolution?: Resolution;
-}>;
-/**
- * `MotifError` and its coercion helper.
- *
- * Extracted from `server.ts` so `server-tools.ts` can construct errors without
- * importing back into `server.ts` — that import was a dependency cycle. Both
- * `server.ts` and `server-tools.ts` import from here, and `server.ts`
- * re-exports `MotifError` so the package's public surface is unchanged.
- */
+/** A named output format: an aspect, and a resolution when the format needs one. */
+interface FormatPreset {
+  readonly aspect: AspectRatio;
+  /** What the format is for, in a few words. */
+  readonly description: string;
+  /** Short title for pickers. */
+  readonly label: string;
+  readonly resolution?: Resolution;
+  /** The platform's pixel spec, such as "1080×1920", when it publishes one. */
+  readonly size?: string;
+}
+/** Format presets that set aspect + resolution in one click, in display order. */
+export declare const FORMAT_PRESETS: Record<string, FormatPreset>;
+/** `MotifError` and the fal HTTP error mapping. */
 export declare class MotifError extends Error {
   readonly status: number;
   readonly code?: string;
@@ -324,6 +330,14 @@ export declare class MotifError extends Error {
 }
 /** Error code for a fal account that is locked, usually for lack of credit. */
 export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
+/**
+ * Error code for a request that can bill a job and got no clear answer (a
+ * connection error, a timeout, a 5xx, or an unreadable acceptance). fal may
+ * have accepted it, so the caller must not blindly submit it again.
+ */
+export declare const SUBMISSION_UNCERTAIN = "SUBMISSION_UNCERTAIN";
+/** Error code for a fal response whose body was not the JSON it should be. */
+export declare const INVALID_RESPONSE = "INVALID_RESPONSE";
 /**
  * Whether a fal HTTP failure means the account is locked.
  *
@@ -331,6 +345,12 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  * account has run out of credit. Retrying cannot help, and the key is valid.
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
+/**
+ * The option a refused request was stopped on, from either refusal shape: an
+ * `INVALID_OPTION` names it as `details.field`, a `NO_MODEL_AVAILABLE` as
+ * `details.blockedBy`. Undefined when the error names no option.
+ */
+export declare function refusedOption(error: MotifError): string | undefined;
 /**
  * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
  * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
@@ -398,6 +418,23 @@ interface TaskDefinition {
   readonly modes?: readonly TaskMode[];
   /** Best first. Order within a Tier is the order tried at that Tier. */
   readonly models: readonly RankedModel[];
+  /**
+   * Its ranked Models are generation Models: a Look can fix one.
+   */
+  readonly generationModels?: true;
+  /** Refuses a request with no prompt. */
+  readonly needsPrompt?: true;
+  /** Takes its Source and exactly one Reference. */
+  readonly oneReference?: true;
+  /** The ranking used when the request carries References, in place of `models`. */
+  readonly referenceModels?: readonly RankedModel[];
+  /** Makes a new image, so there is no Source to ask for. */
+  readonly sourceless?: true;
+  /**
+   * A Mood is joined to the prompt on its tool Models, and the plain job needs
+   * a prompt or a Mood to say what light to make.
+   */
+  readonly takesMood?: true;
 }
 /** Every Task with a Model. A Task is absent here until it has at least one Model. */
 export declare const TASKS: {
@@ -538,10 +575,14 @@ export declare const TASKS: {
   };
   readonly generate: {
     readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29. Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly generationModels: true;
     readonly models: readonly RankedModel[];
+    readonly needsPrompt: true;
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
     readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
+    readonly referenceModels: readonly RankedModel[];
+    readonly sourceless: true;
     readonly summary: "Make an image from a prompt, or change an image you pass as a reference.";
   };
   readonly layers: {
@@ -754,6 +795,7 @@ export declare const TASKS: {
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Change the light in a photo without regenerating it.";
+    readonly takesMood: true;
   };
   readonly restore: {
     readonly basis: "Hand-ranked. Each mode names what is wrong and has the Model that fixes it; the plain job is Topaz's general restoration. Control Light, a FLUX.2 klein fine-tune at $0.03/MP, brightens dark photos.";
@@ -816,6 +858,7 @@ export declare const TASKS: {
       readonly tier: "balanced";
     }];
     readonly notFor: "A house style kept across images (generate with a look).";
+    readonly oneReference: true;
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Redraw an image in the style of a reference image.";
@@ -886,6 +929,7 @@ export declare const TASKS: {
       readonly tier: "balanced";
     }];
     readonly notFor: "Changing clothes by description (generate with a reference).";
+    readonly oneReference: true;
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Dress a person in a garment from another image.";
@@ -951,6 +995,7 @@ export declare const TASKS: {
   };
   readonly vary: {
     readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29. Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly generationModels: true;
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
     readonly rankedAt: "2026-10-29";
@@ -999,6 +1044,13 @@ interface TaskEnvironment {
   readonly keys: readonly string[];
   /** Models pinned per Task in config (`tasks.<task>.model`). */
   readonly pins?: Readonly<Partial<Record<TaskId, string>>>;
+  /**
+   * Whether the Model can carry the whole request: the refusal when it cannot.
+   * The planner supplies it, so a ranked Model it would refuse is skipped
+   * rather than chosen and then refused. Absent when only the capability
+   * profiles are asked, as in `--describe`.
+   */
+  readonly refusal?: (model: string) => MotifError | undefined;
 }
 /** Which rule fixed the Model. */
 type ChosenBy = "look" | "model" | "pin" | "ranking";
@@ -1027,29 +1079,13 @@ interface TaskUnresolved {
   readonly unblockedBy: readonly Unblocker[];
   /** The key variable that would unblock a Model, when one would. */
   readonly missingKey?: string;
+  /** The values the Model takes, when it refused an aspect, resolution or output format. */
+  readonly accepts?: readonly string[];
+  /** The most images the Model makes, when it refused a count. */
+  readonly limit?: number;
   readonly message: string;
 }
 type TaskResolution = TaskResolved | TaskUnresolved;
-interface ModelProfile {
-  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
-  readonly name: string;
-  readonly capabilities: ReadonlySet<Capability>;
-  /** Key variables the Model needs for any request. */
-  readonly keys: readonly string[];
-  readonly maxReferences: number;
-  /** Aspect ratios the Model accepts. Absent means any. */
-  readonly aspects?: readonly string[];
-  /** Resolutions the Model accepts. Absent means any. */
-  readonly resolutions?: readonly string[];
-  /** Output formats the Model returns, for a text request and an edit.
-   * Absent means any. */
-  readonly outputFormats?: {
-    readonly edit: readonly string[];
-    readonly text: readonly string[];
-  };
-}
-/** The profile for a Model id, or undefined when no registry knows it. */
-export declare function modelProfile(model: string): ModelProfile | undefined;
 /**
  * Choose the Model for a Task. Pure: no I/O, and the prompt is never read.
  *
@@ -1250,13 +1286,23 @@ interface TaskPlan {
   body: Record<string, unknown>;
   /** Prompt after Look and Mood enrichment, when the Task takes one. */
   prompt?: string;
+  /**
+   * The exact pixel size the request asks for. Null when the size is the
+   * Model's own to decide (a ratio with a resolution tier), the source's
+   * (`auto`), or not set by the request.
+   */
+  size: CustomImageSize | null;
+  /**
+   * The Model always runs through fal's queue. `run` also queues a run whose
+   * caller passes `onSubmitted`, or `onProgress` on a generation Model.
+   */
   queued: boolean;
   /** Projected: before the call. */
   cost: ResolvedCost;
   /** The provider carrying the request. */
   provider: "fal";
 }
-interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued"> {
+interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued" | "size"> {
   files: TaskFile[];
   /** Non-file result fields: answer, reasoning, boxes, scores, points, rle, text... */
   data: Record<string, unknown>;
@@ -1350,4 +1396,54 @@ export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
 type MotifEnv = ReturnType<typeof motifEnvSchema.parse>;
 export declare function parseMotifEnv(input?: Record<string, unknown>): MotifEnv;
 export declare function getFalKeyFromEnv(input?: Record<string, unknown>): string | undefined;
-export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };
+/**
+ * How a Model is sized:
+ * - `exact`: Motif asks for an exact width and height from the ratio and tier.
+ * - `preset`: a fal named size (about 1024 px on the long edge); no tier.
+ * - `fixed`: a few fixed sizes chosen by ratio; no tier.
+ * - `model`: Motif sends the ratio and tier and the Model decides the pixels.
+ * - `source`: the output keeps the source's size, scaled by the tier where the
+ *   endpoint takes one.
+ * - `none`: the Model takes no size.
+ */
+type SizingKind = "exact" | "preset" | "fixed" | "model" | "source" | "none";
+interface ModelSizing {
+  readonly kind: SizingKind;
+  /** Tiers the Model accepts. Empty when it takes none. */
+  readonly resolutions: readonly Resolution[];
+  /** The tier sent when none is asked for, where the Model takes tiers. */
+  readonly defaultResolution?: Resolution;
+  /** At ratio 1:1, the size each tier asks for (`exact` Models). */
+  readonly tierSizes?: Readonly<Partial<Record<Resolution, CustomImageSize>>>;
+  /** At ratio 1:1, the size asked for with no tier (`preset` and `fixed`). */
+  readonly size?: CustomImageSize;
+}
+interface ModelProfile {
+  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
+  readonly name: string;
+  readonly capabilities: ReadonlySet<Capability>;
+  /** Key variables the Model needs for any request. */
+  readonly keys: readonly string[];
+  /** Most images one request makes. Absent where no maximum is known. */
+  readonly maxCount?: number;
+  readonly maxReferences: number;
+  /** Aspect ratios the Model accepts. Absent means any. */
+  readonly aspects?: readonly string[];
+  /** Resolutions the Model accepts. Absent means any. */
+  readonly resolutions?: readonly string[];
+  /** Upscale factors the Model takes. Absent where its endpoint states no range. */
+  readonly scaleRange?: ScaleRange;
+  /** Output formats that make one image whatever the count. */
+  readonly singleImageFormats?: readonly string[];
+  /** What a resolution tier means for the Model, in pixels where known. */
+  readonly sizing: ModelSizing;
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
+}
+/** The profile for a Model id, or undefined when no registry knows it. */
+export declare function modelProfile(model: string): ModelProfile | undefined;
+export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type FormatPreset, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type ModelSizing, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type SizingKind, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };

package/dist/index.d.ts

@@ -253,6 +253,11 @@ export declare function validateCreativeDirection(creative: CreativeDirection |
  * are joined with `". "` and closed with a period. With no clauses the sanitized prompt is returned unchanged.
  */
 export declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
+/** The upscale factors an endpoint takes, from its fal OpenAPI schema. */
+interface ScaleRange {
+  max: number;
+  min: number;
+}
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -273,6 +278,7 @@ interface ImageSizeBounds {
   /** Both edges must be multiples of this. Motif uses 16 when absent. */
   multipleOf?: number;
 }
+/** ─── Queue Types ────────────────────────────────────────────── */
 interface JobStatus {
   error?: string;
   logs?: {
@@ -298,20 +304,20 @@ export declare class ImageSizeBoundsError extends Error {
   readonly bounds: ImageSizeBounds;
   constructor(model: string, aspect: AspectRatio, bounds: ImageSizeBounds);
 }
-/** Format presets that set aspect + resolution in one click */
-export declare const FORMAT_PRESETS: Record<string, {
-  label: string;
-  aspect: AspectRatio;
-  resolution?: Resolution;
-}>;
-/**
- * `MotifError` and its coercion helper.
- *
- * Extracted from `server.ts` so `server-tools.ts` can construct errors without
- * importing back into `server.ts` — that import was a dependency cycle. Both
- * `server.ts` and `server-tools.ts` import from here, and `server.ts`
- * re-exports `MotifError` so the package's public surface is unchanged.
- */
+/** A named output format: an aspect, and a resolution when the format needs one. */
+interface FormatPreset {
+  readonly aspect: AspectRatio;
+  /** What the format is for, in a few words. */
+  readonly description: string;
+  /** Short title for pickers. */
+  readonly label: string;
+  readonly resolution?: Resolution;
+  /** The platform's pixel spec, such as "1080×1920", when it publishes one. */
+  readonly size?: string;
+}
+/** Format presets that set aspect + resolution in one click, in display order. */
+export declare const FORMAT_PRESETS: Record<string, FormatPreset>;
+/** `MotifError` and the fal HTTP error mapping. */
 export declare class MotifError extends Error {
   readonly status: number;
   readonly code?: string;
@@ -324,6 +330,14 @@ export declare class MotifError extends Error {
 }
 /** Error code for a fal account that is locked, usually for lack of credit. */
 export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
+/**
+ * Error code for a request that can bill a job and got no clear answer (a
+ * connection error, a timeout, a 5xx, or an unreadable acceptance). fal may
+ * have accepted it, so the caller must not blindly submit it again.
+ */
+export declare const SUBMISSION_UNCERTAIN = "SUBMISSION_UNCERTAIN";
+/** Error code for a fal response whose body was not the JSON it should be. */
+export declare const INVALID_RESPONSE = "INVALID_RESPONSE";
 /**
  * Whether a fal HTTP failure means the account is locked.
  *
@@ -331,6 +345,12 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  * account has run out of credit. Retrying cannot help, and the key is valid.
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
+/**
+ * The option a refused request was stopped on, from either refusal shape: an
+ * `INVALID_OPTION` names it as `details.field`, a `NO_MODEL_AVAILABLE` as
+ * `details.blockedBy`. Undefined when the error names no option.
+ */
+export declare function refusedOption(error: MotifError): string | undefined;
 /**
  * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
  * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
@@ -398,6 +418,23 @@ interface TaskDefinition {
   readonly modes?: readonly TaskMode[];
   /** Best first. Order within a Tier is the order tried at that Tier. */
   readonly models: readonly RankedModel[];
+  /**
+   * Its ranked Models are generation Models: a Look can fix one.
+   */
+  readonly generationModels?: true;
+  /** Refuses a request with no prompt. */
+  readonly needsPrompt?: true;
+  /** Takes its Source and exactly one Reference. */
+  readonly oneReference?: true;
+  /** The ranking used when the request carries References, in place of `models`. */
+  readonly referenceModels?: readonly RankedModel[];
+  /** Makes a new image, so there is no Source to ask for. */
+  readonly sourceless?: true;
+  /**
+   * A Mood is joined to the prompt on its tool Models, and the plain job needs
+   * a prompt or a Mood to say what light to make.
+   */
+  readonly takesMood?: true;
 }
 /** Every Task with a Model. A Task is absent here until it has at least one Model. */
 export declare const TASKS: {
@@ -538,10 +575,14 @@ export declare const TASKS: {
   };
   readonly generate: {
     readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29. Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly generationModels: true;
     readonly models: readonly RankedModel[];
+    readonly needsPrompt: true;
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
     readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
+    readonly referenceModels: readonly RankedModel[];
+    readonly sourceless: true;
     readonly summary: "Make an image from a prompt, or change an image you pass as a reference.";
   };
   readonly layers: {
@@ -754,6 +795,7 @@ export declare const TASKS: {
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Change the light in a photo without regenerating it.";
+    readonly takesMood: true;
   };
   readonly restore: {
     readonly basis: "Hand-ranked. Each mode names what is wrong and has the Model that fixes it; the plain job is Topaz's general restoration. Control Light, a FLUX.2 klein fine-tune at $0.03/MP, brightens dark photos.";
@@ -816,6 +858,7 @@ export declare const TASKS: {
       readonly tier: "balanced";
     }];
     readonly notFor: "A house style kept across images (generate with a look).";
+    readonly oneReference: true;
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Redraw an image in the style of a reference image.";
@@ -886,6 +929,7 @@ export declare const TASKS: {
       readonly tier: "balanced";
     }];
     readonly notFor: "Changing clothes by description (generate with a reference).";
+    readonly oneReference: true;
     readonly rankedAt: "2026-09-16";
     readonly rankedFrom: "hand";
     readonly summary: "Dress a person in a garment from another image.";
@@ -951,6 +995,7 @@ export declare const TASKS: {
   };
   readonly vary: {
     readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29. Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly generationModels: true;
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
     readonly rankedAt: "2026-10-29";
@@ -999,6 +1044,13 @@ interface TaskEnvironment {
   readonly keys: readonly string[];
   /** Models pinned per Task in config (`tasks.<task>.model`). */
   readonly pins?: Readonly<Partial<Record<TaskId, string>>>;
+  /**
+   * Whether the Model can carry the whole request: the refusal when it cannot.
+   * The planner supplies it, so a ranked Model it would refuse is skipped
+   * rather than chosen and then refused. Absent when only the capability
+   * profiles are asked, as in `--describe`.
+   */
+  readonly refusal?: (model: string) => MotifError | undefined;
 }
 /** Which rule fixed the Model. */
 type ChosenBy = "look" | "model" | "pin" | "ranking";
@@ -1027,29 +1079,13 @@ interface TaskUnresolved {
   readonly unblockedBy: readonly Unblocker[];
   /** The key variable that would unblock a Model, when one would. */
   readonly missingKey?: string;
+  /** The values the Model takes, when it refused an aspect, resolution or output format. */
+  readonly accepts?: readonly string[];
+  /** The most images the Model makes, when it refused a count. */
+  readonly limit?: number;
   readonly message: string;
 }
 type TaskResolution = TaskResolved | TaskUnresolved;
-interface ModelProfile {
-  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
-  readonly name: string;
-  readonly capabilities: ReadonlySet<Capability>;
-  /** Key variables the Model needs for any request. */
-  readonly keys: readonly string[];
-  readonly maxReferences: number;
-  /** Aspect ratios the Model accepts. Absent means any. */
-  readonly aspects?: readonly string[];
-  /** Resolutions the Model accepts. Absent means any. */
-  readonly resolutions?: readonly string[];
-  /** Output formats the Model returns, for a text request and an edit.
-   * Absent means any. */
-  readonly outputFormats?: {
-    readonly edit: readonly string[];
-    readonly text: readonly string[];
-  };
-}
-/** The profile for a Model id, or undefined when no registry knows it. */
-export declare function modelProfile(model: string): ModelProfile | undefined;
 /**
  * Choose the Model for a Task. Pure: no I/O, and the prompt is never read.
  *
@@ -1250,13 +1286,23 @@ interface TaskPlan {
   body: Record<string, unknown>;
   /** Prompt after Look and Mood enrichment, when the Task takes one. */
   prompt?: string;
+  /**
+   * The exact pixel size the request asks for. Null when the size is the
+   * Model's own to decide (a ratio with a resolution tier), the source's
+   * (`auto`), or not set by the request.
+   */
+  size: CustomImageSize | null;
+  /**
+   * The Model always runs through fal's queue. `run` also queues a run whose
+   * caller passes `onSubmitted`, or `onProgress` on a generation Model.
+   */
   queued: boolean;
   /** Projected: before the call. */
   cost: ResolvedCost;
   /** The provider carrying the request. */
   provider: "fal";
 }
-interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued"> {
+interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued" | "size"> {
   files: TaskFile[];
   /** Non-file result fields: answer, reasoning, boxes, scores, points, rle, text... */
   data: Record<string, unknown>;
@@ -1350,4 +1396,54 @@ export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
 type MotifEnv = ReturnType<typeof motifEnvSchema.parse>;
 export declare function parseMotifEnv(input?: Record<string, unknown>): MotifEnv;
 export declare function getFalKeyFromEnv(input?: Record<string, unknown>): string | undefined;
-export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };
+/**
+ * How a Model is sized:
+ * - `exact`: Motif asks for an exact width and height from the ratio and tier.
+ * - `preset`: a fal named size (about 1024 px on the long edge); no tier.
+ * - `fixed`: a few fixed sizes chosen by ratio; no tier.
+ * - `model`: Motif sends the ratio and tier and the Model decides the pixels.
+ * - `source`: the output keeps the source's size, scaled by the tier where the
+ *   endpoint takes one.
+ * - `none`: the Model takes no size.
+ */
+type SizingKind = "exact" | "preset" | "fixed" | "model" | "source" | "none";
+interface ModelSizing {
+  readonly kind: SizingKind;
+  /** Tiers the Model accepts. Empty when it takes none. */
+  readonly resolutions: readonly Resolution[];
+  /** The tier sent when none is asked for, where the Model takes tiers. */
+  readonly defaultResolution?: Resolution;
+  /** At ratio 1:1, the size each tier asks for (`exact` Models). */
+  readonly tierSizes?: Readonly<Partial<Record<Resolution, CustomImageSize>>>;
+  /** At ratio 1:1, the size asked for with no tier (`preset` and `fixed`). */
+  readonly size?: CustomImageSize;
+}
+interface ModelProfile {
+  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
+  readonly name: string;
+  readonly capabilities: ReadonlySet<Capability>;
+  /** Key variables the Model needs for any request. */
+  readonly keys: readonly string[];
+  /** Most images one request makes. Absent where no maximum is known. */
+  readonly maxCount?: number;
+  readonly maxReferences: number;
+  /** Aspect ratios the Model accepts. Absent means any. */
+  readonly aspects?: readonly string[];
+  /** Resolutions the Model accepts. Absent means any. */
+  readonly resolutions?: readonly string[];
+  /** Upscale factors the Model takes. Absent where its endpoint states no range. */
+  readonly scaleRange?: ScaleRange;
+  /** Output formats that make one image whatever the count. */
+  readonly singleImageFormats?: readonly string[];
+  /** What a resolution tier means for the Model, in pixels where known. */
+  readonly sizing: ModelSizing;
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
+}
+/** The profile for a Model id, or undefined when no registry knows it. */
+export declare function modelProfile(model: string): ModelProfile | undefined;
+export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type FormatPreset, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type ModelSizing, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type SizingKind, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };