@gobing-ai/ts-ai-decision 0.5.29 → 0.5.32

package/src/hub.ts

@@ -21,6 +21,7 @@ import type {
     DecisionType,
     JevEntry,
     JevQuestion,
+    MakerRef,
 } from './types';
 
 /**
@@ -40,6 +41,56 @@ export const DEFAULT_MIN_CONFIDENCE = 0.7;
 /** Hub default when neither the per-call options, the decision nor the catalog names a maker. */
 export const DEFAULT_MAKER = 'typesafe';
 
+/** Upper bound on a carried error message, in characters (ADR-040). */
+export const DECISION_ERROR_MESSAGE_MAX = 500;
+
+/**
+ * The caught failure, carried on a fallback result so a consumer can persist it (Spur stores
+ * `decision_logs.error`). Only `name` and `message`: a stack, a `cause` chain or the failing
+ * request would leak prompt text and internals into logs.
+ */
+export interface DecisionErrorInfo {
+    readonly name: string;
+    readonly message: string;
+}
+
+/**
+ * Reduce a thrown value to {@link DecisionErrorInfo}. Subclasses of `DecisionError` set their own
+ * `name`; a subclass that does not is named by its constructor rather than by `'Error'`.
+ */
+function toErrorInfo(error: unknown): DecisionErrorInfo {
+    if (!(error instanceof Error)) {
+        return { name: 'NonError', message: String(error).slice(0, DECISION_ERROR_MESSAGE_MAX) };
+    }
+    const named = error.name !== 'Error' ? error.name : (error.constructor?.name ?? error.name);
+    return { name: named, message: error.message.slice(0, DECISION_ERROR_MESSAGE_MAX) };
+}
+
+/**
+ * One maker's attempt inside a chain: what it was, how it ended, and how long it took. Present only
+ * when more than one maker was tried, so a single-name decision's result is unchanged.
+ */
+export interface DecisionAttempt {
+    readonly maker: string;
+    readonly reason: DecisionResultBase['reason'];
+    readonly durationMs: number;
+    readonly error?: DecisionErrorInfo;
+}
+
+/**
+ * What a shadow maker did with the same request. Observed only: it rides beside the served answer and
+ * never changes it (ADR-040). `value` is the answer the shadow itself produced, so it is absent when
+ * the shadow fell back.
+ */
+export interface ShadowOutcome {
+    readonly maker: string;
+    readonly value?: string | number | boolean;
+    readonly confidence: number | null;
+    readonly reason: DecisionResultBase['reason'];
+    readonly durationMs: number;
+    readonly error?: DecisionErrorInfo;
+}
+
 /** Shared envelope of every {@link DecisionResult} variant. */
 export interface DecisionResultBase {
     readonly id: string;
@@ -51,6 +102,12 @@ export interface DecisionResultBase {
     /** Registry name of the maker that was selected. */
     readonly maker: string;
     readonly durationMs: number;
+    /** The caught failure. Present only for `no-backend`, `timeout` and `error`. */
+    readonly error?: DecisionErrorInfo;
+    /** Every maker tried, in order. Present only when a chain tried more than one. */
+    readonly attempts?: readonly DecisionAttempt[];
+    /** The shadow's outcome. Present only when the decision or the call named a shadow. */
+    readonly shadow?: ShadowOutcome;
 }
 
 /** The fallback-guaranteed result of one `decide` call, shaped by the decision type. */
@@ -79,8 +136,12 @@ export interface DecisionDescriptor {
     readonly fallback: string | number | boolean;
     /** decision → catalog defaults → {@link DEFAULT_MIN_CONFIDENCE}. */
     readonly minConfidence: number;
-    /** decision → catalog defaults → hub defaultMaker. */
+    /** First name of the effective chain (decision → catalog defaults → hub defaultMaker). */
     readonly maker: string;
+    /** The full effective chain; a single name yields a one-element list. */
+    readonly makers: readonly string[];
+    /** The decision's configured shadow; a per-call shadow is not visible to `describe`. */
+    readonly shadow?: string;
     /** decision → catalog defaults; absent when neither declares one. */
     readonly model?: string;
 }
@@ -97,8 +158,49 @@ export interface DecisionHubOptions {
 
 /** Per-call options for {@link DecisionHub.decide}. */
 export interface DecideOptions {
-    /** Per-call maker name; wins over the decision's, the catalog's and the hub default. */
-    readonly maker?: string;
+    /**
+     * Per-call maker name or ordered fallback chain (ADR-040); wins over the decision's, the
+     * catalog's and the hub default. Validated before any backend call.
+     */
+    readonly maker?: MakerRef;
+    /** Per-call shadow maker (ADR-040); wins over the decision's. Validated before any backend call. */
+    readonly shadow?: string;
+}
+
+/**
+ * One maker's outcome: its result, whether the chain should advance past it, and the answer it
+ * actually produced (absent when it fell back), which a shadow reports as its own value.
+ */
+interface AskOutcome {
+    result: DecisionResult;
+    failed: boolean;
+    answered?: string | number | boolean;
+}
+
+/** The one-question request handed to a maker — the shape of `DecisionMaker.ask`. */
+interface AskRequest {
+    state: DecisionState;
+    questions: Record<string, Question>;
+    model?: string;
+}
+
+/**
+ * Normalize a {@link MakerRef} to an ordered chain. Empty and duplicate lists are caller errors
+ * here, not at load: the loader's schema already rejects them in a catalog.
+ */
+function toChain(ref: MakerRef): readonly string[] {
+    if (typeof ref === 'string') return [ref];
+    if (ref.length === 0) {
+        throw new UnknownDecisionMakerError('A maker chain must name at least one maker', '');
+    }
+    const seen = new Set<string>();
+    for (const name of ref) {
+        if (seen.has(name)) {
+            throw new UnknownDecisionMakerError(`Maker chain repeats '${name}'`, name);
+        }
+        seen.add(name);
+    }
+    return [...ref];
 }
 
 /** One registered decision plus the catalog defaults it loaded under. */
@@ -176,20 +278,24 @@ export class DecisionHub {
 
     /**
      * Register every decision of an already-loaded catalog. All-or-nothing: a
-     * duplicate decision id or an unregistered maker name (decision or
-     * `defaults.maker`) throws {@link DecisionCatalogError} and registers
+     * duplicate decision id or an unregistered maker name (any chain name of a
+     * decision or `defaults.maker`, or a decision `shadow`) throws
+     * {@link DecisionCatalogError} and registers
      * nothing from the offending catalog.
      */
     load(catalog: DecisionCatalog): void {
         const defaultsMaker = catalog.defaults.maker;
-        if (defaultsMaker !== undefined && !this.registry.has(defaultsMaker)) {
-            throw new DecisionCatalogError(
-                `Catalog "${catalog.source}" defaults.maker '${defaultsMaker}' is not registered in the hub registry ` +
-                    `(registered: ${this.registry.names().join(', ') || 'none'})`,
-                catalog.source,
-                undefined,
-                'maker',
-            );
+        const defaultsChain = defaultsMaker === undefined ? undefined : toChain(defaultsMaker);
+        for (const name of defaultsChain ?? []) {
+            if (!this.registry.has(name)) {
+                throw new DecisionCatalogError(
+                    `Catalog "${catalog.source}" defaults.maker '${name}' is not registered in the hub registry ` +
+                        `(registered: ${this.registry.names().join(', ') || 'none'})`,
+                    catalog.source,
+                    undefined,
+                    'maker',
+                );
+            }
         }
         // Stage first, commit only when every decision passed the cross-catalog checks.
         const staged: RegisteredDecision[] = [];
@@ -204,13 +310,24 @@ export class DecisionHub {
                     'id',
                 );
             }
-            if (definition.maker !== undefined && !this.registry.has(definition.maker)) {
+            for (const name of definition.maker === undefined ? [] : toChain(definition.maker)) {
+                if (!this.registry.has(name)) {
+                    throw new DecisionCatalogError(
+                        `Decision "${id}" in catalog "${catalog.source}" names maker '${name}' that is not ` +
+                            `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`,
+                        catalog.source,
+                        id,
+                        'maker',
+                    );
+                }
+            }
+            if (definition.shadow !== undefined && !this.registry.has(definition.shadow)) {
                 throw new DecisionCatalogError(
-                    `Decision "${id}" in catalog "${catalog.source}" names maker '${definition.maker}' that is not ` +
+                    `Decision "${id}" in catalog "${catalog.source}" names shadow '${definition.shadow}' that is not ` +
                         `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`,
                     catalog.source,
                     id,
-                    'maker',
+                    'shadow',
                 );
             }
             staged.push({ definition, defaults: catalog.defaults });
@@ -236,6 +353,7 @@ export class DecisionHub {
     /** Pure read of one decision's served contract; throws UnknownDecisionError for an unknown id. */
     describe(id: string): DecisionDescriptor {
         const { definition, defaults } = this.mustGet(id);
+        const chain = this.effectiveChain(definition, defaults);
         const model = definition.model ?? defaults.model;
         return {
             id: definition.id,
@@ -246,7 +364,9 @@ export class DecisionHub {
             criteria: definition.criteria,
             fallback: definition.fallback,
             minConfidence: effectiveMinConfidence(definition, defaults),
-            maker: this.effectiveMakerName(definition, defaults),
+            maker: chain[0] ?? DEFAULT_MAKER,
+            makers: chain,
+            ...(definition.shadow !== undefined ? { shadow: definition.shadow } : {}),
             ...(model !== undefined ? { model } : {}),
         };
     }
@@ -254,8 +374,9 @@ export class DecisionHub {
     /**
      * Serve one decision with a fallback-guaranteed answer. Resolves the input,
      * renders exactly one Jev question keyed by the decision id, selects the
-     * maker by name (per call → decision → catalog defaults → hub default) and
-     * issues a single `maker.ask`. Backend construction, transport, timeout,
+     * maker chain (per call → decision → catalog defaults → hub default) and
+     * asks its makers in order until one answers, with an optional shadow asked
+     * beside it (ADR-040). Backend construction, transport, timeout,
      * invalid answers and low confidence all resolve to the declared fallback;
      * only caller mistakes throw, before any backend call.
      */
@@ -264,14 +385,26 @@ export class DecisionHub {
         const { definition, defaults } = this.mustGet(id); // UnknownDecisionError — caller error
         const params = resolveDecisionInput(definition, input); // DecisionInputError — caller error
 
-        const makerName = options.maker ?? definition.maker ?? defaults.maker ?? this.defaultMaker;
-        if (!this.registry.has(makerName)) {
-            // Reachable only for a per-call name: catalog and hub default names are checked at
-            // load/construct. It is a caller error, thrown before any backend interaction.
+        const chain = options.maker === undefined ? this.effectiveChain(definition, defaults) : toChain(options.maker);
+        for (const name of chain) {
+            // Reachable only for a per-call chain: catalog and hub default names are checked at
+            // load/construct. A caller error, thrown before any backend interaction.
+            if (!this.registry.has(name)) {
+                throw new UnknownDecisionMakerError(
+                    `Decision "${id}" was asked on maker '${name}' that is not registered in the hub registry ` +
+                        `(registered: ${this.registry.names().join(', ') || 'none'})`,
+                    name,
+                );
+            }
+        }
+
+        const shadowName = options.shadow ?? definition.shadow;
+        if (shadowName !== undefined && !this.registry.has(shadowName)) {
+            // Same caller-error rule as a per-call maker name: before any backend interaction.
             throw new UnknownDecisionMakerError(
-                `Decision "${id}" was asked on maker '${makerName}' that is not registered in the hub registry ` +
+                `Decision "${id}" was asked with shadow '${shadowName}' that is not registered in the hub registry ` +
                     `(registered: ${this.registry.names().join(', ') || 'none'})`,
-                makerName,
+                shadowName,
             );
         }
 
@@ -283,6 +416,97 @@ export class DecisionHub {
             ...(model !== undefined ? { model } : {}),
         };
 
+        // Shadow rule (ADR-040): start the shadow on the SAME request object, without awaiting it, so
+        // both paths run concurrently and latency is the slower of the two. It never rejects `decide`
+        // and never touches a served field — a rejected or failed ask maps to its own outcome.
+        const shadowStart = this.now();
+        const shadowTask: Promise<AskOutcome> | undefined =
+            shadowName === undefined
+                ? undefined
+                : this.askOne(shadowName, definition, defaults, request, shadowStart).then(
+                      (settled): AskOutcome => settled,
+                      (error: unknown): AskOutcome => ({
+                          result: this.fallbackResult(
+                              definition,
+                              shadowName,
+                              'error',
+                              null,
+                              shadowStart,
+                              undefined,
+                              toErrorInfo(error),
+                          ),
+                          failed: true,
+                      }),
+                  );
+
+        // Chain rule (ADR-040): ask makers in order and stop at the first that did not fail as a
+        // backend — `accepted` and `low-confidence` both answer. Every maker after the answering one
+        // stays unresolved, so its lazy factory never runs.
+        const attempts: DecisionAttempt[] = [];
+        let last: { result: DecisionResult; failed: boolean } | undefined;
+        for (const makerName of chain) {
+            const attemptStart = this.now();
+            last = await this.askOne(makerName, definition, defaults, request, attemptStart);
+            attempts.push({
+                maker: makerName,
+                reason: last.result.reason,
+                durationMs: this.now() - attemptStart,
+                ...(last.result.error !== undefined ? { error: last.result.error } : {}),
+            });
+            if (!last.failed) break;
+        }
+
+        // `toChain` rejects an empty list, so the loop always ran at least once.
+        const final = last?.result;
+        if (final === undefined) {
+            throw new UnknownDecisionMakerError(`Decision "${id}" has no maker to ask`, id);
+        }
+        // `durationMs` covers the whole call, shadow wait included; a single-maker call without a
+        // shadow keeps its exact previous shape.
+        const shadowOutcome = shadowTask === undefined ? undefined : this.toShadowOutcome(await shadowTask);
+        return {
+            ...final,
+            durationMs: this.now() - start,
+            ...(attempts.length > 1 ? { attempts } : {}),
+            ...(shadowOutcome !== undefined ? { shadow: shadowOutcome } : {}),
+        };
+    }
+
+    /**
+     * Project a shadow's own result onto {@link ShadowOutcome}. `value` is carried only when the shadow
+     * actually answered — a served-model answer or a low-confidence one — never its declared fallback.
+     */
+    private toShadowOutcome(outcome: AskOutcome): ShadowOutcome {
+        const { result } = outcome;
+        const answered = result.source === 'model' || result.reason === 'low-confidence';
+        return {
+            maker: result.maker,
+            ...(answered && outcome.answered !== undefined ? { value: outcome.answered } : {}),
+            confidence: result.confidence,
+            reason: result.reason,
+            durationMs: result.durationMs,
+            ...(result.error !== undefined ? { error: result.error } : {}),
+        };
+    }
+
+    /**
+     * Ask one maker and classify its outcome. `failed` is true exactly for `no-backend`, `timeout`
+     * and `error` — the reasons a chain advances past (ADR-040); `accepted` and `low-confidence`
+     * answer, so the chain stops there.
+     */
+    private async askOne(
+        makerName: string,
+        definition: DecisionDefinition,
+        defaults: CatalogDefaults,
+        request: AskRequest,
+        start: number,
+    ): Promise<AskOutcome> {
+        const outcome = (result: DecisionResult, answered?: string | number | boolean): AskOutcome => ({
+            result,
+            failed: result.reason === 'no-backend' || result.reason === 'timeout' || result.reason === 'error',
+            ...(answered !== undefined ? { answered } : {}),
+        });
+
         // The one auditable try/catch for steps 4–5: a resolve failure is a construction
         // failure (no-backend); ask failures map per the error taxonomy. Neither rejects.
         let inAsk = false;
@@ -296,17 +520,33 @@ export class DecisionHub {
             validateAnswers(request.questions, answers);
             const answer: Answer | undefined = answers[definition.id];
             if (answer === undefined || answer.kind !== definition.type) {
-                return this.fallbackResult(definition, makerName, 'error', null, start);
+                // Nothing was thrown here, so the failure is synthesized: every `error` reason
+                // must carry a cause a consumer can log (ADR-040).
+                return outcome(
+                    this.fallbackResult(definition, makerName, 'error', null, start, undefined, {
+                        name: 'DecisionBackendError',
+                        message: `Maker returned no answer of type ${definition.type} for "${definition.id}"`,
+                    }),
+                );
             }
             const observed = observedAnswer(answer);
+            const answered =
+                answer.kind === 'choice'
+                    ? answer.label
+                    : answer.kind === 'score'
+                      ? answer.score
+                      : answer.probability >= 0.5;
             if (observed.confidence < effectiveMinConfidence(definition, defaults)) {
-                return this.fallbackResult(
-                    definition,
-                    makerName,
-                    'low-confidence',
-                    observed.confidence,
-                    start,
-                    observed.probability,
+                return outcome(
+                    this.fallbackResult(
+                        definition,
+                        makerName,
+                        'low-confidence',
+                        observed.confidence,
+                        start,
+                        observed.probability,
+                    ),
+                    answered,
                 );
             }
             const base = {
@@ -319,16 +559,19 @@ export class DecisionHub {
             };
             switch (answer.kind) {
                 case 'choice':
-                    return { ...base, type: 'choice', value: answer.label };
+                    return outcome({ ...base, type: 'choice', value: answer.label }, answered);
                 case 'score':
-                    return { ...base, type: 'score', value: answer.score };
+                    return outcome({ ...base, type: 'score', value: answer.score }, answered);
                 case 'noul':
-                    return {
-                        ...base,
-                        type: 'noul',
-                        value: answer.probability >= 0.5,
-                        probability: answer.probability,
-                    };
+                    return outcome(
+                        {
+                            ...base,
+                            type: 'noul',
+                            value: answer.probability >= 0.5,
+                            probability: answer.probability,
+                        },
+                        answered,
+                    );
             }
         } catch (error) {
             const reason =
@@ -337,13 +580,16 @@ export class DecisionHub {
                     : error instanceof DecisionTimeoutError
                       ? 'timeout'
                       : 'error';
-            return this.fallbackResult(definition, makerName, reason, null, start);
+            return outcome(
+                this.fallbackResult(definition, makerName, reason, null, start, undefined, toErrorInfo(error)),
+            );
         }
     }
 
-    /** Maker-name precedence for discovery results: decision → catalog defaults → hub default. */
-    private effectiveMakerName(definition: DecisionDefinition, defaults: CatalogDefaults): string {
-        return definition.maker ?? defaults.maker ?? this.defaultMaker;
+    /** Maker-chain precedence for discovery results: decision → catalog defaults → hub default. */
+    private effectiveChain(definition: DecisionDefinition, defaults: CatalogDefaults): readonly string[] {
+        const ref = definition.maker ?? defaults.maker;
+        return ref === undefined ? [this.defaultMaker] : toChain(ref);
     }
 
     private mustGet(id: string): RegisteredDecision {
@@ -370,6 +616,7 @@ export class DecisionHub {
         confidence: number | null,
         start: number,
         probability?: number,
+        error?: DecisionErrorInfo,
     ): DecisionResult {
         const base = {
             id: definition.id,
@@ -378,6 +625,7 @@ export class DecisionHub {
             reason,
             maker: makerName,
             durationMs: this.now() - start,
+            ...(error !== undefined ? { error } : {}),
         };
         switch (definition.type) {
             case 'choice':

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './agent-driver';
 export * from './catalog';
 export * from './errors';
 export * from './hub';
@@ -5,3 +6,4 @@ export * from './params';
 export * from './registry';
 export * from './schema';
 export * from './types';
+export * from './typesafe-driver';

package/src/registry.ts

@@ -1,17 +1,28 @@
-import { createDecisionMaker, type DecisionMaker, type DecisionMakerOptions } from '@gobing-ai/ts-ai-runner';
+import {
+    createDecisionMaker,
+    type DecisionMaker,
+    type DecisionMakerOptions,
+    resolveApiKey,
+} from '@gobing-ai/ts-ai-runner';
 import { createFmDriver, type FmDriverOptions } from '@gobing-ai/ts-decision-fm';
 import { createLayaDriver, type LayaDriverOptions } from '@gobing-ai/ts-laya-mlx';
+import { type AgentDriverOptions, createAgentDriver } from './agent-driver';
 import { DecisionRegistryError, UnknownDecisionMakerError } from './errors';
+import { createTypesafeDriver } from './typesafe-driver';
 
 /** A maker, or a lazy factory for one (sync or async). Factories run on first `resolve` and are memoised on success. */
 export type MakerSource = DecisionMaker | (() => DecisionMaker | Promise<DecisionMaker>);
 
-/** Options for the three built-in makers pre-registered by {@link DecisionMakerRegistry} (task 0091 R2). */
+/** Options for the four built-in makers pre-registered by {@link DecisionMakerRegistry} (task 0091 R2, task 0115 R8). */
 export interface BuiltinMakerOptions {
     /** Forwarded to `createDecisionMaker` for every built-in (env, apiKey, baseURL, timeoutMs, ...). */
     readonly makerOptions?: Omit<DecisionMakerOptions, 'driver' | 'backend' | 'model'>;
-    /** Driver options for the bundled local drivers; the fm platform check runs at first resolve, not registration. */
-    readonly driverOptions?: { readonly 'fm-local'?: FmDriverOptions; readonly 'laya-local'?: LayaDriverOptions };
+    /** Driver options for the bundled drivers; the fm platform check runs at first resolve, not registration. */
+    readonly driverOptions?: {
+        readonly 'fm-local'?: FmDriverOptions;
+        readonly 'laya-local'?: LayaDriverOptions;
+        readonly 'llm-agent'?: AgentDriverOptions;
+    };
 }
 
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -31,11 +42,29 @@ export class DecisionMakerRegistry {
         { source: MakerSource; maker?: DecisionMaker; pending?: Promise<DecisionMaker> }
     >();
 
-    /** Pre-registers `typesafe`, `fm-local` and `laya-local` unless `builtins: false`. */
+    /** Pre-registers `typesafe`, `fm-local`, `laya-local` and `llm-agent` unless `builtins: false`. */
     constructor(options?: { builtins?: BuiltinMakerOptions | false }) {
         if (options?.builtins === false) return;
         const { makerOptions = {}, driverOptions = {} } = options?.builtins ?? {};
-        this.register('typesafe', () => createDecisionMaker({ backend: 'typesafe', ...makerOptions }));
+        // The driver lives here now (ADR-039), so the built-in no longer routes through the
+        // deprecated dynamic-import bridge. A missing key still throws inside this lazy factory,
+        // before any request, so the hub keeps reporting `reason: 'no-backend'`.
+        //
+        // `Omit<>` over an index-signature option bag collapses every declared field to `unknown`,
+        // so the bag is read back through its own type here — same object, same runtime values.
+        const transportOptions = makerOptions as DecisionMakerOptions;
+        this.register('typesafe', () =>
+            createDecisionMaker({
+                driver: createTypesafeDriver({
+                    apiKey: resolveApiKey(transportOptions),
+                    baseURL: transportOptions.baseURL,
+                    timeoutMs: transportOptions.timeoutMs,
+                    maxRetries: transportOptions.maxRetries,
+                    fetch: transportOptions.fetch,
+                }),
+                ...makerOptions,
+            }),
+        );
         this.register('fm-local', () =>
             createDecisionMaker({ driver: createFmDriver(driverOptions['fm-local'] ?? {}), ...makerOptions }),
         );
@@ -51,6 +80,11 @@ export class DecisionMakerRegistry {
                 ...makerOptions,
             });
         });
+        // Lazy like the rest: `names()`/`has()` construct nothing, and agent detection
+        // runs inside the first `ask`, so an unavailable agent surfaces as a fallback.
+        this.register('llm-agent', () =>
+            createDecisionMaker({ driver: createAgentDriver(driverOptions['llm-agent'] ?? {}), ...makerOptions }),
+        );
     }
 
     /** Register a maker or factory under `name`; chains. Throws on a bad or already-registered name. */

package/src/schema.ts

@@ -15,6 +15,24 @@ export const PARAM_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
 /** Maker registry names: lowercase kebab-case. */
 export const MAKER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
+/** One maker name, or an ordered fallback chain of distinct names (ADR-040). */
+const MakerRefSchema = z.union([
+    z.string().regex(MAKER_NAME_PATTERN),
+    z
+        .array(z.string().regex(MAKER_NAME_PATTERN))
+        .min(1)
+        .superRefine((names, ctx) => {
+            const seen = new Set<string>();
+            for (const name of names) {
+                if (seen.has(name)) {
+                    ctx.addIssue({ code: 'custom', message: `maker list repeats '${name}'` });
+                    return;
+                }
+                seen.add(name);
+            }
+        }),
+]);
+
 const JsonValueSchema: z.ZodType<Json> = z.lazy(() =>
     z.union([
         z.string(),
@@ -60,7 +78,8 @@ export const DecisionSchema = z
         criteria: z.union([NoulCriteriaSchema, ChoiceCriteriaSchema, ScoreCriteriaSchema]).optional(),
         fallback: z.union([z.string(), z.number(), z.boolean()]),
         minConfidence: z.number().min(0).max(1).optional(),
-        maker: z.string().regex(MAKER_NAME_PATTERN).optional(),
+        maker: MakerRefSchema.optional(),
+        shadow: z.string().regex(MAKER_NAME_PATTERN).optional(),
         model: z.string().optional(),
     })
     .strict();
@@ -72,7 +91,7 @@ export const DecisionCatalogSchema = z
         version: z.literal(1),
         defaults: z
             .object({
-                maker: z.string().regex(MAKER_NAME_PATTERN).optional(),
+                maker: MakerRefSchema.optional(),
                 model: z.string().optional(),
                 minConfidence: z.number().min(0).max(1).optional(),
             })

package/src/types.ts

@@ -43,14 +43,23 @@ export interface DecisionDefinition {
     readonly fallback: string | number | boolean;
     /** Overrides `defaults.minConfidence` (0..1). */
     readonly minConfidence?: number;
-    /** Registry name, checked at hub load, not by the catalog loader. */
-    readonly maker?: string;
+    /** Registry name, or an ordered fallback chain of names (ADR-040); checked at hub load, not by the loader. */
+    readonly maker?: MakerRef;
+    /** One maker asked beside the primary on live traffic and reported, never served (ADR-040). */
+    readonly shadow?: string;
     readonly model?: string;
 }
 
+/**
+ * A maker reference: one registry name, or an ordered fallback chain of names (ADR-040). The
+ * authored form is preserved (`string` stays `string`), so a single-name catalog round-trips
+ * byte-identically; the hub resolves the chain per call.
+ */
+export type MakerRef = string | readonly string[];
+
 /** Catalog-wide maker/model/minConfidence defaults; every key optional. */
 export interface CatalogDefaults {
-    readonly maker?: string;
+    readonly maker?: MakerRef;
     readonly model?: string;
     readonly minConfidence?: number;
 }