@gobing-ai/knowledge-kit 0.0.23 → 0.0.24

package/plugins/generations/image-gen/presets/formats/daily-news-cover.yaml

@@ -0,0 +1,19 @@
+name: daily-news-cover
+description: Daily AI news episode cover — fixed composition and palette; subject is the only per-run input
+job: cover
+aspectRatio: '21:9'
+width: 1344
+height: 576
+defaultStyle: daily-news
+keywords: [clean composition, high detail, consistent series look]
+outputFilename: 'daily-news-cover.png'
+variables:
+    subject:
+        description: One concrete visual scene for the day's lead story (objects, settings, symbols)
+        default: a glowing network of connected nodes rising above a quiet city at dawn
+template: |-
+    Ultrawide editorial cover illustration for a daily AI news podcast episode.
+    Scene: {{subject | a glowing network of connected nodes rising above a quiet city at dawn}}.
+    Composition: one central focal subject, generous negative space in the upper third, uncluttered background.
+    Color palette: deep navy background with electric blue and warm amber accents.
+    Atmosphere: calm, intelligent, forward-looking.

package/plugins/generations/image-gen/presets/formats/xhs-card.yaml

@@ -0,0 +1,55 @@
+name: xhs-card
+description: >-
+  Xiaohongshu (XHS) knowledge card — 3:4 portrait image-text card with large
+  Chinese headline and short bullet points. Adapted from baoyu-xhs-images
+  (MIT © Jim Liu); see plugins/kk/skills/xhs-images/references/card-layouts.md.
+job: free
+aspectRatio: '3:4'
+width: 1080
+height: 1440
+defaultStyle: xhs-knowledge
+keywords:
+    - xiaohongshu-style
+    - image-text card layout
+    - large-font title (Chinese-friendly)
+    - fresh clean design
+    - flat illustration accents with geometric decorations
+    - crisp legible text hierarchy
+    - professional color grading
+outputFilename: 'card-{{index | 01}}.png'
+variables:
+    role:
+        description: Card role in the series (cover, content, closing)
+        default: content
+    layout:
+        description: Layout name from xhs-images references (see references/card-layouts.md)
+        default: definition
+    headline:
+        description: Short on-card headline (Chinese, ≤ 12 chars recommended)
+        default: 核心概念
+    points:
+        description: 2–4 short on-card bullet points, one per line
+        default: ''
+    subject:
+        description: Visual scene or metaphor illustrated on the card
+        default: clean flat illustration of the core concept
+    language:
+        description: On-card text language
+        default: 简体中文
+    index:
+        description: Card number in the series (zero-padded)
+        default: '01'
+    content:
+        description: Additional context (use --content)
+        default: ''
+template: |-
+    Xiaohongshu-style knowledge card, portrait 3:4, for a card series.
+    Card role: {{role | content}}. Layout: {{layout | definition}}.
+    On-card headline in {{language | 简体中文}}, extra-large bold type: "{{headline}}".
+    Bullet points (short lines, generous line spacing, keep on-card text minimal):
+    {{points}}
+    Visual scene: {{subject | clean flat illustration of the core concept}},
+    rendered as flat illustration accents with subtle geometric decorations.
+    Fresh clean design, strong text hierarchy, comfortable margins, no watermark,
+    no extra UI chrome. 8K quality, crisp details, professional color grading.
+    {{content}}

package/plugins/generations/image-gen/presets/styles/daily-news.yaml

@@ -0,0 +1,9 @@
+name: daily-news
+description: House style for the kk-daily-ai-voice cover series — flat editorial vector, navy/blue/amber
+modifiers: flat editorial vector illustration, bold simple geometric shapes, subtle paper grain, soft even lighting, limited palette
+palette:
+    - { role: background, name: deep navy, hex: '#0B1F3A' }
+    - { role: primary, name: electric blue, hex: '#2D7FF9' }
+    - { role: accent, name: warm amber, hex: '#F5A623' }
+negative: text, letters, words, numbers, captions, watermark, logo, brand marks, flags, real people, recognizable faces, photorealism, clutter
+source: { kind: authored }

