@gobing-ai/ts-ai-decision 0.5.13

package/src/registry.ts

@@ -0,0 +1,99 @@
+import { createDecisionMaker, type DecisionMaker, type DecisionMakerOptions } 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 { DecisionRegistryError, UnknownDecisionMakerError } from './errors';
+
+/** 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 };
+}
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * 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 class DecisionMakerRegistry {
+    private readonly entries = new Map<
+        string,
+        { source: MakerSource; maker?: DecisionMaker; pending?: Promise<DecisionMaker> }
+    >();
+
+    /** Pre-registers `typesafe`, `fm-local` and `laya-local` 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 }));
+        this.register('fm-local', () =>
+            createDecisionMaker({ driver: createFmDriver(driverOptions['fm-local'] ?? {}), ...makerOptions }),
+        );
+        this.register('laya-local', () =>
+            createDecisionMaker({ driver: createLayaDriver(driverOptions['laya-local'] ?? {}), ...makerOptions }),
+        );
+    }
+
+    /** Register a maker or factory under `name`; chains. Throws on a bad or already-registered name. */
+    register(name: string, source: MakerSource): this {
+        if (!NAME_PATTERN.test(name)) {
+            throw new DecisionRegistryError(`Invalid decision maker name '${name}' — must match ${NAME_PATTERN}.`);
+        }
+        if (this.entries.has(name)) {
+            throw new DecisionRegistryError(`Decision maker '${name}' is already registered.`);
+        }
+        this.entries.set(name, { source });
+        return this;
+    }
+
+    has(name: string): boolean {
+        return this.entries.has(name);
+    }
+
+    names(): string[] {
+        return [...this.entries.keys()];
+    }
+
+    /**
+     * 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.
+     */
+    async resolve(name: string): Promise<DecisionMaker> {
+        const entry = this.entries.get(name);
+        if (entry === undefined) {
+            throw new UnknownDecisionMakerError(
+                `Unknown decision maker '${name}' — register it or use a built-in.`,
+                name,
+            );
+        }
+        if (entry.maker) return entry.maker;
+        // A check-then-set across `await` would let two concurrent callers run the factory and
+        // receive different instances, so the run itself is memoised while in flight. The
+        // rejection teardown attaches via .catch instead of a try/finally inside the run: with a
+        // finally-based clear, Bun's test runner reports the settled rejection as an unhandled
+        // error when a later resolve retries (false positive).
+        if (!entry.pending) {
+            const run = (async () => {
+                const maker = typeof entry.source === 'function' ? await entry.source() : entry.source;
+                entry.maker = maker;
+                return maker;
+            })();
+            run.catch(() => {
+                if (entry.pending === run) entry.pending = undefined; // allow a later resolve to retry
+            });
+            entry.pending = run;
+        }
+        return await entry.pending;
+    }
+}

package/src/schema.ts

@@ -0,0 +1,95 @@
+import type { Desc, Json } from '@gobing-ai/ts-ai-runner';
+import { z } from 'zod';
+
+/**
+ * Zod schema for the decision catalog — the runtime source of truth (task 0089 R4).
+ * `schemas/decision-catalog.schema.json` describes the same shape for editors and
+ * standard validators; strictness (`additionalProperties: false` / `.strict()`) applies
+ * at every level. Cross-field semantics (fallback vocabulary, template refs, defaults,
+ * reserved `instructions`) are enforced by the loader in `catalog.ts`.
+ */
+
+export const DECISION_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/** Declared parameter names: lowercase-start identifier, no hyphens. */
+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-]*$/;
+
+const JsonValueSchema: z.ZodType<Json> = z.lazy(() =>
+    z.union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.null(),
+        z.array(JsonValueSchema),
+        z.record(z.string(), JsonValueSchema),
+    ]),
+);
+
+/** A Jev entry: string, JSON object, JSON array, or null ("left undescribed"). */
+const JevEntrySchema: z.ZodType<Desc> = z.lazy(() =>
+    z.union([z.string(), z.null(), z.array(JsonValueSchema), z.record(z.string(), JsonValueSchema)]),
+);
+
+const ParamTypeSchema = z.enum(['string', 'number', 'boolean', 'enum', 'json']);
+
+/** Full parameter form; the shorthand is the bare {@link ParamTypeSchema} string. */
+const FullParamSchema = z
+    .object({
+        type: ParamTypeSchema,
+        default: z.unknown().optional(),
+        values: z.array(z.string()).min(1).optional(),
+        description: z.string().optional(),
+    })
+    .strict();
+
+/** Authored parameter form: the bare type shorthand or the full strict object. */
+export const ParamSchema = z.union([ParamTypeSchema, FullParamSchema]);
+
+const NoulCriteriaSchema = z.object({ true: JevEntrySchema.optional(), false: JevEntrySchema.optional() }).strict();
+const ChoiceCriteriaSchema = z.record(z.string().min(1), JevEntrySchema);
+const ScoreCriteriaSchema = z.array(JevEntrySchema);
+
+/** One authored decision (strict; cross-field semantics are enforced by the loader in `catalog.ts`). */
+export const DecisionSchema = z
+    .object({
+        type: z.enum(['choice', 'score', 'noul']),
+        description: z.string().optional(),
+        instructions: JevEntrySchema.optional(),
+        parameters: z.record(z.string().regex(PARAM_NAME_PATTERN), ParamSchema).optional(),
+        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(),
+        model: z.string().optional(),
+    })
+    .strict();
+
+/** Whole-catalog schema (strict; `version` must be 1 and at least one decision is required). */
+export const DecisionCatalogSchema = z
+    .object({
+        $schema: z.string().optional(),
+        version: z.literal(1),
+        defaults: z
+            .object({
+                maker: z.string().regex(MAKER_NAME_PATTERN).optional(),
+                model: z.string().optional(),
+                minConfidence: z.number().min(0).max(1).optional(),
+            })
+            .strict()
+            .optional(),
+        decisions: z.record(z.string().regex(DECISION_ID_PATTERN), DecisionSchema),
+    })
+    .strict()
+    .refine((catalog) => Object.keys(catalog.decisions).length >= 1, {
+        message: 'decisions must declare at least one decision',
+    });
+
+/** Inferred shape of a validated catalog body. */
+export type ParsedCatalog = z.infer<typeof DecisionCatalogSchema>;
+/** Inferred shape of one validated decision body. */
+export type ParsedDecision = z.infer<typeof DecisionSchema>;
+/** Inferred shape of the full (non-shorthand) parameter form. */
+export type ParsedParam = z.infer<typeof FullParamSchema>;
+/** The whole parameter union: the shorthand type string or the full form. */
+export type ParsedParamUnion = z.infer<typeof ParamSchema>;

