@acorex/platform 0.0.0-ACOREX

package/types/acorex-platform-runtime.d.ts

@@ -0,0 +1,470 @@
+import { AXPExecuteCommandResult, AXPViewDefinition, AXPMetaData } from '@acorex/platform/core';
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders, Type, Provider } from '@angular/core';
+import { AXComponent } from '@acorex/cdk/common';
+
+/**
+ * Shared build-time metadata shapes for command and query catalog definitions.
+ * Lives under `shared/` so secondary ng-packagr entries under `commands/` or `queries/` share a common `src/lib` compilation root.
+ */
+/** Command metadata validation: rule key + optional rule options only. */
+interface AXPCommandValidationRuleValue {
+    rule: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * Widget/interface reference for a schema property (name + optional widget options).
+ */
+interface AXPCommandInterfaceDefinitionValue {
+    name: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * One input/output property description (same structural role as AXPPropertyDefinition).
+ */
+interface AXPCommandSchemaPropertyDefinition {
+    name: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    defaultValue?: unknown;
+    disabled?: boolean;
+    interface: AXPCommandInterfaceDefinitionValue;
+    validations?: AXPCommandValidationRuleValue[];
+}
+/** Structured usage hints for planners and assistants (prefer over duplicating rules only in `description`). */
+interface AXPCommandAiUsageMetadata {
+    whenToUse?: string[];
+    avoidWhen?: string[];
+    /** Registry keys or tool names that commonly follow this command/query. */
+    followUpTools?: string[];
+}
+/** Declarative contracts: what the tool provides, who depends on it, and guarantees (not workflow `outcomes`). */
+interface AXPCommandAiContractsMetadata {
+    provides?: string[];
+    requiredBy?: string[];
+    guarantees?: string[];
+}
+type AXPCommandAiSafetyKind = 'read-only' | 'mutating';
+interface AXPCommandAiSafetyMetadata {
+    kind?: AXPCommandAiSafetyKind;
+    sideEffects?: boolean;
+    requiresConfirmation?: boolean;
+}
+type AXPCommandAiPerformanceCost = 'low' | 'medium' | 'high';
+interface AXPCommandAiPerformanceMetadata {
+    cost?: AXPCommandAiPerformanceCost;
+    cacheable?: boolean;
+}
+interface AXPCommandAiNextStepMetadata {
+    when: string;
+    action: string;
+}
+/**
+ * How to interpret a successful payload for agents (documentation only; not command workflow outcomes).
+ */
+interface AXPCommandAiResultSemanticsMetadata {
+    noMatch?: string;
+    exactMatch?: string;
+    multipleMatches?: string;
+    failed?: string;
+    /** Full catalog listing (e.g. no entity filter). */
+    catalog?: string;
+}
+interface AXPCommandAiMetadata {
+    shortDescription?: string;
+    tags?: string[];
+    usage?: AXPCommandAiUsageMetadata;
+    contracts?: AXPCommandAiContractsMetadata;
+    safety?: AXPCommandAiSafetyMetadata;
+    performance?: AXPCommandAiPerformanceMetadata;
+    nextSteps?: AXPCommandAiNextStepMetadata[];
+    resultSemantics?: AXPCommandAiResultSemanticsMetadata;
+    /**
+     * Default input fragment merged for AI/tool invocations (catalog & tooling).
+     * Runtime merge for a given command is applied in the AI module (not the generic command executor).
+     */
+    toolInputDefaults?: Record<string, unknown>;
+    /**
+     * Optional JSON Schema fragment for LLM tool `parameters` (OpenAI-style function calling).
+     * Merged over the auto-generated schema from catalog `inputs` (`properties` / `required` deep-merged).
+     * Use when widget-to-type inference is insufficient (e.g. `object`, `array`, `enum`, `format`).
+     */
+    toolParametersSchema?: Record<string, unknown>;
+}
+type AXPCommandExecutionMode = 'frontend' | 'backend' | 'both';
+/**
+ * Where this command is intended to appear in product tooling (AI agents, workflow automation pickers, etc.).
+ * Omitted = not declared here; runtimes may fall back to other metadata (e.g. `ai.tags`).
+ */
+type AXPCommandCapability = 'ai' | 'workflow';
+
+/**
+ * Build-time command metadata for AXPCommand implementations.
+ * `inputs` / `outputs` are schema rows (same family as entity optionDefinitions).
+ * Validation entries: only `rule` name and optional `options` (no title/message on rules).
+ * Do not import from Angular templates; sidecars may import `defineCommand` from `@acorex/platform/runtime`.
+ *
+ * Query metadata (fetch-only, no outcomes) is defined in `../queries/query-definition.types.ts` with `defineQuery`.
+ */
+
+type AXPCommandOutcomeDefinition = {
+    mode: 'static';
+    values: string[];
+} | {
+    mode: 'dynamic';
+    summary: string;
+    derivesFrom: string;
+    examples?: string[];
+};
+interface AXPCommandMetadataDefinition {
+    /** Runtime registration key (provideCommand / provideCommandSetups). */
+    key: string;
+    title: string;
+    description: string;
+    executionMode: AXPCommandExecutionMode;
+    /** Input parameters as schema rows. */
+    inputs?: AXPCommandSchemaPropertyDefinition[];
+    /** Output shape as schema rows. */
+    outputs?: AXPCommandSchemaPropertyDefinition[];
+    outcomes: AXPCommandOutcomeDefinition;
+    ai?: AXPCommandAiMetadata;
+    /** Optional list of surfaces that may list or invoke this command as a tool/activity. */
+    capabilities?: AXPCommandCapability[];
+}
+
+/**
+ * Typed identity helper for command metadata sidecars.
+ */
+declare function defineCommand<T extends AXPCommandMetadataDefinition>(definition: T): T;
+
+type AXPCommandExecutionStage = 'before' | 'after';
+interface AXPCommandExecutionEvent<TInput = unknown, TResult = unknown> {
+    stage: AXPCommandExecutionStage;
+    key: string;
+    input: TInput;
+    success?: boolean;
+    result?: AXPExecuteCommandResult<TResult> | null;
+    error?: unknown;
+}
+type CommandExecutionHandler<TInput, TResult> = (event: AXPCommandExecutionEvent<TInput, TResult>) => void;
+declare class AXPCommandEventsService {
+    private readonly broadcast;
+    private readonly distributedEvents;
+    listen<TInput = unknown, TResult = unknown>(handler: CommandExecutionHandler<TInput, TResult>): () => void;
+    emit<TInput = unknown, TResult = unknown>(event: AXPCommandExecutionEvent<TInput, TResult>): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPCommandEventsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPCommandEventsService>;
+}
+
+declare class AXPCommandExecutor {
+    private readonly injector;
+    private readonly registry;
+    private readonly extensions;
+    private readonly commandEvents;
+    execute<TInput = any, TResult = any>(key: string, input: TInput): Promise<AXPExecuteCommandResult<TResult> | null>;
+    private getPluginMiddlewares;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPCommandExecutor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPCommandExecutor>;
+}
+
+/**
+ * Represents a middleware function in the command execution pipeline.
+ */
+type AXPCommandMiddleware<TInput = any, TResult = any> = (input: TInput, next: (input: TInput) => Promise<AXPExecuteCommandResult<TResult>>) => Promise<AXPExecuteCommandResult<TResult>>;
+/**
+ * Creates a composed handler by chaining the provided command middlewares.
+ */
+declare function composeCommandMiddlewares<TInput, TResult>(middlewares: AXPCommandMiddleware<TInput, TResult>[]): (handler: (input: TInput) => Promise<AXPExecuteCommandResult<TResult>>) => (input: TInput) => Promise<AXPExecuteCommandResult<TResult>>;
+
+interface AXPCommandExtension {
+    target: string | RegExp;
+    middleware: AXPCommandMiddleware;
+}
+declare const AXP_COMMAND_EXTENSION: InjectionToken<AXPCommandExtension[]>;
+
+type AXPExecuteCommandResultPromise<TResult = any> = Promise<AXPExecuteCommandResult<TResult>>;
+interface AXPCommand<TInput = any, TResult = any> {
+    execute(input: TInput): AXPExecuteCommandResultPromise<TResult>;
+}
+
+declare class AXPCommandRegistry {
+    private registry;
+    private middlewares;
+    register(key: string, loader: () => Promise<AXPCommand>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPCommandMiddleware): void;
+    exists(key: string): boolean;
+    getLoader(key: string): (() => Promise<AXPCommand>) | undefined;
+    getMiddlewares(): readonly AXPCommandMiddleware[];
+    getRegisteredKeys(): string[];
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPCommandRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPCommandRegistry>;
+}
+
+declare class AXPCommandService {
+    private readonly registry;
+    private readonly executor;
+    register(key: string, loader: () => Promise<AXPCommand>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPCommandMiddleware): void;
+    exists(key: string): boolean;
+    getRegisteredKeys(): string[];
+    clear(): void;
+    execute<TInput = any, TResult = any>(key: string, input: TInput): Promise<AXPExecuteCommandResult<TResult> | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPCommandService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPCommandService>;
+}
+
+declare const AXP_COMMAND_MIDDLEWARE_SETUP: InjectionToken<void>;
+type AXPCommandMiddlewareEntry = (AXPCommandMiddleware | {
+    target: string | RegExp;
+    middleware: AXPCommandMiddleware;
+})[];
+declare function provideCommandMiddleware(entries: AXPCommandMiddlewareEntry): EnvironmentProviders;
+
+declare const AXP_COMMAND_SETUP: InjectionToken<void>;
+type AXPCommandLoader = {
+    key: string;
+    command: () => Type<AXPCommand> | Promise<Type<AXPCommand>>;
+};
+declare function provideCommandSetups(entries: AXPCommandLoader[]): EnvironmentProviders;
+declare function provideCommand(key: string, loader: () => Type<AXPCommand> | Promise<Type<AXPCommand>>): EnvironmentProviders;
+
+/**
+ * Build-time query metadata for AXPQuery implementations.
+ * Mirrors command metadata shape except there are no `outcomes` (queries only `fetch`).
+ * `inputs` / `outputs` are schema rows (same family as entity optionDefinitions).
+ */
+
+/** One input/output property description for query definitions (same as command schema rows). */
+type AXPQuerySchemaPropertyDefinition = AXPCommandSchemaPropertyDefinition;
+interface AXPQueryMetadataDefinition {
+    /** Runtime registration key (provideQuerySetups). */
+    key: string;
+    title: string;
+    description: string;
+    executionMode: AXPCommandExecutionMode;
+    /** Query input / filter parameters as schema rows. */
+    inputs?: AXPQuerySchemaPropertyDefinition[];
+    /** Documented result shape as schema rows. */
+    outputs?: AXPQuerySchemaPropertyDefinition[];
+    ai?: AXPCommandAiMetadata;
+    /** Optional list of surfaces that may list or invoke this query as a tool (e.g. AI assistants). */
+    capabilities?: AXPCommandCapability[];
+}
+
+/**
+ * Typed identity helper for query metadata sidecars.
+ */
+declare function defineQuery<T extends AXPQueryMetadataDefinition>(definition: T): T;
+
+type AXPQueryMiddleware<TInput = any, TResult = any> = (input: TInput, next: (input: TInput) => Promise<TResult>) => Promise<TResult>;
+declare function composeQueryMiddlewares<TInput, TResult>(middlewares: AXPQueryMiddleware<TInput, TResult>[]): (handler: (input: TInput) => Promise<TResult>) => (input: TInput) => Promise<TResult>;
+
+declare const AXP_QUERY_MIDDLEWARE_SETUP: InjectionToken<void>;
+type AXPQueryMiddlewareEntry = (AXPQueryMiddleware | {
+    key: string;
+    middleware: AXPQueryMiddleware;
+})[];
+declare function provideQueryMiddleware(entries: AXPQueryMiddlewareEntry): EnvironmentProviders;
+
+interface AXPQuery<TInput = any, TResult = any> {
+    fetch(input: TInput): Promise<TResult>;
+}
+
+declare const AXP_QUERY_SETUP: InjectionToken<void>;
+type AXPQueryLoaderEntry = {
+    key: string;
+    loader: () => Type<AXPQuery> | Promise<Type<AXPQuery>>;
+};
+declare function provideQuerySetups(entries: AXPQueryLoaderEntry[]): EnvironmentProviders;
+
+declare class AXPQueryExecutor {
+    private readonly injector;
+    private readonly registry;
+    private readonly extensions;
+    fetch<TInput = any, TResult = any>(key: string, input: TInput): Promise<TResult | null>;
+    private getPluginMiddlewares;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPQueryExecutor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPQueryExecutor>;
+}
+
+interface AXPQueryExtension {
+    target: string | RegExp;
+    middleware: AXPQueryMiddleware;
+}
+declare const AXP_QUERY_EXTENSION: InjectionToken<AXPQueryExtension[]>;
+
+declare class AXPQueryRegistry {
+    private registry;
+    private middlewares;
+    register(key: string, loader: () => Promise<AXPQuery>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPQueryMiddleware): void;
+    exists(key: string): boolean;
+    getLoader(key: string): (() => Promise<AXPQuery>) | undefined;
+    getMiddlewares(): readonly AXPQueryMiddleware[];
+    getRegisteredKeys(): string[];
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPQueryRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPQueryRegistry>;
+}
+
+declare class AXPQueryService {
+    private readonly registry;
+    private readonly executor;
+    register(key: string, loader: () => Promise<AXPQuery>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPQueryMiddleware): void;
+    exists(key: string): boolean;
+    getRegisteredKeys(): string[];
+    clear(): void;
+    fetch<TInput = any, TResult = any>(key: string, input: TInput): Promise<TResult | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPQueryService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPQueryService>;
+}
+
+interface AXPViewProvider<TInput = any> {
+    provide(input: TInput): Promise<AXPViewDefinition>;
+}
+
+type AXPViewMiddleware<TInput = any> = (input: TInput, next: (input: TInput) => Promise<AXPViewDefinition>) => Promise<AXPViewDefinition>;
+declare function composeViewMiddlewares<TInput>(middlewares: AXPViewMiddleware<TInput>[]): (handler: (input: TInput) => Promise<AXPViewDefinition>) => (input: TInput) => Promise<AXPViewDefinition>;
+
+declare class AXPViewRegistry {
+    private registry;
+    private middlewares;
+    register(key: string, loader: () => Promise<AXPViewProvider>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPViewMiddleware): void;
+    exists(key: string): boolean;
+    getLoader(key: string): (() => Promise<AXPViewProvider>) | undefined;
+    getMiddlewares(): readonly AXPViewMiddleware[];
+    getRegisteredKeys(): string[];
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPViewRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPViewRegistry>;
+}
+
+declare class AXPViewExecutor {
+    private readonly injector;
+    private readonly registry;
+    private readonly extensions;
+    provide<TInput = any>(key: string, input: TInput): Promise<AXPViewDefinition | null>;
+    private getPluginMiddlewares;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPViewExecutor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPViewExecutor>;
+}
+
+declare class AXPViewService {
+    private readonly registry;
+    private readonly executor;
+    register(key: string, loader: () => Promise<AXPViewProvider>): void;
+    unregister(key: string): boolean;
+    use(middleware: AXPViewMiddleware): void;
+    exists(key: string): boolean;
+    getRegisteredKeys(): string[];
+    clear(): void;
+    provide<TInput = any>(key: string, input: TInput): Promise<AXPViewDefinition | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPViewService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPViewService>;
+}
+
+interface AXPViewExtension {
+    target: string | RegExp;
+    middleware: AXPViewMiddleware;
+}
+declare const AXP_VIEW_EXTENSION: InjectionToken<AXPViewExtension[]>;
+
+declare const AXP_VIEW_SETUP: InjectionToken<void>;
+declare function provideViewSetups(providers: Provider[]): EnvironmentProviders;
+declare function provideViewSetup(key: string, loader: () => Promise<AXPViewProvider>): Provider;
+
+type AXPPolicyOptions = {
+    id: string;
+    sender: HTMLElement | AXComponent | AXPMetaData;
+    policies?: string[];
+};
+
+interface AXPPolicy {
+    apply(context: AXPPolicyEngineContext): Promise<void>;
+}
+declare class AXPPolicyEngineContext {
+    private _id;
+    private _sender;
+    private _visible;
+    private _enabled;
+    constructor(options: AXPPolicyOptions);
+    get sender(): AXPPolicyOptions['sender'];
+    get id(): string;
+    get visible(): boolean;
+    get enabled(): boolean;
+    setVisible(visible: boolean): this;
+    setEnabled(enabled: boolean): this;
+}
+
+type AXPPolicyEngineMiddleware = (context: AXPPolicyEngineContext, next: (context: AXPPolicyEngineContext) => Promise<void>) => Promise<void>;
+declare function composePolicyEngineMiddlewares(middlewares: AXPPolicyEngineMiddleware[]): (handler: (context: AXPPolicyEngineContext) => Promise<void>) => (context: AXPPolicyEngineContext) => Promise<void>;
+
+declare class AXPPolicyEngineRegistry {
+    private registry;
+    private middlewares;
+    private extensions;
+    private injector;
+    use(mw: AXPPolicyEngineMiddleware): void;
+    exists(key: string): boolean;
+    getPolicies(): string[];
+    register(key: string, loader: () => Promise<AXPPolicy>): void;
+    private getPluginMiddlewares;
+    execute(policy: string, instance: AXPPolicyOptions): Promise<AXPPolicyEngineContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPPolicyEngineRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPPolicyEngineRegistry>;
+}
+
+declare class AXPPolicyEngineService {
+    private registry;
+    apply(options: AXPPolicyOptions): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPPolicyEngineService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPPolicyEngineService>;
+}
+
+declare class AXPPolicyEngineDirective {
+    #private;
+    policy: i0.InputSignal<string | null | undefined>;
+    private service;
+    private elementRef;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPPolicyEngineDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<AXPPolicyEngineDirective, "[axp-apply-policy]", never, { "policy": { "alias": "axp-apply-policy"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface AXPPolicyExtension {
+    key: string;
+    middleware: AXPPolicyEngineMiddleware;
+}
+declare const AXP_POLICY_EXTENSION: InjectionToken<AXPPolicyExtension[]>;
+
+declare const AXP_POLICY_ENGINE_MIDDLEWARE_SETUP: InjectionToken<void>;
+type AXPPolicyLoader = {
+    key: string;
+    policy: () => Type<AXPPolicy> | Promise<Type<AXPPolicy>>;
+};
+declare function providePolicySetups(entries: AXPPolicyLoader[]): EnvironmentProviders;
+
+declare class AXPRuntimeModule {
+    private _commandSetup;
+    private _commandMiddlewareSetup;
+    private _querySetup;
+    private _queryMiddlewareSetup;
+    private _viewSetup;
+    private _viewMiddlewareSetup;
+    private _policyEngineSetup;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPRuntimeModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXPRuntimeModule, never, never, never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<AXPRuntimeModule>;
+}
+
+export { AXPCommandEventsService, AXPCommandExecutor, AXPCommandRegistry, AXPCommandService, AXPPolicyEngineContext, AXPPolicyEngineDirective, AXPPolicyEngineRegistry, AXPPolicyEngineService, AXPQueryExecutor, AXPQueryRegistry, AXPQueryService, AXPRuntimeModule, AXPViewExecutor, AXPViewRegistry, AXPViewService, AXP_COMMAND_EXTENSION, AXP_COMMAND_MIDDLEWARE_SETUP, AXP_COMMAND_SETUP, AXP_POLICY_ENGINE_MIDDLEWARE_SETUP, AXP_POLICY_EXTENSION, AXP_QUERY_EXTENSION, AXP_QUERY_MIDDLEWARE_SETUP, AXP_QUERY_SETUP, AXP_VIEW_EXTENSION, AXP_VIEW_SETUP, composeCommandMiddlewares, composePolicyEngineMiddlewares, composeQueryMiddlewares, composeViewMiddlewares, defineCommand, defineQuery, provideCommand, provideCommandMiddleware, provideCommandSetups, providePolicySetups, provideQueryMiddleware, provideQuerySetups, provideViewSetup, provideViewSetups };
+export type { AXPCommand, AXPCommandAiContractsMetadata, AXPCommandAiMetadata, AXPCommandAiNextStepMetadata, AXPCommandAiPerformanceCost, AXPCommandAiPerformanceMetadata, AXPCommandAiResultSemanticsMetadata, AXPCommandAiSafetyKind, AXPCommandAiSafetyMetadata, AXPCommandAiUsageMetadata, AXPCommandCapability, AXPCommandExecutionEvent, AXPCommandExecutionMode, AXPCommandExecutionStage, AXPCommandExtension, AXPCommandInterfaceDefinitionValue, AXPCommandMetadataDefinition, AXPCommandMiddleware, AXPCommandOutcomeDefinition, AXPCommandSchemaPropertyDefinition, AXPCommandValidationRuleValue, AXPExecuteCommandResultPromise, AXPPolicy, AXPPolicyEngineMiddleware, AXPPolicyExtension, AXPQuery, AXPQueryExtension, AXPQueryMetadataDefinition, AXPQueryMiddleware, AXPQuerySchemaPropertyDefinition, AXPViewExtension, AXPViewMiddleware, AXPViewProvider };