package/plugins/generations/image-gen/presets/styles/xhs-knowledge.yaml

@@ -0,0 +1,7 @@
+name: xhs-knowledge
+description: >-
+  Notion-like knowledge card aesthetic for XHS image-text series — simple light
+  background, clean information layout, soft accent colors, rounded card zones.
+  Adapted from baoyu-xhs-images "knowledge card" style guidance (MIT © Jim Liu);
+  see plugins/kk/skills/xhs-images/references/card-layouts.md.
+modifiers: simple clean light background, rounded rectangle card zones, soft pastel accent colors, large legible Chinese typography, generous whitespace, flat geometric decorations, subtle drop shadows, fresh and professional

package/plugins/generations/image-gen/src/index.ts

@@ -9,12 +9,22 @@ import {
     type ImageArtifact,
     type ImageGenMetadata,
     type ImageJobSpec,
+    type ProviderAttempt,
     parseJobSpec,
     readPositions,
 } from './job';
 import { artifactPath, outStemFor } from './paths';
 import { composePrompt, type FormatPreset, loadPresets, type StylePreset } from './presets';
-import { type ImageProvider, type ImageRequest, PROVIDERS, selectProvider } from './providers/types';
+import {
+    classifyProviderError,
+    type ImageProvider,
+    type ImageRequest,
+    type ImageResult,
+    isFallbackEligible,
+    PROVIDERS,
+    resolveFallbackOrder,
+    selectProvider,
+} from './providers/types';
 
 export * from './job';
 export * from './paths';
@@ -44,6 +54,16 @@ function defaultProviderResolver(spec: ImageJobSpec): ImageProvider {
     return registration.create();
 }
 
+/** Build a fallback candidate from the registry; guards registry drift like defaultProviderResolver. */
+function registeredProvider(name: string): ImageProvider {
+    const registration = PROVIDERS[name];
+    if (registration === undefined) {
+        // resolveFallbackOrder rejects unknown names before this runs; this guards drift only.
+        throw new Error(`Provider '${name}' was selected but is missing from the registry`);
+    }
+    return registration.create();
+}
+
 /**
  * Budget cap resolution (R6): the spec value wins over the env, which wins over
  * the compiled default — the repo's flag > env > config > default rule, with
@@ -126,6 +146,35 @@ function composePrompts(
     return [composePrompt(format, style, vars, spec.extra)];
 }
 
+/** Task 0169: validate the illustration anchor plan against the original body before any provider work. */
+function assertAnchorPlan(body: string, positions: string[] | undefined, count: number): void {
+    const ranges: { anchor: string; start: number; end: number }[] = [];
+    for (let index = 0; index < count; index++) {
+        const anchor = positions?.[index];
+        if (anchor === undefined) {
+            throw new Error('Illustration anchor missing from metadata.positions');
+        }
+        const found = anchor === '' ? 0 : body.split(anchor).length - 1;
+        if (found !== 1) {
+            throw new Error(
+                `Illustration anchor must occur exactly once in the source body, found ${found}: '${anchor.slice(0, 50)}'`,
+            );
+        }
+        const start = body.indexOf(anchor);
+        ranges.push({ anchor, start, end: start + anchor.length });
+    }
+    // ponytail: O(n²) pair scan; n ≤ maxImages (default 4), so sorting is not worth it.
+    for (const [i, a] of ranges.entries()) {
+        for (const b of ranges.slice(i + 1)) {
+            if (a.start < b.end && b.start < a.end) {
+                throw new Error(
+                    `Illustration anchors overlap in the source body: '${a.anchor.slice(0, 50)}' and '${b.anchor.slice(0, 50)}'`,
+                );
+            }
+        }
+    }
+}
+
 /**
  * Read validated `Doc[]` input and emit the image-gen `Content` (R1/R3/R6).
  *
@@ -139,7 +188,11 @@ function composePrompts(
 export async function processGeneratorIO(
     inputPath: string,
     outputPath: string,
-    options: { providerResolver?: ProviderResolver } = {},
+    options: {
+        providerResolver?: ProviderResolver;
+        /** D6 0166: builds fallback candidates by name (tests inject stubs); defaults to the registry. */
+        createProvider?: (name: string) => ImageProvider;
+    } = {},
 ): Promise<void> {
     const fs = createNodeFileSystem();
     // voice-gen rule: start clean, and on any failure delete --out plus every
@@ -174,10 +227,44 @@ export async function processGeneratorIO(
                 `Image count ${prompts.length} exceeds the budget cap ${cap} (raise ImageJobSpec.maxImages or KK_IMAGE_MAX_IMAGES)`,
             );
         }
