@gobing-ai/ts-ai-decision 0.5.13

package/dist/hub.d.ts

@@ -0,0 +1,142 @@
+import { type Json } from '@gobing-ai/ts-ai-runner';
+import { type CatalogLoadOptions } from './catalog';
+import { type BuiltinMakerOptions, DecisionMakerRegistry, type MakerSource } from './registry';
+import type { DecisionCatalog, DecisionCriteria, DecisionParam, DecisionType } from './types';
+/**
+ * DecisionHub (task 0090, ADR-033 § API / § decide algorithm): loads catalogs
+ * over the 0089 loader and serves `decide` through makers resolved by name
+ * from the 0091 registry. `decide` never rejects for backend construction,
+ * transport, timeout, answer validation or low confidence — it maps every such
+ * outcome to the declared fallback — and rejects only for caller mistakes
+ * (unknown id, invalid input, unregistered per-call maker), always before any
+ * backend call. The hub contains no driver code; every maker comes from
+ * `registry.resolve(name)`.
+ */
+/** Package confidence floor when neither the decision nor the catalog declares one. */
+export declare const DEFAULT_MIN_CONFIDENCE = 0.7;
+/** Hub default when neither the per-call options, the decision nor the catalog names a maker. */
+export declare const DEFAULT_MAKER = "typesafe";
+/** Shared envelope of every {@link DecisionResult} variant. */
+export interface DecisionResultBase {
+    readonly id: string;
+    /** Observed calibration; null only when no answer was obtained. */
+    readonly confidence: number | null;
+    /** `model` for an accepted answer, `default` for any fallback. */
+    readonly source: 'model' | 'default';
+    readonly reason: 'accepted' | 'low-confidence' | 'no-backend' | 'timeout' | 'error';
+    /** Registry name of the maker that was selected. */
+    readonly maker: string;
+    readonly durationMs: number;
+}
+/** The fallback-guaranteed result of one `decide` call, shaped by the decision type. */
+export type DecisionResult = (DecisionResultBase & {
+    readonly type: 'choice';
+    readonly value: string;
+}) | (DecisionResultBase & {
+    readonly type: 'score';
+    readonly value: number;
+}) | (DecisionResultBase & {
+    readonly type: 'noul';
+    readonly value: boolean;
+    readonly probability: number | null;
+});
+/** One loaded decision, for downstream discovery (`hub.list()`). */
+export interface DecisionSummary {
+    readonly id: string;
+    readonly type: DecisionType;
+    readonly description?: string;
+    readonly source: string;
+}
+/** Full served contract of one decision (`hub.describe(id)`), including the effective defaults. */
+export interface DecisionDescriptor {
+    readonly id: string;
+    readonly type: DecisionType;
+    readonly description?: string;
+    readonly source: string;
+    /** Declared parameter contract including the reserved `instructions` parameter. */
+    readonly parameters: Readonly<Record<string, DecisionParam>>;
+    readonly criteria: DecisionCriteria;
+    readonly fallback: string | number | boolean;
+    /** decision → catalog defaults → {@link DEFAULT_MIN_CONFIDENCE}. */
+    readonly minConfidence: number;
+    /** decision → catalog defaults → hub defaultMaker. */
+    readonly maker: string;
+    /** decision → catalog defaults; absent when neither declares one. */
+    readonly model?: string;
+}
+/** {@link DecisionHub} construction options. */
+export interface DecisionHubOptions {
+    /** Default: a fresh `DecisionMakerRegistry` with the three built-in makers. */
+    readonly registry?: DecisionMakerRegistry;
+    /** Used when neither the decision nor the catalog names a maker. Default 'typesafe'. */
+    readonly defaultMaker?: string;
+    /** Clock for `durationMs`; injectable so tests are deterministic. Default `Date.now`. */
+    readonly now?: () => number;
+}
+/** 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;
+}
+/**
+ * Hub over loaded catalogs and named makers (task 0090, ADR-033 § API):
+ * `decide` serves one Jev question per call and resolves every backend outcome
+ * to the declared fallback; only caller mistakes throw, before any backend
+ * call. Discovery (`list`/`describe`) and maker construction stay decoupled —
+ * makers come only from `registry.resolve(name)`.
+ */
+export declare class DecisionHub {
+    readonly registry: DecisionMakerRegistry;
+    private readonly decisions;
+    private readonly defaultMaker;
+    private readonly now;
+    constructor(options?: DecisionHubOptions);
+    /**
+     * 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
+     * nothing from the offending catalog.
+     */
+    load(catalog: DecisionCatalog): void;
+    /** Load a catalog file through the 0089 loader, then register it via {@link load}. */
+    loadFile(path: string, options?: CatalogLoadOptions): Promise<void>;
+    /** Pure read over the loaded decisions; never constructs a maker or driver. */
+    list(): DecisionSummary[];
+    /** Pure read of one decision's served contract; throws UnknownDecisionError for an unknown id. */
+    describe(id: string): DecisionDescriptor;
+    /**
+     * 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,
+     * invalid answers and low confidence all resolve to the declared fallback;
+     * only caller mistakes throw, before any backend call.
+     */
+    decide(id: string, input?: Record<string, Json>, options?: DecideOptions): Promise<DecisionResult>;
+    /** Maker-name precedence for discovery results: decision → catalog defaults → hub default. */
+    private effectiveMakerName;
+    private mustGet;
+    /**
+     * Build the declared-fallback envelope: `source: 'default'`, the observed
+     * confidence (null when none), always the selected maker name. For noul,
+     * `probability` stays null unless the answer itself supplied one.
+     */
+    private fallbackResult;
+}
+/** Options for {@link createDecisionHub}: one call from options to a ready hub. */
+export interface CreateDecisionHubOptions extends DecisionHubOptions {
+    /** Ignored when `registry` is supplied. Default: the three built-in makers. */
+    readonly builtins?: BuiltinMakerOptions | false;
+    /** Extra makers registered before any catalog loads (catalog checks run at load). */
+    readonly makers?: Readonly<Record<string, MakerSource>>;
+    /** Catalog files loaded in order with {@link CreateDecisionHubOptions.catalogOptions}. */
+    readonly catalogs?: readonly string[];
+    /** Forwarded to every `loadFile` call. */
+    readonly catalogOptions?: CatalogLoadOptions;
+}
+/**
+ * Build the registry, register `makers`, construct the hub and `loadFile` each
+ * catalog in order. Any failure rejects; a partially built hub never escapes.
+ */
+export declare function createDecisionHub(options?: CreateDecisionHubOptions): Promise<DecisionHub>;
+//# sourceMappingURL=hub.d.ts.map

