@spine-event-engine/ai 0.0.0-stage → 2.0.0-snapshot.24

package/dist/internal/registry.d.ts

@@ -0,0 +1,102 @@
+import type { MessageSchema } from "@spine-event-engine/core";
+import type { ModelRef } from "@spine-event-engine/proto/agent";
+import type { AiRegistryOptions } from "./contracts.js";
+import type { AiModel } from "./model.js";
+import { type AiBackendRegistration } from "./registration.js";
+import { type McpServerRegistration } from "./mcp.js";
+/**
+ * Application registry with fixed build policy and append-only deployments.
+ */
+export declare class AiRegistry {
+    /**
+     * Creates a registry only through the factory.
+     */
+    private constructor();
+    /**
+     * Creates a validated application registry.
+     *
+     * @param options Defaults, limits and queue bounds.
+     * @returns Registry with append-only deployments and build-time tool policy.
+     */
+    static create(options: AiRegistryOptions): AiRegistry;
+    /**
+     * Adds one unique adapter deployment, including after Bounded Context build.
+     *
+     * @param deployment Factory-created adapter registration.
+     * @returns This registry for configuration chaining.
+     */
+    register(deployment: AiBackendRegistration): this;
+    /**
+     * Registers one unique MCP server policy.
+     *
+     * @param server Factory-created MCP configuration.
+     * @returns This registry for configuration chaining.
+     */
+    registerTools(server: McpServerRegistration): this;
+}
+/**
+ * Sets registration to its immutable build state.
+ *
+ * @param registry Application configuration.
+ */
+export declare const freezeRegistry: (registry: AiRegistry) => void;
+/**
+ * Inputs for the per-kind selection precedence and repository allowlist.
+ */
+export interface AiSelection {
+    /**
+     * Declared generation or decision kind.
+     */
+    readonly kind: "generation" | "decision";
+    /**
+     * Registered application capabilities considered for selection.
+     */
+    readonly models: readonly AiModel<MessageSchema, MessageSchema>[];
+    /**
+     * Explicit model selected for this Agent instance.
+     */
+    readonly instancePreference?: ModelRef;
+    /**
+     * Repository model preference for this kind.
+     */
+    readonly repositoryDefault?: ModelRef;
+    /**
+     * Bounded Context model preference for this kind.
+     */
+    readonly contextDefault?: ModelRef;
+    /**
+     * Repository allowlist of permitted deployment references.
+     */
+    readonly allowedModels?: readonly ModelRef[];
+}
+/**
+ * Resolves one deployment by Proto value and validates its capabilities.
+ *
+ * @param registry Configured application registry.
+ * @param selection Effective scope preferences and registered capabilities.
+ * @returns Registered deployment selected for this invocation.
+ */
+export declare const selectDeployment: (registry: AiRegistry, selection: AiSelection) => AiBackendRegistration;
+/**
+ * Returns frozen application options for internal runtime binding.
+ *
+ * @param registry Application registry.
+ * @returns Immutable configuration options.
+ */
+export declare const registryOptions: (registry: AiRegistry) => Readonly<AiRegistryOptions>;
+/**
+ * Finds a factory-created MCP registration by configured server ID.
+ *
+ * @param registry Application configuration.
+ * @param id Configured MCP server identifier.
+ * @returns Registered server, or absence when the ID is not configured.
+ */
+export declare const mcpRegistration: (registry: AiRegistry, id: string) => McpServerRegistration | undefined;
+/**
+ * Returns a frozen snapshot of configured MCP registrations.
+ *
+ * @param registry Application configuration.
+ * @returns Registrations in configuration order without the mutable registry map.
+ */
+export declare const mcpRegistrations: (registry: AiRegistry) => readonly McpServerRegistration[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/internal/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/internal/registry.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAuC,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE7F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,EAAiB,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAqIrE;;GAEG;AACH,qBAAa,UAAU;IACrB;;OAEG;IACH,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU;IAYrD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI;IASjD;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI;CAQnD;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,UAAU,KAAG,IAUrD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,CAAC,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC;IAElE;;OAEG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,UAAU,EACpB,WAAW,WAAW,KACrB,qBA6BF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,UAAU,KAAG,QAAQ,CAAC,iBAAiB,CAEhF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,UAAU,EACpB,IAAI,MAAM,KACT,qBAAqB,GAAG,SAA0C,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,UAAU,KAAG,SAAS,qBAAqB,EAClC,CAAC"}

package/dist/internal/registry.js

@@ -0,0 +1,250 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { isAiModel, modelRefKey, ModelRef as ModelRefFactory, positiveInteger } from "./model.js";
+import { backendDefinition } from "./registration.js";
+import { mcpDefinition } from "./mcp.js";
+const registries = new WeakMap();
+/**
+ * Copies only explicitly configured whole-signal ceilings.
+ *
+ * @param limits Caller-supplied limits.
+ * @returns Immutable invocation limits.
+ */
+const copyInvocationLimits = (limits) => {
+    const candidate = limits;
+    if (typeof candidate !== "object" || candidate === null)
+        throw new TypeError("invocationLimits must be an object");
+    return Object.freeze({
+        ...(limits.operations === undefined
+            ? {}
+            : { operations: positiveInteger(limits.operations, "operations") }),
+        ...(limits.modelRequests === undefined
+            ? {}
+            : { modelRequests: positiveInteger(limits.modelRequests, "modelRequests") }),
+        ...(limits.toolCalls === undefined
+            ? {}
+            : { toolCalls: positiveInteger(limits.toolCalls, "toolCalls", true) }),
+        ...(limits.recordedReads === undefined
+            ? {}
+            : { recordedReads: positiveInteger(limits.recordedReads, "recordedReads", true) }),
+        ...(limits.deadlineMs === undefined
+            ? {}
+            : { deadlineMs: positiveInteger(limits.deadlineMs, "deadlineMs") }),
+        ...(limits.totalInputBytes === undefined
+            ? {}
+            : { totalInputBytes: positiveInteger(limits.totalInputBytes, "totalInputBytes") }),
+        ...(limits.totalOutputBytes === undefined
+            ? {}
+            : { totalOutputBytes: positiveInteger(limits.totalOutputBytes, "totalOutputBytes") }),
+        ...(limits.maxRecoveryBytes === undefined
+            ? {}
+            : { maxRecoveryBytes: positiveInteger(limits.maxRecoveryBytes, "maxRecoveryBytes") }),
+    });
+};
+/**
+ * Copies optional deployment defaults by Protobuf value.
+ *
+ * @param defaults Caller-supplied defaults.
+ * @returns Immutable references.
+ */
+const copyDefaults = (defaults) => {
+    const candidate = defaults;
+    if (typeof candidate !== "object" || candidate === null)
+        throw new TypeError("defaultModels are required");
+    const copy = (ref) => {
+        const value = ModelRefFactory.of(ref.name?.value ?? "", ref.revision?.value ?? "");
+        Object.freeze(value.name);
+        Object.freeze(value.revision);
+        return Object.freeze(value);
+    };
+    return Object.freeze({
+        ...(defaults.generation ? { generation: copy(defaults.generation) } : {}),
+        ...(defaults.decision ? { decision: copy(defaults.decision) } : {}),
+    });
+};
+/**
+ * Validates and freezes the registry's explicitly configured controls.
+ *
+ * @param options Caller-supplied defaults and optional ceilings.
+ * @returns Immutable registry options.
+ */
+const copyRegistryOptions = (options) => {
+    const suppliedLimits = options.invocationLimits;
+    if (suppliedLimits === null)
+        throw new TypeError("invocationLimits must be an object");
+    const copy = Object.freeze({
+        defaultModels: copyDefaults(options.defaultModels),
+        invocationLimits: copyInvocationLimits(options.invocationLimits ?? {}),
+        ...(options.concurrentOperations === undefined
+            ? {}
+            : {
+                concurrentOperations: positiveInteger(options.concurrentOperations, "concurrentOperations"),
+            }),
+        ...(options.queuedOperations === undefined
+            ? {}
+            : { queuedOperations: positiveInteger(options.queuedOperations, "queuedOperations", true) }),
+        ...(options.hookTimeoutMs === undefined
+            ? {}
+            : { hookTimeoutMs: positiveInteger(options.hookTimeoutMs, "hookTimeoutMs") }),
+    });
+    if (copy.hookTimeoutMs !== undefined &&
+        copy.invocationLimits.deadlineMs !== undefined &&
+        copy.hookTimeoutMs > copy.invocationLimits.deadlineMs)
+        throw new TypeError("hookTimeoutMs cannot exceed invocation deadlineMs");
+    return copy;
+};
+/**
+ * Retrieves active registry state without exposing it on the public class.
+ *
+ * @param registry Factory-created registry.
+ * @returns Internal mutable configuration state.
+ */
+const state = (registry) => {
+    const found = registries.get(registry);
+    if (!found)
+        throw new TypeError("registry must come from AiRegistry.create");
+    return found;
+};
+/**
+ * Application registry with fixed build policy and append-only deployments.
+ */
+export class AiRegistry {
+    /**
+     * Creates a registry only through the factory.
+     */
+    constructor() {
+        // Only create() may install the private registry state.
+    }
+    /**
+     * Creates a validated application registry.
+     *
+     * @param options Defaults, limits and queue bounds.
+     * @returns Registry with append-only deployments and build-time tool policy.
+     */
+    static create(options) {
+        const copy = copyRegistryOptions(options);
+        const registry = new AiRegistry();
+        registries.set(registry, {
+            options: copy,
+            backends: new Map(),
+            tools: new Map(),
+            frozen: false,
+        });
+        return registry;
+    }
+    /**
+     * Adds one unique adapter deployment, including after Bounded Context build.
+     *
+     * @param deployment Factory-created adapter registration.
+     * @returns This registry for configuration chaining.
+     */
+    register(deployment) {
+        const current = state(this);
+        const definition = backendDefinition(deployment);
+        const key = modelRefKey(definition.ref);
+        if (current.backends.has(key))
+            throw new TypeError("Duplicate deployment reference");
+        current.backends.set(key, deployment);
+        return this;
+    }
+    /**
+     * Registers one unique MCP server policy.
+     *
+     * @param server Factory-created MCP configuration.
+     * @returns This registry for configuration chaining.
+     */
+    registerTools(server) {
+        const current = state(this);
+        if (current.frozen)
+            throw new Error("AI registry is frozen");
+        const definition = mcpDefinition(server);
+        if (current.tools.has(definition.id))
+            throw new TypeError("Duplicate MCP server ID");
+        current.tools.set(definition.id, server);
+        return this;
+    }
+}
+/**
+ * Sets registration to its immutable build state.
+ *
+ * @param registry Application configuration.
+ */
+export const freezeRegistry = (registry) => {
+    const current = state(registry);
+    for (const kind of ["generation", "decision"]) {
+        const ref = current.options.defaultModels[kind];
+        if (!ref)
+            continue;
+        const registration = current.backends.get(modelRefKey(ref));
+        if (registration?.kind !== kind)
+            throw new TypeError(`${kind} default lacks a compatible registered deployment`);
+    }
+    current.frozen = true;
+};
+/**
+ * Resolves one deployment by Proto value and validates its capabilities.
+ *
+ * @param registry Configured application registry.
+ * @param selection Effective scope preferences and registered capabilities.
+ * @returns Registered deployment selected for this invocation.
+ */
+export const selectDeployment = (registry, selection) => {
+    const kind = selection.kind;
+    if (kind !== "generation" && kind !== "decision")
+        throw new TypeError("selection kind is unsupported");
+    const current = state(registry);
+    const ref = selection.instancePreference ??
+        selection.repositoryDefault ??
+        selection.contextDefault ??
+        current.options.defaultModels[selection.kind];
+    if (!ref)
+        throw new TypeError(`${selection.kind} has no deployment default`);
+    const key = modelRefKey(ref);
+    if (selection.allowedModels &&
+        !selection.allowedModels.some((allowed) => modelRefKey(allowed) === key))
+        throw new TypeError("Selected deployment is not allowed by repository");
+    const registered = current.backends.get(key);
+    if (registered?.kind !== selection.kind)
+        throw new TypeError("Selected deployment is not registered for this kind");
+    const models = selection.models.filter((model) => isAiModel(model) && model.definition.kind === selection.kind);
+    if (models.length === 0 ||
+        models.some((model) => !backendDefinition(registered).supports(model.definition)))
+        throw new TypeError("Selected deployment lacks a registered capability");
+    return registered;
+};
+/**
+ * Returns frozen application options for internal runtime binding.
+ *
+ * @param registry Application registry.
+ * @returns Immutable configuration options.
+ */
+export const registryOptions = (registry) => {
+    return state(registry).options;
+};
+/**
+ * Finds a factory-created MCP registration by configured server ID.
+ *
+ * @param registry Application configuration.
+ * @param id Configured MCP server identifier.
+ * @returns Registered server, or absence when the ID is not configured.
+ */
+export const mcpRegistration = (registry, id) => state(registry).tools.get(id);
+/**
+ * Returns a frozen snapshot of configured MCP registrations.
+ *
+ * @param registry Application configuration.
+ * @returns Registrations in configuration order without the mutable registry map.
+ */
+export const mcpRegistrations = (registry) => Object.freeze([...state(registry).tools.values()]);
+//# sourceMappingURL=registry.js.map

package/dist/internal/registry.js.map

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

package/dist/internal/schema.d.ts

@@ -0,0 +1,70 @@
+import type { MessageShape } from "@bufbuild/protobuf";
+import { type MessageSchema } from "@spine-event-engine/core";
+import type { AiValidationIssue } from "./contracts.js";
+/**
+ * Provider-neutral JSON schema for one supported Protobuf output.
+ */
+export interface AiOutputSchema {
+    /**
+     * JSON object discriminator for a message output.
+     */
+    readonly type: "object";
+    /**
+     * JSON properties derived from the Protobuf descriptor.
+     */
+    readonly properties: Readonly<Record<string, unknown>>;
+    /**
+     * JSON properties that must be supplied for admission.
+     */
+    readonly required: readonly string[];
+    /**
+     * Rejects unknown JSON properties.
+     */
+    readonly additionalProperties: false;
+    /**
+     * Oneof constraints combined with field constraints.
+     */
+    readonly allOf?: readonly unknown[];
+}
+/**
+ * Either a locally admitted Protobuf value or precise validation issues.
+ *
+ * @typeParam S - Output message descriptor.
+ */
+export type AiCandidateResult<S extends MessageSchema> = {
+    /**
+     * Indicates exact ProtoJSON and local validation succeeded.
+     */
+    readonly ok: true;
+    /**
+     * Validated generated Protobuf output.
+     */
+    readonly value: MessageShape<S>;
+} | {
+    /**
+     * Indicates candidate admission failed.
+     */
+    readonly ok: false;
+    /**
+     * Local defects available for one bounded correction.
+     */
+    readonly issues: readonly AiValidationIssue[];
+};
+/**
+ * Creates provider-neutral schema directly from a generated descriptor.
+ *
+ * @param schema Generated Protobuf output schema.
+ * @returns Strict schema or a field-specific unsupported-feature error.
+ */
+export declare const deriveOutputSchema: (schema: MessageSchema) => AiOutputSchema;
+/**
+ * Parses exact ProtoJSON, then applies Spine constraints and application validation.
+ *
+ * @typeParam S - Output message descriptor.
+ * @param schema Generated output descriptor.
+ * @param text Exact provider candidate text.
+ * @param check Optional pure application validator.
+ * @returns Admitted value or bounded local issues for a correction.
+ */
+export declare const parseCandidate: <S extends MessageSchema>(schema: S, text: string, check?: (value: MessageShape<S>) => readonly AiValidationIssue[]) => AiCandidateResult<S>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/internal/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/internal/schema.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAA0B,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEvD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,aAAa,IACjD;IACE;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CACjC,GACD;IACE;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C,CAAC;AAqMN;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,aAAa,KAAG,cAW1D,CAAC;AAqFF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,aAAa,EACpD,QAAQ,CAAC,EACT,MAAM,MAAM,EACZ,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,SAAS,iBAAiB,EAAE,KAC/D,iBAAiB,CAAC,CAAC,CA6BrB,CAAC"}