+        if (spec.job === 'illustration') assertAnchorPlan(doc?.body ?? '', positions, prompts.length);
 
         // Selection must succeed (or fail loud naming the provider) even when nothing is spent.
         const resolveProvider: ProviderResolver = options.providerResolver ?? defaultProviderResolver;
-        const provider = resolveProvider(spec);
+        const primary = resolveProvider(spec);
+
+        // D6 (0166): the fallback order is resolved once, before the dry-run branch, so a typo'd
+        // name fails with no spend on both branches. Candidates are created once through the
+        // cached `createProvider` seam; `skipReason` consults candidates only, never the primary.
+        const built = new Map<string, ImageProvider>();
+        const createCandidate = (name: string): ImageProvider => {
+            const cached = built.get(name);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const created =
+                options.createProvider !== undefined ? options.createProvider(name) : registeredProvider(name);
+            built.set(name, created);
+            return created;
+        };
+        const skipReason = (name: string): string | undefined => {
+            const prospect = createCandidate(name);
+            if (!prospect.isAvailable()) {
+                return 'not configured';
+            }
+            if (
+                spec.referenceImages !== undefined &&
+                spec.referenceImages.length > 0 &&
+                !prospect.supportsReferenceImages(prospect.defaultModel())
+            ) {
+                return 'no reference-image support';
+            }
+            return undefined;
+        };
+        const { order, skipped } = resolveFallbackOrder(primary.name, spec.fallback, { skipReason });
+        for (const skip of skipped) {
+            echoError(`WARN image-gen: skipping fallback ${skip.provider} (${skip.reason})`);
+        }
 
         if (process.env.KK_IMAGE_DRY_RUN === '1') {
             // R6: compose every prompt, select the provider, spend nothing, write no image.
@@ -204,23 +291,69 @@ export async function processGeneratorIO(
         // The money-spending branch: one provider call per prompt, bytes written
         // beside `--out` via artifactPath (R1/R3 worded as 0104 R3), written[]
         // tracking keeps failure cleanup live (dead-loop advisory closed here).
+        // D6 (0166): the validate+generate pair rides the fallback loop. `at`
+        // advances stickily — an image that fell to candidate i keeps the later
+        // images there — and failed attempts never consume the budget cap,
+        // which counts produced images only.
         await fs.ensureDir(dirname(outputPath));
         const stem = outStemFor(outputPath, spec.outputStem);
         const artifacts: ImageArtifact[] = [];
         const captions: CaptionEntry[] = [];
+        const attempts: ProviderAttempt[] = [];
+        let at = 0; // sticky index into `order`
+        const generateWithFallback = async (image: number, prompt: string): Promise<ImageResult> => {
+            const start = attempts.length; // this image's failed attempts begin here (R5 summarises the slice)
+            for (;;) {
+                const name = order[at];
+                if (name === undefined) {
+                    // Unreachable: `at` advances only after order[at + 1] was just proven defined.
+                    throw new Error(`image-gen: fallback order exhausted before image ${image} was decided`);
+                }
+                const provider = at === 0 ? primary : createCandidate(name);
+                // spec.model is provider-specific (D6): only the requested provider receives it.
+                const model = at === 0 ? (spec.model ?? provider.defaultModel()) : provider.defaultModel();
+                const request: ImageRequest = {
+                    prompt,
+                    model,
+                    aspectRatio: format.aspectRatio,
+                    ...(spec.referenceImages !== undefined && spec.referenceImages.length > 0
+                        ? { referenceImages: spec.referenceImages }
+                        : {}),
+                };
+                try {
+                    provider.validate?.(request);
+                    return await provider.generate(request);
+                } catch (err: unknown) {
+                    if (spec.fallback === undefined) {
+                        throw err; // D6 R1: strict mode propagates the original error, unwrapped.
+                    }
+                    const cls = classifyProviderError(err);
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (!isFallbackEligible(cls)) {
+                        // D6 R4: a rejected prompt is never re-asked to a second vendor.
+                        throw new Error(
+                            `image-gen: ${provider.name} rejected the prompt (policy): ${message}; fallback does not apply`,
+                        );
+                    }
+                    attempts.push({ image, provider: provider.name, model, errorClass: cls, message });
+                    const next = order[at + 1];
+                    if (next === undefined) {
+                        // D6 R5: every candidate failed — name each with its class, then the last message.
+                        const detail = attempts
+                            .slice(start)
+                            .map((attempt) => `${attempt.provider} (${attempt.errorClass})`)
+                            .join(', ');
+                        throw new Error(`image-gen: all providers failed for image ${image}: ${detail}; ${message}`);
+                    }
+                    echoError(`WARN image-gen: ${provider.name} failed (${cls}): ${message}; falling back to ${next}`);
+                    at += 1;
+                }
+            }
+        };
         let body = doc?.body ?? '';
         for (const [index, prompt] of prompts.entries()) {
-            const request: ImageRequest = {
-                prompt,
-                model: spec.model ?? provider.defaultModel(),
-                aspectRatio: format.aspectRatio,
-                ...(spec.referenceImages && spec.referenceImages.length > 0
-                    ? { referenceImages: spec.referenceImages }
-                    : {}),
-            };
-            provider.validate?.(request);
-            const result = await provider.generate(request);
-            // Illustration: the anchor must occur exactly once before we spend image 1.
+            const result = await generateWithFallback(index + 1, prompt);
+            // Re-check against the spliced body; the pre-spend plan check is assertAnchorPlan (0169).
             let anchor: string | undefined;
             if (spec.job === 'illustration') {
                 anchor = positions?.[index];
@@ -271,6 +404,7 @@ export async function processGeneratorIO(
             images: artifacts,
             ...(spec.job !== 'free' && doc?.id !== undefined ? { sourceDocId: doc.id } : {}),
             ...(captions.length > 0 ? { captions } : {}),
+            ...(attempts.length > 0 ? { attempts } : {}),
         };
         const content = ContentSchema.parse({
             // free/cover: the body is the prompt trail (same as dry run); illustration: the

package/plugins/generations/image-gen/src/job.ts

@@ -1,5 +1,6 @@
 import type { Doc } from '@gobing-ai/kk-core';
 import { z } from 'zod';
+import type { ProviderErrorClass } from './providers/errors';
 
 /**
  * Task 0104 — the frozen `--in` envelope. A plugin's only input channel is the
@@ -25,6 +26,13 @@ export interface ImageJobSpec {
     extra?: string;
     /** 0103 selectProvider's `requested` name. */
     provider?: string;
+    /**
+     * D6 runtime fallback (0165). Absent = strict: one provider, fail fast. `true` = on a
+     * fallback-eligible error retry down AUTO_ORDER (minus NEVER_AUTO). A list = retry in exactly
+     * that order. Name validation lives in resolveFallbackOrder — this file must not import the
+     * provider registry (it pulls in every adapter).
+     */
+    fallback?: true | string[];
     model?: string;
     /** Absolute paths (0105 pass-through). */
     referenceImages?: string[];
@@ -45,6 +53,8 @@ export const ImageJobSpecSchema = z.strictObject({
     vars: z.record(z.string(), z.string()).optional(),
     extra: z.string().optional(),
     provider: z.string().optional(),
+    /** Absent = strict; `true` or a non-empty list of non-empty strings. `false`/`[]` fail so "off" has one spelling. */
+    fallback: z.union([z.literal(true), z.array(z.string().min(1)).min(1)]).optional(),
     model: z.string().optional(),
     referenceImages: z.array(z.string()).optional(),
     count: z.number().int().positive().optional(),
@@ -80,6 +90,24 @@ export interface CaptionEntry {
     anchor: string;
 }
 
+/**
+ * One failed provider try, recorded by the D6 fallback loop (task 0166). The classifier class lives
+ * in `./providers/errors` — a leaf module with no imports — so this file stays clear of the
+ * provider registry (which pulls in every adapter).
+ */
+export interface ProviderAttempt {
+    /** 1-based image number in the run (same scale as `captions[].index` and the `-NN` artefact suffix). */
+    image: number;
+    /** The provider whose validate/generate call failed. */
+    provider: string;
+    /** The model the failed call sent (`spec.model` on the requested provider, else its default). */
+    model: string;
+    /** The 0164 classification that drove the retry decision. */
+    errorClass: ProviderErrorClass;
+    /** The failed call's own error message, unwrapped. */
+    message: string;
+}
+
 /** Typed shape of this plugin's `Content.metadata` (frozen keys, 0104 Design). */
 export interface ImageGenMetadata {
     generator: 'kk:image-gen';
@@ -89,6 +117,8 @@ export interface ImageGenMetadata {
     sourceDocId?: string;
     /** Illustration only: the captions payload. */
     captions?: CaptionEntry[];
+    /** D6 fallback (0166): every failed provider try in attempt order; present only when non-empty. */
+    attempts?: ProviderAttempt[];
     /** Set only when the run spent nothing (R6 dry run). */
     dryRun?: true;
 }

package/plugins/generations/image-gen/src/providers/errors.ts

@@ -0,0 +1,91 @@
+/**
+ * Provider error classifier for image-gen runtime fallback (task 0164, feature D6).
+ *
+ * Leaf module — no imports, like `timeouts.ts`. `types.ts` builds the `PROVIDERS` registry from
+ * value imports of every adapter, so anything a provider needs outside that cycle must live in its
+ * own leaf; task 0166's retry loop (and any adapter later) can import this one safely.
+ *
+ * The adapters throw plain `Error`s with inconsistent messages: some carry a status
+ * (`seedream HTTP 401: …`, `MiniMax API error (429): …`, `Google API error (403): …`,
+ * `HuggingFace model loading (HTTP 503): …`), some carry none (`OpenAI API error: <body>`),
+ * some name a missing key (`… requires ARK_API_KEY`), and request timeouts abort through
+ * `AbortSignal` (see `timeouts.ts`) as DOMExceptions named `TimeoutError`/`AbortError`. Rather
+ * than retyping all 13 adapters to a typed error (rejected in the task Q&A), the classifier reads
+ * `err.name` plus the message, parsing statuses from the three shapes in use: `(NNN)`, `HTTP NNN`,
+ * and a trailing `: NNN`. Test fixtures copy real adapter throw strings, so wording drift in an
+ * adapter shows up as a test to update.
+ *
+ * First matching row wins, policy first: content-policy rejections often arrive as HTTP 400/403,
+ * and they must never trigger a fallback (D6 R4). `unknown` stays fallback-eligible — most
+ * unknowns are provider-specific request constraints (validate() size/ratio rules, "no image
+ * data") another provider may satisfy (task Q&A).
+ */
+
+/** The retry decision classes the D6 fallback loop (0166) acts on. */
+export type ProviderErrorClass = 'auth' | 'quota' | 'transient' | 'policy' | 'unknown';
+
+/** Content-policy / safety / moderation rejections — checked first, they often arrive as 400/403. */
+const POLICY_RE = /content[_ -]?policy|moderation|safety|sensitive|inappropriate|violat|blocked/i;
+/** Credential wording; 401/403 statuses are checked separately. */
+const AUTH_RE = /api[_ -]?key|unauthori[sz]ed|authenticat|forbidden|requires [A-Z_]+|is required/i;
+/** Quota / spend / rate-limit wording; 402/429 statuses are checked separately. */
+const QUOTA_RE = /quota|rate[_ -]?limit|insufficient|balance|billing|exceeded|too many requests/i;
+/** Network / timeout wording (the `err.name` TimeoutError/AbortError check is separate). */
+const TRANSIENT_RE = /timed? ?out|ECONNRESET|ETIMEDOUT|ECONNREFUSED|fetch failed|socket|model loading/i;
+
+/** Abort names produced by `AbortSignal.timeout` and manual aborts (DOMException in Bun and Node). */
+const TRANSIENT_NAMES: ReadonlySet<string> = new Set(['TimeoutError', 'AbortError']);
+
+/**
+ * HTTP statuses carried by the message, parsed from the three shapes adapters use: `(NNN)`
+ * (`MiniMax API error (429): …`), `HTTP NNN` (`seedream HTTP 401: …`), and a trailing `: NNN`
+ * (`Failed to download image from MiniMax: 401`). Response bodies and provider-specific codes are
+ * deliberately not statuses.
+ */
+function statusesIn(message: string): number[] {
+    const statuses: number[] = [];
+    for (const match of message.matchAll(/\((\d{3})\)|HTTP\s+(\d{3})\b|:\s*(\d{3})\s*$/gi)) {
+        const status = match[1] ?? match[2] ?? match[3];
+        if (status !== undefined) statuses.push(Number(status));
+    }
+    return statuses;
+}
+
+/** Duck-typed read of `name`/`message`; never throws, and non-object values have neither. */
+function partsOf(err: unknown): { readonly name: string; readonly message: string } {
+    if (typeof err !== 'object' || err === null) return { name: '', message: '' };
+    const candidate = err as { readonly name?: unknown; readonly message?: unknown };
+    return {
+        name: typeof candidate.name === 'string' ? candidate.name : '',
+        message: typeof candidate.message === 'string' ? candidate.message : '',
+    };
+}
+
+/**
+ * Classify a thrown value for the D6 fallback decision. Pure: no I/O, no env, no provider imports.
+ * Row order is load-bearing — policy → auth → quota → transient → unknown — and the function never
+ * throws: non-object values and objects without string `name`/`message` classify as `unknown`.
+ */
+export function classifyProviderError(err: unknown): ProviderErrorClass {
+    const parts = partsOf(err);
+    const statuses = statusesIn(parts.message);
+    if (POLICY_RE.test(parts.message)) return 'policy';
+    if (statuses.some((status) => status === 401 || status === 403) || AUTH_RE.test(parts.message)) return 'auth';
+    if (statuses.some((status) => status === 402 || status === 429) || QUOTA_RE.test(parts.message)) return 'quota';
+    if (
+        TRANSIENT_NAMES.has(parts.name) ||
+        statuses.some((status) => status === 408 || (status >= 500 && status <= 599)) ||
+        TRANSIENT_RE.test(parts.message)
+    ) {
+        return 'transient';
+    }
+    return 'unknown';
+}
+
+/**
+ * Whether the D6 fallback loop may move to the next provider after this class. Only `policy` is
+ * never eligible: a rejected prompt must not be re-asked to a second vendor (D6 R4 / AC1).
+ */
+export function isFallbackEligible(cls: ProviderErrorClass): boolean {
+    return cls !== 'policy';
+}

package/plugins/generations/image-gen/src/providers/types.ts

@@ -69,6 +69,14 @@ export interface ImageProvider {
     generate(req: ImageRequest): Promise<ImageResult>;
 }
 
+/**
+ * Provider error classification for the runtime fallback loop (task 0164; consumed by 0166).
+ * Declared in `./errors`, a leaf module like `./timeouts`, so adapters can classify throw sites
+ * later without entering the registry import cycle.
+ */
+export type { ProviderErrorClass } from './errors';
+export { classifyProviderError, isFallbackEligible } from './errors';
+
 /** Injection seam for tests — mirrors `VoiceboxClientOptions.fetch` (voice-gen). */
 /**
  * Default per-request timeout for every image-gen provider HTTP call. Defined in `./timeouts` (a
@@ -294,3 +302,74 @@ export function selectProvider(
         .join('; ');
     throw new Error(`No image provider is configured. Credentials wanted — ${wanted}`);
 }
+
+/**
+ * D6 runtime fallback (task 0165) — the envelope's `fallback` field as the schema admits it:
+ * absent (strict), `true` (AUTO_ORDER), or an explicit ordered list. Shape-only; name validation
+ * happens in {@link resolveFallbackOrder}, because `job.ts` must not import this registry.
+ */
+export type FallbackSpec = true | readonly string[] | undefined;
+
+/** The ordered candidate list the retry loop (task 0166) walks, plus every dropped candidate. */
+export interface FallbackOrder {
+    /** Invariant: non-empty, no duplicates, `order[0] === requested`. */
+    order: string[];
+    /** Candidates dropped because `skipReason` returned a string; never contains `requested`. */
+    skipped: { provider: string; reason: string }[];
+}
+
+/**
+ * Turn the envelope's `fallback` field into the candidate order for the retry loop (task 0166).
+ * Pure: availability and reference support arrive through `skipReason`, which 0166 builds from
+ * provider instances — nothing here constructs or calls a provider. Behaviour:
+ *
+ * - absent → `[requested]` (strict, today's fail-fast).
+ * - `true` → `requested`, then AUTO_ORDER minus NEVER_AUTO minus `requested`, in AUTO_ORDER order.
+ * - list → `requested`, then the list in the given order, deduped and minus `requested`.
+ *
+ * An unknown name in a list throws before any provider call, because a typo must fail loud, not
+ * silently shrink the chain. An explicitly listed NEVER_AUTO provider is allowed: NEVER_AUTO
+ * governs automatic choice only (mirrors selectProvider's explicit pin rule). `skipReason` is
+ * consulted for candidates only — never `requested`, so `order` always keeps the already-selected
+ * provider first.
+ */
+export function resolveFallbackOrder(
+    requested: string,
+    fallback: FallbackSpec,
+    options?: { skipReason?: (name: string) => string | undefined },
+): FallbackOrder {
+    if (fallback === undefined) {
+        return { order: [requested], skipped: [] };
+    }
+
+    let candidates: readonly string[];
+    if (fallback === true) {
+        candidates = AUTO_ORDER.filter((name) => !NEVER_AUTO.has(name) && name !== requested);
+    } else {
+        const names = Object.keys(PROVIDERS).sort();
+        const seen = new Set<string>([requested]);
+        const listed: string[] = [];
+        for (const name of fallback) {
+            if (PROVIDERS[name] === undefined) {
+                throw new Error(`Unknown fallback provider '${name}'. Valid providers: ${names.join(', ')}`);
+            }
+            if (!seen.has(name)) {
+                seen.add(name);
+                listed.push(name);
+            }
+        }
+        candidates = listed;
+    }
+
+    const order = [requested];
+    const skipped: { provider: string; reason: string }[] = [];
+    for (const name of candidates) {
+        const reason = options?.skipReason?.(name);
+        if (reason === undefined) {
+            order.push(name);
+        } else {
+            skipped.push({ provider: name, reason });
+        }
+    }
+    return { order, skipped };
+}