package/dist/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"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"}

package/dist/hub.js

@@ -0,0 +1,262 @@
+import { DecisionConfigError, DecisionTimeoutError, q, } from '@gobing-ai/ts-ai-runner';
+import { loadDecisionCatalog } from './catalog.js';
+import { DecisionCatalogError, UnknownDecisionError, UnknownDecisionMakerError } from './errors.js';
+import { buildState, renderQuestion, resolveDecisionInput } from './params.js';
+import { DecisionMakerRegistry } from './registry.js';
+/**
+ * DecisionHub (task 0090, ADR-033 § API / § decide algorithm): loads catalogs
+ * over the 0089 loader and serves `decide` through makers resolved by name
+ * from the 0091 registry. `decide` never rejects for backend construction,
+ * transport, timeout, answer validation or low confidence — it maps every such
+ * outcome to the declared fallback — and rejects only for caller mistakes
+ * (unknown id, invalid input, unregistered per-call maker), always before any
+ * backend call. The hub contains no driver code; every maker comes from
+ * `registry.resolve(name)`.
+ */
+/** Package confidence floor when neither the decision nor the catalog declares one. */
+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';
+/** Effective confidence floor: decision → catalog defaults → package default. */
+function effectiveMinConfidence(definition, defaults) {
+    return definition.minConfidence ?? defaults.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+}
+/** Confidence observed in one validated answer; noul synthesizes `max(p, 1 - p)`. */
+function observedAnswer(answer) {
+    switch (answer.kind) {
+        case 'choice':
+            return { confidence: answer.confidence };
+        case 'score':
+            return { confidence: answer.confidence };
+        case 'noul':
+            return {
+                confidence: Math.max(answer.probability, 1 - answer.probability),
+                probability: answer.probability,
+            };
+    }
+}
+/**
+ * Map the rendered question onto the neutral Jev builders — exactly one
+ * question per `decide` call, keyed by the decision id at the `ask` level.
+ */
+function buildJevQuestion(question) {
+    switch (question.type) {
+        case 'choice':
+            return q.choice(question.instructions, { ...question.criteria });
+        case 'score':
+            // The loader enforces >= 2 levels; the tuple is the builder's shape.
+            return q.score(question.instructions, question.criteria);
+        case 'noul': {
+            const outcomes = question.criteria;
+            return q.noul(question.instructions, outcomes !== undefined ? { yes: outcomes.true, no: outcomes.false } : undefined);
+        }
+    }
+}
+/**
+ * Hub over loaded catalogs and named makers (task 0090, ADR-033 § API):
+ * `decide` serves one Jev question per call and resolves every backend outcome
+ * to the declared fallback; only caller mistakes throw, before any backend
+ * call. Discovery (`list`/`describe`) and maker construction stay decoupled —
+ * makers come only from `registry.resolve(name)`.
+ */
+export class DecisionHub {
+    registry;
+    decisions = new Map();
+    defaultMaker;
+    now;
+    constructor(options = {}) {
+        this.registry = options.registry ?? new DecisionMakerRegistry();
+        this.defaultMaker = options.defaultMaker ?? DEFAULT_MAKER;
+        this.now = options.now ?? Date.now;
+        if (!this.registry.has(this.defaultMaker)) {
+            throw new UnknownDecisionMakerError(`Default decision maker '${this.defaultMaker}' is not registered in the hub registry ` +
+                `(registered: ${this.registry.names().join(', ') || 'none'})`, this.defaultMaker);
+        }
+    }
+    /**
+     * 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
+     * nothing from the offending catalog.
+     */
+    load(catalog) {
+        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');
+        }
+        // Stage first, commit only when every decision passed the cross-catalog checks.
+        const staged = [];
+        for (const [id, definition] of Object.entries(catalog.decisions)) {
+            const existing = this.decisions.get(id);
+            if (existing !== undefined) {
+                throw new DecisionCatalogError(`Decision id "${id}" in catalog "${catalog.source}" duplicates the decision loaded from ` +
+                    `"${existing.definition.source}"`, catalog.source, id, 'id');
+            }
+            if (definition.maker !== undefined && !this.registry.has(definition.maker)) {
+                throw new DecisionCatalogError(`Decision "${id}" in catalog "${catalog.source}" names maker '${definition.maker}' that is not ` +
+                    `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, id, 'maker');
+            }
+            staged.push({ definition, defaults: catalog.defaults });
+        }
+        for (const entry of staged)
+            this.decisions.set(entry.definition.id, entry);
+    }
+    /** Load a catalog file through the 0089 loader, then register it via {@link load}. */
+    async loadFile(path, options = {}) {
+        this.load(await loadDecisionCatalog(path, options));
+    }
+    /** Pure read over the loaded decisions; never constructs a maker or driver. */
+    list() {
+        return [...this.decisions.values()].map(({ definition }) => ({
+            id: definition.id,
+            type: definition.type,
+            ...(definition.description !== undefined ? { description: definition.description } : {}),
+            source: definition.source,
+        }));
+    }
+    /** Pure read of one decision's served contract; throws UnknownDecisionError for an unknown id. */
+    describe(id) {
+        const { definition, defaults } = this.mustGet(id);
+        const model = definition.model ?? defaults.model;
+        return {
+            id: definition.id,
+            type: definition.type,
+            ...(definition.description !== undefined ? { description: definition.description } : {}),
+            source: definition.source,
+            parameters: definition.parameters,
+            criteria: definition.criteria,
+            fallback: definition.fallback,
+            minConfidence: effectiveMinConfidence(definition, defaults),
+            maker: this.effectiveMakerName(definition, defaults),
+            ...(model !== undefined ? { model } : {}),
+        };
+    }
+    /**
+     * 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,
+     * invalid answers and low confidence all resolve to the declared fallback;
+     * only caller mistakes throw, before any backend call.
+     */
+    async decide(id, input = {}, options = {}) {
+        const start = this.now();
+        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.
+            throw new UnknownDecisionMakerError(`Decision "${id}" was asked on maker '${makerName}' that is not registered in the hub registry ` +
+                `(registered: ${this.registry.names().join(', ') || 'none'})`, makerName);
+        }
+        const state = buildState(definition, params);
+        const model = definition.model ?? defaults.model;
+        const request = {
+            state,
+            questions: { [definition.id]: buildJevQuestion(renderQuestion(definition, params)) },
+            ...(model !== undefined ? { model } : {}),
+        };
+        // 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;
+        try {
+            const maker = await this.registry.resolve(makerName);
+            inAsk = true;
+            const answers = await maker.ask(request);
+            const answer = answers[definition.id];
+            if (answer === undefined || answer.kind !== definition.type) {
+                return this.fallbackResult(definition, makerName, 'error', null, start);
+            }
+            const observed = observedAnswer(answer);
+            if (observed.confidence < effectiveMinConfidence(definition, defaults)) {
+                return this.fallbackResult(definition, makerName, 'low-confidence', observed.confidence, start, observed.probability);
+            }
+            const base = {
+                id: definition.id,
+                confidence: observed.confidence,
+                source: 'model',
+                reason: 'accepted',
+                maker: makerName,
+                durationMs: this.now() - start,
+            };
+            switch (answer.kind) {
+                case 'choice':
+                    return { ...base, type: 'choice', value: answer.label };
+                case 'score':
+                    return { ...base, type: 'score', value: answer.score };
+                case 'noul':
+                    return {
+                        ...base,
+                        type: 'noul',
+                        value: answer.probability >= 0.5,
+                        probability: answer.probability,
+                    };
+            }
+        }
+        catch (error) {
+            const reason = !inAsk || error instanceof DecisionConfigError
+                ? 'no-backend'
+                : error instanceof DecisionTimeoutError
+                    ? 'timeout'
+                    : 'error';
+            return this.fallbackResult(definition, makerName, reason, null, start);
+        }
+    }
+    /** Maker-name precedence for discovery results: decision → catalog defaults → hub default. */
+    effectiveMakerName(definition, defaults) {
+        return definition.maker ?? defaults.maker ?? this.defaultMaker;
+    }
+    mustGet(id) {
+        const registered = this.decisions.get(id);
+        if (registered === undefined) {
+            const loaded = [...this.decisions.keys()];
+            throw new UnknownDecisionError(`Unknown decision "${id}" — loaded decisions: ${loaded.length > 0 ? loaded.join(', ') : '(none)'}`, id);
+        }
+        return registered;
+    }
+    /**
+     * Build the declared-fallback envelope: `source: 'default'`, the observed
+     * confidence (null when none), always the selected maker name. For noul,
+     * `probability` stays null unless the answer itself supplied one.
+     */
+    fallbackResult(definition, makerName, reason, confidence, start, probability) {
+        const base = {
+            id: definition.id,
+            confidence,
+            source: 'default',
+            reason,
+            maker: makerName,
+            durationMs: this.now() - start,
+        };
+        switch (definition.type) {
+            case 'choice':
+                return { ...base, type: 'choice', value: definition.fallback };
+            case 'score':
+                return { ...base, type: 'score', value: definition.fallback };
+            case 'noul':
+                return {
+                    ...base,
+                    type: 'noul',
+                    value: definition.fallback,
+                    probability: probability ?? null,
+                };
+        }
+    }
+}
+/**
+ * Build the registry, register `makers`, construct the hub and `loadFile` each
+ * catalog in order. Any failure rejects; a partially built hub never escapes.
+ */
+export async function createDecisionHub(options = {}) {
+    const registry = options.registry ?? new DecisionMakerRegistry({ builtins: options.builtins });
+    for (const [name, source] of Object.entries(options.makers ?? {})) {
+        registry.register(name, source);
+    }
+    const hub = new DecisionHub({ registry, defaultMaker: options.defaultMaker, now: options.now });
+    for (const path of options.catalogs ?? []) {
+        await hub.loadFile(path, options.catalogOptions);
+    }
+    return hub;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './catalog';
+export * from './errors';
+export * from './hub';
+export * from './params';
+export * from './registry';
+export * from './schema';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './catalog.js';
+export * from './errors.js';
+export * from './hub.js';
+export * from './params.js';
+export * from './registry.js';
+export * from './schema.js';
+export * from './types.js';

package/dist/params.d.ts

@@ -0,0 +1,31 @@
+import type { Json } from '@gobing-ai/ts-ai-runner';
+import type { DecisionDefinition, DecisionParam, JevQuestion, ResolvedParams } from './types';
+/**
+ * Parameter resolution, `${params.*}` rendering and state building
+ * (task 0089 R7; design § Parameters, § Variable replacement).
+ */
+/** The reserved per-decision parameter carrying the caller's text; authors cannot declare it. */
+export declare const INSTRUCTIONS_PARAM = "instructions";
+/** Authored-instructions default: the caller's text passed through unchanged. */
+export declare const DEFAULT_INSTRUCTIONS_TEMPLATE = "${params.instructions}";
+/** The implicit reserved `instructions` parameter: type string, default "". */
+export declare function implicitInstructionsParam(): DecisionParam;
+/**
+ * Resolve one decision's parameters: declared defaults overlaid by input, plus the
+ * implicit `instructions` (default ""). Unknown keys, missing required parameters
+ * (those without a default) and type mismatches throw {@link DecisionInputError}.
+ * An explicitly supplied `null` is a provided value (type-checked like any other).
+ */
+export declare function resolveDecisionInput(decision: DecisionDefinition, input?: Record<string, Json>): ResolvedParams;
+/**
+ * Render the decision's Jev question: `${params.<name>}` substitution applied to
+ * `instructions` and to criteria-description string leaves. Labels, `fallback`,
+ * `maker` and `model` are never templated, so the answer vocabulary stays static.
+ */
+export declare function renderQuestion(decision: DecisionDefinition, params: ResolvedParams): JevQuestion;
+/**
+ * Build the Jev `state` from the resolved declared parameters, excluding
+ * `instructions` and null values; null when nothing remains.
+ */
+export declare function buildState(decision: DecisionDefinition, params: ResolvedParams): Record<string, Json> | null;
+//# sourceMappingURL=params.d.ts.map

package/dist/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../src/params.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAY,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExG;;;GAGG;AAEH,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,2BAA4B,CAAC;AAKvE,+EAA+E;AAC/E,wBAAgB,yBAAyB,IAAI,aAAa,CAEzD;AA8BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM,GAAG,cAAc,CA2BnH;AAiCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,WAAW,CAgChG;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAS5G"}

package/dist/params.js

@@ -0,0 +1,149 @@
+import { DecisionInputError } from './errors.js';
+/**
+ * Parameter resolution, `${params.*}` rendering and state building
+ * (task 0089 R7; design § Parameters, § Variable replacement).
+ */
+/** The reserved per-decision parameter carrying the caller's text; authors cannot declare it. */
+export const INSTRUCTIONS_PARAM = 'instructions';
+/** Authored-instructions default: the caller's text passed through unchanged. */
+export const DEFAULT_INSTRUCTIONS_TEMPLATE = `\${params.instructions}`;
+/** Same regex as `ts-dual-workflow-engine`'s variable resolver (design § Variable replacement). */
+const TEMPLATE_REF = /\$\{([^}]+)\}/g;
+/** The implicit reserved `instructions` parameter: type string, default "". */
+export function implicitInstructionsParam() {
+    return { name: INSTRUCTIONS_PARAM, type: 'string', required: false, default: '' };
+}
+function expectTypeMatch(decision, param, value) {
+    const expects = param.values !== undefined ? `one of [${param.values.join(', ')}]` : param.type;
+    let ok;
+    switch (param.type) {
+        case 'string':
+            ok = typeof value === 'string';
+            break;
+        case 'number':
+            ok = typeof value === 'number' && Number.isFinite(value);
+            break;
+        case 'boolean':
+            ok = typeof value === 'boolean';
+            break;
+        case 'enum':
+            ok = typeof value === 'string' && param.values?.includes(value) === true;
+            break;
+        case 'json':
+            return; // any JSON value is accepted
+    }
+    if (!ok) {
+        throw new DecisionInputError(`Parameter "${param.name}" of decision "${decision.id}" expects ${expects}, got ${JSON.stringify(value)}`, decision.id, param.name);
+    }
+}
+/**
+ * Resolve one decision's parameters: declared defaults overlaid by input, plus the
+ * implicit `instructions` (default ""). Unknown keys, missing required parameters
+ * (those without a default) and type mismatches throw {@link DecisionInputError}.
+ * An explicitly supplied `null` is a provided value (type-checked like any other).
+ */
+export function resolveDecisionInput(decision, input = {}) {
+    const params = {};
+    for (const key of Object.keys(input)) {
+        // Own-property check: input keys like "constructor" must not resolve via the prototype chain.
+        if (!Object.hasOwn(decision.parameters, key)) {
+            throw new DecisionInputError(`Unknown parameter "${key}" for decision "${decision.id}"; declared parameters: ` +
+                `${Object.keys(decision.parameters).join(', ')}`, decision.id, key);
+        }
+    }
+    for (const param of Object.values(decision.parameters)) {
+        const supplied = param.name in input ? input[param.name] : undefined;
+        if (supplied === undefined && param.required) {
+            throw new DecisionInputError(`Missing required parameter "${param.name}" for decision "${decision.id}"`, decision.id, param.name);
+        }
+        const value = supplied !== undefined ? supplied : (param.default ?? null);
+        expectTypeMatch(decision, param, value);
+        params[param.name] = value;
+    }
+    return params;
+}
+function substitute(decisionId, ref, params) {
+    if (!ref.startsWith('params.')) {
+        throw new DecisionInputError(`Template ref "\${${ref}}" must use the "params" namespace`, decisionId, ref);
+    }
+    const name = ref.slice('params.'.length);
+    const value = params[name];
+    // Substitution forms (design § Variable replacement): strings verbatim, numbers and
+    // booleans via String, json via JSON.stringify, null as "".
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+function renderEntryValue(decisionId, value, params) {
+    if (typeof value === 'string') {
+        return value.replace(TEMPLATE_REF, (_match, ref) => substitute(decisionId, ref, params));
+    }
+    if (Array.isArray(value))
+        return value.map((item) => renderEntryValue(decisionId, item, params));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, renderEntryValue(decisionId, entry, params)]));
+    }
+    return value;
+}
+function renderEntry(decisionId, entry, params) {
+    return renderEntryValue(decisionId, entry, params);
+}
+/**
+ * Render the decision's Jev question: `${params.<name>}` substitution applied to
+ * `instructions` and to criteria-description string leaves. Labels, `fallback`,
+ * `maker` and `model` are never templated, so the answer vocabulary stays static.
+ */
+export function renderQuestion(decision, params) {
+    const instructions = renderEntry(decision.id, decision.instructions, params);
+    const criteria = decision.criteria;
+    switch (criteria.kind) {
+        case 'choice': {
+            const rendered = {};
+            for (const [label, entry] of Object.entries(criteria.labels)) {
+                rendered[label] = renderEntry(decision.id, entry, params);
+            }
+            return { type: 'choice', instructions, criteria: rendered };
+        }
+        case 'score':
+            return {
+                type: 'score',
+                instructions,
+                criteria: criteria.levels.map((entry) => renderEntry(decision.id, entry, params)),
+            };
+        case 'noul': {
+            const outcomes = criteria.outcomes;
+            if (outcomes === undefined)
+                return { type: 'noul', instructions };
+            return {
+                type: 'noul',
+                instructions,
+                criteria: {
+                    ...(outcomes.true !== undefined ? { true: renderEntry(decision.id, outcomes.true, params) } : {}),
+                    ...(outcomes.false !== undefined
+                        ? { false: renderEntry(decision.id, outcomes.false, params) }
+                        : {}),
+                },
+            };
+        }
+    }
+}
+/**
+ * Build the Jev `state` from the resolved declared parameters, excluding
+ * `instructions` and null values; null when nothing remains.
+ */
+export function buildState(decision, params) {
+    const state = {};
+    for (const param of Object.values(decision.parameters)) {
+        if (param.name === INSTRUCTIONS_PARAM)
+            continue;
+        const value = params[param.name];
+        if (value === null || value === undefined)
+            continue;
+        state[param.name] = value;
+    }
+    return Object.keys(state).length === 0 ? null : state;
+}

package/dist/registry.d.ts

@@ -0,0 +1,42 @@
+import { type DecisionMaker, type DecisionMakerOptions } from '@gobing-ai/ts-ai-runner';
+import { type FmDriverOptions } from '@gobing-ai/ts-decision-fm';
+import { type LayaDriverOptions } from '@gobing-ai/ts-laya-mlx';
+/** 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). */
+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;
+    };
+}
+/**
+ * Registry mapping plain names to {@link DecisionMaker}s (task 0091, ADR-033
+ * § Maker registry). Built-ins are registered as lazy factories, so
+ * `register`, `has` and `names` never construct a maker or driver; the first
+ * `resolve` runs the factory and memoises the maker, while a failed factory
+ * stays un-memoised so a later resolve retries (e.g. a model not yet
+ * downloaded). No catalog dependency — catalog code depends on this, never
+ * the reverse.
+ */
+export declare class DecisionMakerRegistry {
+    private readonly entries;
+    /** Pre-registers `typesafe`, `fm-local` and `laya-local` unless `builtins: false`. */
+    constructor(options?: {
+        builtins?: BuiltinMakerOptions | false;
+    });
+    /** Register a maker or factory under `name`; chains. Throws on a bad or already-registered name. */
+    register(name: string, source: MakerSource): this;
+    has(name: string): boolean;
+    names(): string[];
+    /**
+     * Resolve `name` to a maker, running and memoising a factory on first use. Factory errors
+     * propagate unchanged. Concurrent resolves of one name share a single in-flight factory run
+     * so every caller gets the same instance; a rejected run is cleared so a later resolve retries.
+     */
+    resolve(name: string): Promise<DecisionMaker>;
+}
+//# sourceMappingURL=registry.d.ts.map