package/src/types.ts

@@ -0,0 +1,80 @@
+import type { Desc, Json } from '@gobing-ai/ts-ai-runner';
+
+/** Jev question types a decision can declare (task 0089 R4). */
+export type DecisionType = 'choice' | 'score' | 'noul';
+
+/** Declared parameter types; `enum` requires `values`, `json` accepts any JSON value. */
+export type ParamType = 'string' | 'number' | 'boolean' | 'enum' | 'json';
+
+/** One declared parameter, normalized from the shorthand (`name: type`) or full form. */
+export interface DecisionParam {
+    readonly name: string;
+    readonly type: ParamType;
+    /** True when authored without a `default` key: every call must supply it. */
+    readonly required: boolean;
+    /** Authored `default` value (may be null); defined exactly when not required. */
+    readonly default?: Json;
+    /** Accepted strings for `type: enum` (at least one). */
+    readonly values?: readonly string[];
+    readonly description?: string;
+}
+
+/** A criteria/instructions entry: description string, JSON object, JSON array, or null ("undescribed"). */
+export type JevEntry = Desc;
+
+/** Normalized criteria of a decision, shaped by its `type`. */
+export type DecisionCriteria =
+    | { readonly kind: 'choice'; readonly labels: Readonly<Record<string, JevEntry>> }
+    | { readonly kind: 'score'; readonly levels: readonly JevEntry[] }
+    | { readonly kind: 'noul'; readonly outcomes?: { readonly true?: JevEntry; readonly false?: JevEntry } };
+
+/** One typed decision definition as produced by the loader. */
+export interface DecisionDefinition {
+    readonly id: string;
+    readonly source: string;
+    readonly type: DecisionType;
+    /** Documentation only; never sent to the model. */
+    readonly description?: string;
+    /** Authored instructions template; {@link DEFAULT_INSTRUCTIONS_TEMPLATE} when absent. */
+    readonly instructions: JevEntry;
+    /** Declared parameters plus the implicit reserved `instructions` parameter. */
+    readonly parameters: Readonly<Record<string, DecisionParam>>;
+    readonly criteria: DecisionCriteria;
+    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;
+    readonly model?: string;
+}
+
+/** Catalog-wide maker/model/minConfidence defaults; every key optional. */
+export interface CatalogDefaults {
+    readonly maker?: string;
+    readonly model?: string;
+    readonly minConfidence?: number;
+}
+
+/** A loaded catalog: typed definitions, all-or-nothing (task 0089 invariant). */
+export interface DecisionCatalog {
+    readonly source: string;
+    readonly defaults: CatalogDefaults;
+    readonly decisions: Readonly<Record<string, DecisionDefinition>>;
+}
+
+/** Fully resolved parameter values for one `decide` call, including `instructions`. */
+export type ResolvedParams = Record<string, Json>;
+
+/** The rendered Jev question for one decision, ready for the neutral surface. */
+export type JevQuestion =
+    | {
+          readonly type: 'choice';
+          readonly instructions: JevEntry;
+          readonly criteria: Readonly<Record<string, JevEntry>>;
+      }
+    | { readonly type: 'score'; readonly instructions: JevEntry; readonly criteria: readonly JevEntry[] }
+    | {
+          readonly type: 'noul';
+          readonly instructions: JevEntry;
+          readonly criteria?: { readonly true?: JevEntry; readonly false?: JevEntry };
+      };