@xpert-ai/plugin-analytics-data-xpert 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,10 @@
 # data-xpert analytics provider
 
+The Live Dashboard Agent generates this provider’s Definition through `analytics_definition_connections` → `analytics_definition_inspect` → `analytics_definition_register`. Existing toolset/Integration credentials stay in their original configuration entries. Settings → Analytics is for viewing, correction and version management; users do not fill internal IDs. See [the authoring guide](../../../../docs/analytics-providers.md#automatic-definition-generation).
+Configure API URL and audience in Settings → Integrations → data-xpert Analytics. The Agent selects this integration from the authorized catalog.
+
 System plugin `@xpert-ai/plugin-analytics-data-xpert`; provider `data-xpert.ontology`, operation `action`, version 1.
 
-Contributes the data-xpert DataSource type through DataSourceType sync. Server configuration: baseUrl (including /api), audience, assistantCode, assistantXpertId, workspaceId. No database runner is required. Platform code has no ontology dependency.
 
 ```json
 {"resourceId":"datax-semantic-model-<published-model-id>","actionTypeCode":"sql.query_cube_slice","target":{"entityTypeCode":"semantic_cube","entityRef":"<published-model-id>::Sales"},"params":{"dimensions":["Region"],"measures":["Amount"],"filters":[{"field":"Region","op":"contains","value":"west"}],"limit":100},"parameterPaths":{"region":["filters","0","value"]}}
@@ -16,4 +18,28 @@ Run `corepack pnpm exec nx run @xpert-ai/plugin-analytics-data-xpert:test` with
 
 Discovery preserves each adapter's `definition` (identity, version, native metadata and instructions) and each Action's input schema. Semantic Model, OData and future registered read-only adapters share this transport without sharing query syntax.
 
+Before constructing a dashboard binding, call `dashboard_discover` with the selected source/provider and `requestJson` encoding:
+
+```json
+{"kind":"query-schema","payload":{"resourceId":"<discovered-resource>","actionTypeCode":"<discovered-read-action>","target":{"entityRef":"<canonical-target>"},"params":{},"parameterPaths":{}},"parameters":{}}
+```
+
+Omit `datasetId` to let the provider generate a valid local output key from the native payload, including its projection. An optional `datasetId` accepts a nonempty string of up to 512 characters: valid output keys (a letter followed by up to 79 letters, digits, `_`, `.` or `-`) are preserved; native references or other aliases are replaced with a generated key. Native resource IDs and targets are unchanged. Copy the returned `output.datasetId` as well as its fields.
+
+Use the Action's actual bounded query arguments in `params`. This plugin-owned discovery request executes the same authorized `/agent-workbench/analytics/query` path as preview, with the current actor, host row limit and cancellation signal. It does not require a new DataXpert discovery endpoint. Copy `items[0].metadata.output` into the preview binding and use the same native payload and parameter values. The response includes no business rows and is not a preview receipt; a successful `dashboard_preview` is still required before saving.
+
+Output fields retain exact native keys and declared types, roles and nullability, including empty results. Decimal/int64 cells remain exact strings. Stable field IDs are derived from native keys; duplicate semantic selectors use exact keys instead. Grain is left empty until query semantics establish uniqueness. Missing declarations fail with `DATAX_RESULT_SCHEMA_UNAVAILABLE`; duplicate native keys fail with `DATAX_RESULT_SCHEMA_AMBIGUOUS`. Legacy authored bindings can still execute without these optional declarations. Rediscover after changing the projection; existing incorrect saved bindings must be corrected and previewed before saving.
+
+Release compatibility: this path uses existing exports from the published SDK/contracts 3.26.1 and does not require a new host capability. The companion SDK change only adds optional column metadata to its TypeScript contract. Merge and publish this plugin's Changeset, then update the installed plugin; merging source alone does not update an existing deployment. Schema authoring requires DataXpert to supply declared column metadata (including the decimal fix in data-xpert PR #108). SAP query errors, authentication, and model-generated malformed tool calls remain separate acceptance checks.
+
+After building this plugin and Live Dashboard, run `node plugin-dev-harness/verify-datax-dashboard-schema.mjs` from the repository root. It invokes the real discovery and preview tools, provider and HTTP parser with published SDKs. Its local HTTP source and host-service fixtures do not establish customer SSO, SAP or browser acceptance.
+
 See [architecture and Binding usage](docs/index.mdx) and [compatibility and verification](docs/verification.mdx).
+# Public query diagnostics
+
+Non-success HTTP responses may contain the shared `xpert.analytics.diagnostic` v1 envelope.
+Only validated public causes and opaque audit references cross into `AnalyticsProviderError`.
+Malformed, sensitive, oversized or unfinished bodies use the existing status-only fallback.
+Parameter mapping failures use provider-authored repair guidance without echoing values.
+
+Structured diagnostics require `@xpert-ai/contracts` and `@xpert-ai/plugin-sdk` 3.32.0 or a compatible later 3.x release.

package/dist/index.js

@@ -5,7 +5,7 @@ const node_path_1 = require("node:path");
 const plugin_1 = require("./lib/plugin");
 const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '../package.json'), 'utf8'));
 const plugin = {
-    meta: { name: packageJson.name, version: packageJson.version, category: 'database', displayName: 'data-xpert Analytics', description: 'data-xpert Analytics', author: 'XpertAI', level: packageJson.xpert.plugin.level, artifactNamespace: packageJson.xpert.plugin.artifactNamespace },
+    meta: { name: packageJson.name, version: packageJson.version, category: 'tools', displayName: 'data-xpert Analytics', description: 'data-xpert Analytics', author: 'XpertAI', level: packageJson.xpert.plugin.level, artifactNamespace: packageJson.xpert.plugin.artifactNamespace },
     register: () => ({ module: plugin_1.AnalyticsDataXpertPlugin })
 };
 exports.default = plugin;

package/dist/lib/client.d.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsBinding, AnalyticsValue, JSONValue, AnalyticsDiscoveryResult } from '@xpert-ai/contracts';
+export { dataXpertPayloadSchema } from './payload';
+import { type AnalyticsProviderContext, type AnalyticsProviderResult, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+export type DataXpertClientContext = Pick<AnalyticsProviderContext, 'actor' | 'options' | 'signal' | 'deadlineAt' | 'maxRows'>;
+export declare class DataXpertAnalyticsClient {
+    private readonly runtime;
+    constructor(runtime: RuntimeCapabilityRegistry);
+    discover(request: JSONValue, context: DataXpertClientContext): Promise<AnalyticsDiscoveryResult>;
+    private request;
+    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: DataXpertClientContext): Promise<AnalyticsProviderResult>;
+    private query;
+}
+/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
+export declare function bindParameters(params: Record<string, JSONValue>, paths: Record<string, string[]>, parameters: Record<string, AnalyticsValue>): Record<string, JSONValue>;

package/dist/lib/client.js

@@ -0,0 +1,169 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataXpertAnalyticsClient = exports.dataXpertPayloadSchema = void 0;
+exports.bindParameters = bindParameters;
+const common_1 = require("@nestjs/common");
+const v3_1 = require("zod/v3");
+const discovery_1 = require("./discovery");
+const diagnostic_1 = require("./diagnostic");
+const payload_1 = require("./payload");
+var payload_2 = require("./payload");
+Object.defineProperty(exports, "dataXpertPayloadSchema", { enumerable: true, get: function () { return payload_2.dataXpertPayloadSchema; } });
+const import_targets_1 = require("./import-targets");
+const result_schema_1 = require("./result-schema");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
+const json = v3_1.z.lazy(() => v3_1.z.union([scalar, v3_1.z.array(json), v3_1.z.record(json)]));
+const querySchemaRequestSchema = v3_1.z.object({
+    kind: v3_1.z.literal('query-schema'), datasetId: v3_1.z.string().min(1).max(512).optional(),
+    payload: payload_1.dataXpertPayloadSchema, parameters: v3_1.z.record(scalar).default({})
+}).strict();
+/** Trusted DataSource configuration; never merge it with payloads, controls or discovery requests. */
+const optionsSchema = v3_1.z.object({
+    baseUrl: v3_1.z.string().url(), audience: v3_1.z.string().min(1),
+    assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid()
+}).strict();
+const responseSchema = v3_1.z.object({
+    effect: v3_1.z.object({ version: v3_1.z.literal(2), kind: v3_1.z.enum(['rows', 'series', 'entity']),
+        columns: v3_1.z.array(result_schema_1.dataXpertResultColumnSchema),
+        rows: v3_1.z.array(v3_1.z.record(scalar)),
+        summary: v3_1.z.object({ rowCount: v3_1.z.number().int().nonnegative(), returnedRowCount: v3_1.z.number().int().nonnegative(), truncated: v3_1.z.boolean() }) }),
+    fetchedAt: v3_1.z.string().datetime(), executionId: v3_1.z.string(), auditRef: v3_1.z.string(), fromCache: v3_1.z.literal(false)
+});
+let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async discover(request, context) {
+        const importing = import_targets_1.importTargetRequest.safeParse(request);
+        if (importing.success)
+            return (0, import_targets_1.discoverImportTargets)(importing.data, browse => this.discover(browse, context));
+        if (request && typeof request === 'object' && !Array.isArray(request) && request.kind === 'query-schema') {
+            const parsed = querySchemaRequestSchema.parse(request);
+            const datasetId = (0, result_schema_1.createDataXpertDatasetId)(parsed.payload, parsed.datasetId);
+            const result = await this.query(datasetId, parsed.payload, parsed.parameters, context);
+            return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({
+                items: [{ id: datasetId, name: datasetId, kind: 'dataset',
+                        metadata: { output: (0, result_schema_1.createDataXpertOutput)(datasetId, result.effect.columns) } }],
+                queryContract: discovery_1.dataXpertQueryContract
+            });
+        }
+        const empty = request && typeof request === 'object' && !Array.isArray(request) && Object.keys(request).length === 0;
+        const parsed = discovery_1.dataXpertDiscoveryRequestSchema.parse(empty ? { kind: 'resources' } : request);
+        const response = await this.request('discover', context, { request: parsed });
+        const result = v3_1.z.object({ items: v3_1.z.array(v3_1.z.unknown()),
+            nextRequest: json.optional() }).strict().parse(await boundedJson(response));
+        return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({ ...result, queryContract: discovery_1.dataXpertQueryContract });
+    }
+    async request(endpoint, context, body) {
+        context.signal.throwIfAborted();
+        const options = optionsSchema.parse(context.options);
+        const base = new URL(options.baseUrl);
+        if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+            throw new Error('DATAX_URL_INVALID');
+        const token = await this.runtime.require(plugin_sdk_1.ActorTokenRuntimeFactoryCapability).createScopedApi(context.actor).getToken({ audience: options.audience });
+        context.signal.throwIfAborted();
+        const response = await fetch(`${base.href.replace(/\/$/, '')}/agent-workbench/analytics/${endpoint}`, {
+            method: 'POST', redirect: 'error', signal: context.signal,
+            headers: { Authorization: `Bearer ${token.token}`, 'Content-Type': 'application/json', 'organization-id': context.actor.organizationId },
+            body: JSON.stringify({ assistant: { code: options.assistantCode, xpertId: options.assistantXpertId, workspaceId: options.workspaceId }, ...body })
+        });
+        if (!response.ok) {
+            const error = await (0, diagnostic_1.readAnalyticsHttpError)(response, context.signal, context.deadlineAt);
+            context.signal.throwIfAborted();
+            throw error ?? new Error(`DATAX_QUERY_HTTP_${response.status}`);
+        }
+        return response;
+    }
+    async execute(binding, parameters, context) {
+        const payload = payload_1.dataXpertPayloadSchema.parse(binding.payload);
+        const result = await this.query(binding.id, payload, parameters, context);
+        return { columns: result.effect.columns, rows: result.effect.rows,
+            completeness: { returnedRows: result.effect.summary.returnedRowCount, totalRows: result.effect.summary.rowCount,
+                totalAccuracy: result.effect.summary.truncated ? 'unknown' : 'exact', scope: result.effect.summary.truncated ? 'page' : 'full_query_result',
+                truncated: result.effect.summary.truncated }, sourceFetchedAt: result.fetchedAt,
+            upstreamExecutionId: result.executionId, auditRef: result.auditRef };
+    }
+    async query(id, payload, parameters, context) {
+        const response = await this.request('query', context, {
+            binding: { id, resourceId: payload.resourceId, actionTypeCode: payload.actionTypeCode, target: payload.target,
+                params: bindParameters(payload.params, payload.parameterPaths, parameters) }, maxRows: context.maxRows
+        });
+        return responseSchema.parse(await boundedJson(response));
+    }
+};
+exports.DataXpertAnalyticsClient = DataXpertAnalyticsClient;
+exports.DataXpertAnalyticsClient = DataXpertAnalyticsClient = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [Object])
+], DataXpertAnalyticsClient);
+/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
+function bindParameters(params, paths, parameters) {
+    const result = structuredClone(params);
+    if (Object.keys(parameters).some((name) => !Object.hasOwn(paths, name)) || Object.keys(paths).some((name) => !Object.hasOwn(parameters, name)))
+        throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_MAPPING_INVALID');
+    if (new Set(Object.values(paths).map((path) => JSON.stringify(path))).size !== Object.keys(paths).length)
+        throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_MAPPING_INVALID');
+    for (const [name, path] of Object.entries(paths)) {
+        let current = result;
+        for (const [index, key] of path.entries()) {
+            if (['__proto__', 'prototype', 'constructor'].includes(key) || !current || typeof current !== 'object' || !Object.hasOwn(current, key))
+                throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_INVALID');
+            if (Array.isArray(current)) {
+                if (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= current.length)
+                    throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_INVALID');
+                const position = Number(key);
+                if (index === path.length - 1) {
+                    if (current[position] !== null && typeof current[position] === 'object')
+                        throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                    current[position] = parameters[name];
+                }
+                else
+                    current = current[position];
+            }
+            else if (index === path.length - 1) {
+                if (current[key] !== null && typeof current[key] === 'object')
+                    throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                current[key] = parameters[name];
+            }
+            else
+                current = current[key];
+        }
+    }
+    return result;
+}
+async function boundedJson(response) {
+    if (!response.body)
+        throw new Error('DATAX_EMPTY_RESPONSE');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 2_500_000)
+                throw new Error('DATAX_RESPONSE_TOO_LARGE');
+            chunks.push(chunk.value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    finally {
+        await reader.cancel();
+    }
+}

package/dist/lib/diagnostic.d.ts

@@ -0,0 +1,10 @@
+import { AnalyticsProviderError } from '@xpert-ai/plugin-sdk';
+declare const parameterMessages: {
+    DATAX_PARAMETER_MAPPING_INVALID: string;
+    DATAX_PARAMETER_PATH_INVALID: string;
+    DATAX_PARAMETER_PATH_NOT_SCALAR: string;
+};
+export declare function dataXpertParameterError(code: keyof typeof parameterMessages): AnalyticsProviderError;
+/** Error responses get a smaller byte/time budget than results. Never retain or echo an unknown body. */
+export declare function readAnalyticsHttpError(response: Response, signal: AbortSignal, deadlineAt?: number): Promise<AnalyticsProviderError | undefined>;
+export {};

package/dist/lib/diagnostic.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataXpertParameterError = dataXpertParameterError;
+exports.readAnalyticsHttpError = readAnalyticsHttpError;
+const contracts_1 = require("@xpert-ai/contracts");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const parameterMessages = {
+    DATAX_PARAMETER_MAPPING_INVALID: 'Parameter names must match parameterPaths exactly, with a distinct target path for each parameter.',
+    DATAX_PARAMETER_PATH_INVALID: 'parameterPaths are relative to params. Omit the leading params segment and target an existing scalar, for example ["slicers","1","value"].',
+    DATAX_PARAMETER_PATH_NOT_SCALAR: 'A parameter path must target a scalar value, not an entire object or array. Select the existing filter value field.'
+};
+function dataXpertParameterError(code) {
+    return new plugin_sdk_1.AnalyticsProviderError({ schema: 'xpert.analytics.diagnostic', version: 1,
+        code, stage: 'validation', retryable: false, message: parameterMessages[code] });
+}
+/** Error responses get a smaller byte/time budget than results. Never retain or echo an unknown body. */
+async function readAnalyticsHttpError(response, signal, deadlineAt) {
+    if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') ?? '') || !response.body) {
+        await response.body?.cancel().catch(() => undefined);
+        return undefined;
+    }
+    const reader = response.body.getReader();
+    const budget = Math.min(1000, Math.max(0, (deadlineAt ?? Infinity) - Date.now()));
+    let timer;
+    let abort = () => undefined;
+    const cancelled = new Promise(resolve => {
+        abort = () => resolve(undefined);
+        timer = setTimeout(abort, budget);
+        signal.addEventListener('abort', abort, { once: true });
+    });
+    const read = async () => {
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 16_384)
+                return undefined;
+            chunks.push(chunk.value);
+        }
+        const diagnostic = (0, contracts_1.parseAnalyticsDiagnostic)(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        return diagnostic && new plugin_sdk_1.AnalyticsProviderError(diagnostic);
+    };
+    try {
+        signal.throwIfAborted();
+        return await Promise.race([read(), cancelled]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', abort);
+        await reader.cancel().catch(() => undefined);
+    }
+}

package/dist/lib/discovery.js

@@ -22,6 +22,7 @@ exports.dataXpertDiscoveryRequestSchema = v3_1.z.discriminatedUnion('kind', [
 exports.dataXpertQueryContract = {
     operation: 'action', contractVersion: 1,
     payloadSchema: {
+        'x-xpert-import': { version: 1, request: { kind: 'import-targets' } },
         type: 'object', additionalProperties: false,
         required: ['resourceId', 'actionTypeCode', 'target', 'params', 'parameterPaths'],
         properties: {
@@ -47,6 +48,7 @@ exports.dataXpertQueryContract = {
         'Entity metadata.definition contains adapterId, contractVersion, metadata and instructions. Follow that adapter-specific definition and the discovered Action inputSchema/inputHint. Preserve canonical targets, resource IDs and exact field names. Do not infer adapter types from names or apply one adapter\'s query, filter or time rules to another.',
         'Use only published metadata and authorized previews to establish business metrics, time axes, supported filters and complete aggregation. Missing metadata does not authorize guessing; obtain sufficient evidence before generating a time filter.',
         'Use parameterPaths relative to params to replace an existing scalar value, for example {region:["filters","0","value"]}. Paths must be unique. Never interpolate values into query text. Controls supply scalar values; arrays remain static unless the native Action explicitly supports another declared scalar mapping. Null handling and filter operators are defined by the Action schema and adapter instructions.',
-        'Only read-only Actions allowed by the current viewer policy are returned. Map output sourceField to returned column keys (or an explicit semanticRef). Numeric JSON cells require float64; decimal/int64 require exact strings. Preview to verify types, grain and completeness before binding charts. A partial page is not a complete business aggregate.'
+        'Before authoring a binding, use dashboard_discover with the same source/providerId and requestJson encoding {kind:"query-schema",payload:<native Action envelope>,parameters:<mapped scalar values, or {}>}. This runs that bounded read-only Action under the current viewer policy; respect the native Action limits and filters. It returns items[0].metadata.output without business rows. Omit datasetId to let the provider generate a valid output key. Copy this output into the dashboard_preview binding, preserving datasetId, field IDs, sourceField, logicalType, role and nullable. Decimal/int64 remain exact strings; do not infer types from sample cells or names. If declarations are missing, obtain source metadata instead of guessing.',
+        'The discovered output has empty grain because column roles alone do not prove uniqueness. Declare grain only when supported by query semantics. Always run dashboard_preview with the same payload and parameter values to validate the binding and obtain a preview receipt before saving; schema discovery is not a preview receipt. Re-discover after changing the query projection. A partial page is not a complete business aggregate.'
     ].join(' ')
 };

package/dist/lib/import-targets.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod/v3';
+import type { AnalyticsDiscoveryResult, JSONValue } from '@xpert-ai/contracts';
+/** Provider-owned reference migration. Native Action arguments and output contracts remain unchanged. */
+export declare const importTargetRequest: z.ZodObject<{
+    kind: z.ZodLiteral<"import-targets">;
+    payload: z.ZodObject<{
+        resourceId: z.ZodString;
+        actionTypeCode: z.ZodString;
+        target: z.ZodEffects<z.ZodObject<{
+            entityId: z.ZodOptional<z.ZodString>;
+            entityTypeCode: z.ZodOptional<z.ZodString>;
+            entityRef: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        }, {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        }>, {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        }, {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        }>;
+        params: z.ZodRecord<z.ZodString, z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
+        parameterPaths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strict", z.ZodTypeAny, {
+        params: Record<string, JSONValue>;
+        resourceId: string;
+        target: {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        };
+        actionTypeCode: string;
+        parameterPaths: Record<string, string[]>;
+    }, {
+        params: Record<string, JSONValue>;
+        resourceId: string;
+        target: {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        };
+        actionTypeCode: string;
+        parameterPaths?: Record<string, string[]> | undefined;
+    }>;
+    browse: z.ZodDefault<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"resources">;
+        after: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "resources";
+        after?: string | undefined;
+    }, {
+        kind: "resources";
+        after?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"entities">;
+        resourceId: z.ZodString;
+        entityTypeCode: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "entities";
+        resourceId: string;
+        entityTypeCode?: string | undefined;
+        query?: string | undefined;
+    }, {
+        kind: "entities";
+        resourceId: string;
+        entityTypeCode?: string | undefined;
+        query?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"actions">;
+        resourceId: z.ZodString;
+        target: z.ZodObject<{
+            entityTypeCode: z.ZodString;
+            entityRef: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            entityTypeCode: string;
+            entityRef: string;
+        }, {
+            entityTypeCode: string;
+            entityRef: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "actions";
+        resourceId: string;
+        target: {
+            entityTypeCode: string;
+            entityRef: string;
+        };
+    }, {
+        kind: "actions";
+        resourceId: string;
+        target: {
+            entityTypeCode: string;
+            entityRef: string;
+        };
+    }>]>>;
+}, "strict", z.ZodTypeAny, {
+    kind: "import-targets";
+    payload: {
+        params: Record<string, JSONValue>;
+        resourceId: string;
+        target: {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        };
+        actionTypeCode: string;
+        parameterPaths: Record<string, string[]>;
+    };
+    browse: {
+        kind: "resources";
+        after?: string | undefined;
+    } | {
+        kind: "entities";
+        resourceId: string;
+        entityTypeCode?: string | undefined;
+        query?: string | undefined;
+    } | {
+        kind: "actions";
+        resourceId: string;
+        target: {
+            entityTypeCode: string;
+            entityRef: string;
+        };
+    };
+}, {
+    kind: "import-targets";
+    payload: {
+        params: Record<string, JSONValue>;
+        resourceId: string;
+        target: {
+            entityTypeCode?: string | undefined;
+            entityRef?: string | undefined;
+            entityId?: string | undefined;
+        };
+        actionTypeCode: string;
+        parameterPaths?: Record<string, string[]> | undefined;
+    };
+    browse?: {
+        kind: "resources";
+        after?: string | undefined;
+    } | {
+        kind: "entities";
+        resourceId: string;
+        entityTypeCode?: string | undefined;
+        query?: string | undefined;
+    } | {
+        kind: "actions";
+        resourceId: string;
+        target: {
+            entityTypeCode: string;
+            entityRef: string;
+        };
+    } | undefined;
+}>;
+export declare function discoverImportTargets(input: z.infer<typeof importTargetRequest>, discover: (request: JSONValue) => Promise<AnalyticsDiscoveryResult>): Promise<AnalyticsDiscoveryResult>;

package/dist/lib/import-targets.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importTargetRequest = void 0;
+exports.discoverImportTargets = discoverImportTargets;
+const v3_1 = require("zod/v3");
+const payload_1 = require("./payload");
+const discovery_1 = require("./discovery");
+/** Provider-owned reference migration. Native Action arguments and output contracts remain unchanged. */
+exports.importTargetRequest = v3_1.z.object({
+    kind: v3_1.z.literal('import-targets'), payload: payload_1.dataXpertPayloadSchema,
+    browse: discovery_1.dataXpertDiscoveryRequestSchema.default({ kind: 'resources' })
+}).strict();
+async function discoverImportTargets(input, discover) {
+    const result = await discover(input.browse);
+    const wrap = (browse) => ({ kind: 'import-targets', payload: { ...input.payload, params: {}, parameterPaths: {} }, browse });
+    return { ...result,
+        items: result.items.flatMap(item => {
+            const next = discovery_1.dataXpertDiscoveryRequestSchema.safeParse(item.inspectRequest);
+            if (next.success && next.data.kind === 'actions') {
+                const target = next.data.target;
+                if (input.payload.target.entityTypeCode && target.entityTypeCode !== input.payload.target.entityTypeCode)
+                    return [];
+                return [{ id: item.id, name: item.name, kind: 'dataset', description: item.description,
+                        metadata: { schema: 'xpert.analytics.import-target', version: 1,
+                            payloadPatch: { resourceId: next.data.resourceId, target } } }];
+            }
+            return item.inspectRequest ? [{ ...item, inspectRequest: wrap(item.inspectRequest) }] : [];
+        }),
+        ...(result.nextRequest ? { nextRequest: wrap(result.nextRequest) } : {}) };
+}

package/dist/lib/integration.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod/v3';
+import type { IIntegration } from '@xpert-ai/contracts';
+import { type IntegrationStrategy, type TIntegrationStrategyParams } from '@xpert-ai/plugin-sdk';
+export declare const DATA_XPERT_INTEGRATION = "analytics-data-xpert";
+export declare const connectionSchema: z.ZodObject<{
+    baseUrl: z.ZodEffects<z.ZodString, string, string>;
+    audience: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    baseUrl: string;
+    audience: string;
+}, {
+    baseUrl: string;
+    audience: string;
+}>;
+export declare class DataXpertAnalyticsIntegration implements IntegrationStrategy<z.output<typeof connectionSchema>> {
+    readonly meta: {
+        name: string;
+        label: {
+            en_US: string;
+            zh_Hans: string;
+        };
+        icon: {
+            type: "font";
+            value: string;
+        };
+        schema: {
+            type: "object";
+            properties: {
+                baseUrl: {
+                    type: "string";
+                    title: string;
+                };
+                audience: {
+                    type: "string";
+                    title: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    prepareConfig(config: z.output<typeof connectionSchema>): {
+        baseUrl: string;
+        audience: string;
+    };
+    validateConfig(config: z.output<typeof connectionSchema>): Promise<void>;
+    execute(_integration: IIntegration<z.output<typeof connectionSchema>>, _payload: TIntegrationStrategyParams): Promise<never>;
+}

package/dist/lib/integration.js

@@ -0,0 +1,29 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataXpertAnalyticsIntegration = exports.connectionSchema = exports.DATA_XPERT_INTEGRATION = void 0;
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+exports.DATA_XPERT_INTEGRATION = 'analytics-data-xpert';
+exports.connectionSchema = v3_1.z.object({
+    baseUrl: v3_1.z.string().url().refine(value => { const url = new URL(value); return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash; }),
+    audience: v3_1.z.string().min(1)
+}).strict();
+let DataXpertAnalyticsIntegration = class DataXpertAnalyticsIntegration {
+    constructor() {
+        this.meta = { name: exports.DATA_XPERT_INTEGRATION, label: { en_US: 'data-xpert Analytics', zh_Hans: 'data-xpert 分析服务' }, icon: { type: 'font', value: 'ri-bar-chart-box-line' },
+            schema: { type: 'object', properties: { baseUrl: { type: 'string', title: 'API URL' }, audience: { type: 'string', title: 'OIDC audience' } }, required: ['baseUrl', 'audience'] } };
+    }
+    prepareConfig(config) { return exports.connectionSchema.parse(config); }
+    async validateConfig(config) { exports.connectionSchema.parse(config); }
+    async execute(_integration, _payload) { throw new Error('DATAX_USE_ANALYTICS_RUNTIME'); }
+};
+exports.DataXpertAnalyticsIntegration = DataXpertAnalyticsIntegration;
+exports.DataXpertAnalyticsIntegration = DataXpertAnalyticsIntegration = __decorate([
+    (0, plugin_sdk_1.IntegrationStrategyKey)(exports.DATA_XPERT_INTEGRATION)
+], DataXpertAnalyticsIntegration);

package/dist/lib/payload.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod/v3';
+import type { JSONValue } from '@xpert-ai/contracts';
+/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
+export declare const dataXpertPayloadSchema: z.ZodObject<{
+    resourceId: z.ZodString;
+    actionTypeCode: z.ZodString;
+    target: z.ZodEffects<z.ZodObject<{
+        entityId: z.ZodOptional<z.ZodString>;
+        entityTypeCode: z.ZodOptional<z.ZodString>;
+        entityRef: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }>, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }>;
+    params: z.ZodRecord<z.ZodString, z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
+    parameterPaths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+}, "strict", z.ZodTypeAny, {
+    params: Record<string, JSONValue>;
+    resourceId: string;
+    target: {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    };
+    actionTypeCode: string;
+    parameterPaths: Record<string, string[]>;
+}, {
+    params: Record<string, JSONValue>;
+    resourceId: string;
+    target: {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    };
+    actionTypeCode: string;
+    parameterPaths?: Record<string, string[]> | undefined;
+}>;

package/dist/lib/payload.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataXpertPayloadSchema = void 0;
+const v3_1 = require("zod/v3");
+const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
+const json = v3_1.z.lazy(() => v3_1.z.union([scalar, v3_1.z.array(json), v3_1.z.record(json)]));
+/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
+exports.dataXpertPayloadSchema = v3_1.z.object({
+    resourceId: v3_1.z.string().min(1).max(160), actionTypeCode: v3_1.z.string().min(1).max(160),
+    target: v3_1.z.object({
+        entityId: v3_1.z.string().trim().min(1).max(256).optional(),
+        entityTypeCode: v3_1.z.string().trim().min(1).max(256).optional(),
+        entityRef: v3_1.z.string().trim().min(1).max(512).optional()
+    }).strict().refine(target => Boolean(target.entityId || target.entityRef), 'Target reference is required'),
+    params: v3_1.z.record(json),
+    parameterPaths: v3_1.z.record(v3_1.z.array(v3_1.z.string().min(1)).min(1).max(8)).default({})
+}).strict();

package/dist/lib/plugin.js

@@ -7,11 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsDataXpertPlugin = void 0;
+const client_1 = require("./client");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const provider_1 = require("./provider");
+const cqrs_1 = require("@nestjs/cqrs");
+const integration_1 = require("./integration");
 let AnalyticsDataXpertPlugin = class AnalyticsDataXpertPlugin {
 };
 exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin;
 exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin = __decorate([
-    (0, plugin_sdk_1.XpertServerPlugin)({ providers: [provider_1.DataXpertAnalyticsProvider] })
+    (0, plugin_sdk_1.XpertServerPlugin)({ imports: [cqrs_1.CqrsModule], providers: [provider_1.DataXpertAnalyticsProvider, client_1.DataXpertAnalyticsClient, integration_1.DataXpertAnalyticsIntegration] })
 ], AnalyticsDataXpertPlugin);

package/dist/lib/provider.d.ts

@@ -1,61 +1,61 @@
-import { z } from 'zod/v3';
-import type { AnalyticsBinding, AnalyticsProviderDescriptor, AnalyticsValue, JSONValue, AnalyticsDiscoveryResult } from '@xpert-ai/contracts';
-import { type AnalyticsQueryProvider, type AnalyticsProviderContext, type AnalyticsProviderResult, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
-/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
-export declare const dataXpertPayloadSchema: z.ZodObject<{
-    resourceId: z.ZodString;
-    actionTypeCode: z.ZodString;
-    target: z.ZodEffects<z.ZodObject<{
-        entityId: z.ZodOptional<z.ZodString>;
-        entityTypeCode: z.ZodOptional<z.ZodString>;
-        entityRef: z.ZodOptional<z.ZodString>;
-    }, "strict", z.ZodTypeAny, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }>, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }>;
-    params: z.ZodRecord<z.ZodString, z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
-    parameterPaths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
-}, "strict", z.ZodTypeAny, {
-    params: Record<string, JSONValue>;
-    resourceId: string;
-    target: {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
+import { QueryBus } from '@nestjs/cqrs';
+import type { AnalyticsBinding, AnalyticsValue, JSONValue } from '@xpert-ai/contracts';
+import { type AnalyticsQueryProvider, type AnalyticsProviderContext, type AnalyticsDefinitionAuthoring, type DataSourceActor } from '@xpert-ai/plugin-sdk';
+import { DataXpertAnalyticsClient } from './client';
+export declare class DataXpertAnalyticsProvider implements AnalyticsQueryProvider {
+    private readonly engine;
+    private readonly queries;
+    constructor(engine: DataXpertAnalyticsClient, queries: QueryBus);
+    readonly descriptor: {
+        id: string;
+        name: string;
+        sourceKinds: ["definition"];
+        operations: {
+            name: string;
+            contractVersion: number;
+            readOnly: true;
+        }[];
     };
-    actionTypeCode: string;
-    parameterPaths: Record<string, string[]>;
-}, {
-    params: Record<string, JSONValue>;
-    resourceId: string;
-    target: {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
+    readonly authoring: AnalyticsDefinitionAuthoring;
+    private authoringContext;
+    readonly configuration: {
+        kind: "definition";
+        connection: "integration";
+        schema: {
+            type: string;
+            properties: {
+                integrationId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+                assistantCode: {
+                    type: string;
+                    title: string;
+                };
+                assistantXpertId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+                workspaceId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
     };
-    actionTypeCode: string;
-    parameterPaths?: Record<string, string[]> | undefined;
-}>;
-export declare class DataXpertAnalyticsProvider implements AnalyticsQueryProvider {
-    private readonly runtime;
-    readonly descriptor: AnalyticsProviderDescriptor;
-    constructor(runtime: RuntimeCapabilityRegistry);
-    discover(request: JSONValue, context: AnalyticsProviderContext): Promise<AnalyticsDiscoveryResult>;
-    private request;
-    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: AnalyticsProviderContext): Promise<AnalyticsProviderResult>;
+    validateConfiguration(options: Record<string, JSONValue>, actor: DataSourceActor): Promise<{
+        assistantCode: string;
+        assistantXpertId: string;
+        workspaceId: string;
+        integrationId: string;
+    }>;
+    private connection;
+    private run;
+    discover(request: JSONValue, context: AnalyticsProviderContext): Promise<import("@xpert-ai/contracts").AnalyticsDiscoveryResult>;
+    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: AnalyticsProviderContext): Promise<import("@xpert-ai/plugin-sdk").AnalyticsProviderResult>;
 }
-/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
-export declare function bindParameters(params: Record<string, JSONValue>, paths: Record<string, string[]>, parameters: Record<string, AnalyticsValue>): Record<string, JSONValue>;

package/dist/lib/provider.js

@@ -8,157 +8,70 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataXpertAnalyticsProvider = exports.dataXpertPayloadSchema = void 0;
-exports.bindParameters = bindParameters;
-const common_1 = require("@nestjs/common");
+exports.DataXpertAnalyticsProvider = void 0;
+const cqrs_1 = require("@nestjs/cqrs");
 const v3_1 = require("zod/v3");
-const discovery_1 = require("./discovery");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
-const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
-const json = v3_1.z.lazy(() => v3_1.z.union([scalar, v3_1.z.array(json), v3_1.z.record(json)]));
-/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
-exports.dataXpertPayloadSchema = v3_1.z.object({
-    resourceId: v3_1.z.string().min(1).max(160), actionTypeCode: v3_1.z.string().min(1).max(160),
-    target: v3_1.z.object({
-        entityId: v3_1.z.string().trim().min(1).max(256).optional(),
-        entityTypeCode: v3_1.z.string().trim().min(1).max(256).optional(),
-        entityRef: v3_1.z.string().trim().min(1).max(512).optional()
-    }).strict().refine(target => Boolean(target.entityId || target.entityRef), 'Target reference is required'),
-    params: v3_1.z.record(json),
-    parameterPaths: v3_1.z.record(v3_1.z.array(v3_1.z.string().min(1)).min(1).max(8)).default({})
-}).strict();
-/** Trusted DataSource configuration; never merge it with payloads, controls or discovery requests. */
-const optionsSchema = v3_1.z.object({
-    baseUrl: v3_1.z.string().url(), audience: v3_1.z.string().min(1),
-    assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid()
-}).strict();
-const responseSchema = v3_1.z.object({
-    effect: v3_1.z.object({ version: v3_1.z.literal(2), kind: v3_1.z.enum(['rows', 'series', 'entity']),
-        columns: v3_1.z.array(v3_1.z.object({ key: v3_1.z.string(), semanticRef: v3_1.z.string().optional() })),
-        rows: v3_1.z.array(v3_1.z.record(scalar)),
-        summary: v3_1.z.object({ rowCount: v3_1.z.number().int().nonnegative(), returnedRowCount: v3_1.z.number().int().nonnegative(), truncated: v3_1.z.boolean() }) }),
-    fetchedAt: v3_1.z.string().datetime(), executionId: v3_1.z.string(), auditRef: v3_1.z.string(), fromCache: v3_1.z.literal(false)
-});
+const client_1 = require("./client");
+const integration_1 = require("./integration");
+const optionsSchema = v3_1.z.object({ integrationId: v3_1.z.string().uuid(), assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid() }).strict();
 let DataXpertAnalyticsProvider = class DataXpertAnalyticsProvider {
-    constructor(runtime) {
-        this.runtime = runtime;
-        this.descriptor = {
-            id: 'data-xpert.ontology', name: 'data-xpert Ontology', dataSourceTypes: ['data-xpert'],
-            operations: [{ name: 'action', contractVersion: 1, readOnly: true }],
-            connectionType: { type: 'data-xpert', name: 'data-xpert', configuration: {
-                    type: 'object', properties: { baseUrl: { type: 'string', title: 'API URL' }, audience: { type: 'string', title: 'OIDC audience' },
-                        assistantCode: { type: 'string', title: 'Assistant code' }, assistantXpertId: { type: 'string', title: 'Assistant Xpert ID' },
-                        workspaceId: { type: 'string', title: 'Workspace ID' } },
-                    required: ['baseUrl', 'audience', 'assistantCode', 'assistantXpertId', 'workspaceId'], additionalProperties: false
-                } }
+    constructor(engine, queries) {
+        this.engine = engine;
+        this.queries = queries;
+        this.descriptor = { id: 'data-xpert.ontology', name: 'data-xpert Ontology', sourceKinds: ['definition'], operations: [{ name: 'action', contractVersion: 1, readOnly: true }] };
+        this.authoring = {
+            integrationProvider: integration_1.DATA_XPERT_INTEGRATION,
+            inspectSchema: { type: 'object', additionalProperties: true },
+            definitionSchema: { type: 'object', properties: {}, additionalProperties: false },
+            instructions: 'The system supplies integration and current Assistant identity. Inspect the authorized ontology, following nextRequest/inspectRequest. Register with definition {} then discover and preview the returned source. Do not ask the user for integration, workspace or Assistant IDs.',
+            inspect: (input, context) => this.run(this.authoringContext(context), resolved => this.engine.discover(input, resolved)).then(result => JSON.parse(JSON.stringify(result))),
+            prepare: async (input, context) => {
+                v3_1.z.object({}).strict().parse(input);
+                const resolved = this.authoringContext(context);
+                await this.run(resolved, current => this.engine.discover({}, current));
+                return resolved.options;
+            }
         };
+        this.configuration = { kind: 'definition', connection: 'integration', schema: {
+                type: 'object', properties: { integrationId: { type: 'string', format: 'uuid', title: 'Integration ID' }, assistantCode: { type: 'string', title: 'Assistant code' }, assistantXpertId: { type: 'string', format: 'uuid', title: 'Assistant ID' }, workspaceId: { type: 'string', format: 'uuid', title: 'Workspace ID' } },
+                required: ['integrationId', 'assistantCode', 'assistantXpertId', 'workspaceId'], additionalProperties: false
+            } };
     }
-    async discover(request, context) {
-        const empty = request && typeof request === 'object' && !Array.isArray(request) && Object.keys(request).length === 0;
-        const parsed = discovery_1.dataXpertDiscoveryRequestSchema.parse(empty ? { kind: 'resources' } : request);
-        const response = await this.request('discover', context, { request: parsed });
-        const result = v3_1.z.object({ items: v3_1.z.array(v3_1.z.unknown()),
-            nextRequest: json.optional() }).strict().parse(await boundedJson(response));
-        return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({ ...result, schemaVersion: 1, queryContract: discovery_1.dataXpertQueryContract });
+    authoringContext(context) {
+        if (context.connection.kind !== 'integration')
+            throw new Error('ANALYTICS_CONNECTION_INVALID');
+        // The host uses the Assistant UUID as x-assistant-code for data-xpert calls.
+        return { actor: context.actor, signal: context.signal, deadlineAt: context.deadlineAt, maxRows: 5,
+            options: { integrationId: context.connection.integrationId, assistantCode: context.xpertId,
+                assistantXpertId: context.xpertId, workspaceId: context.workspaceId } };
     }
-    async request(endpoint, context, body) {
-        context.signal.throwIfAborted();
-        const options = optionsSchema.parse(context.options);
-        const base = new URL(options.baseUrl);
-        if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
-            throw new Error('DATAX_URL_INVALID');
-        const token = await this.runtime.require(plugin_sdk_1.ActorTokenRuntimeFactoryCapability).createScopedApi(context.actor).getToken({ audience: options.audience });
-        context.signal.throwIfAborted();
-        const response = await fetch(`${base.href.replace(/\/$/, '')}/agent-workbench/analytics/${endpoint}`, {
-            method: 'POST', redirect: 'error', signal: context.signal,
-            headers: { Authorization: `Bearer ${token.token}`, 'Content-Type': 'application/json', 'organization-id': context.actor.organizationId },
-            body: JSON.stringify({ assistant: { code: options.assistantCode, xpertId: options.assistantXpertId, workspaceId: options.workspaceId }, ...body })
-        });
-        if (!response.ok) {
-            // Do not retain an unconsumed upstream error stream or expose its potentially sensitive body.
-            await response.body?.cancel().catch(() => undefined);
-            throw new Error(`DATAX_QUERY_HTTP_${response.status}`);
-        }
-        return response;
+    async validateConfiguration(options, actor) {
+        const parsed = optionsSchema.parse(options);
+        await this.connection(parsed.integrationId, actor);
+        return parsed;
     }
-    async execute(binding, parameters, context) {
-        const payload = exports.dataXpertPayloadSchema.parse(binding.payload);
-        const response = await this.request('query', context, {
-            binding: { id: binding.id, resourceId: payload.resourceId, actionTypeCode: payload.actionTypeCode, target: payload.target,
-                params: bindParameters(payload.params, payload.parameterPaths, parameters) }, maxRows: context.maxRows
-        });
-        const result = responseSchema.parse(await boundedJson(response));
-        return { columns: result.effect.columns, rows: result.effect.rows,
-            completeness: { returnedRows: result.effect.summary.returnedRowCount, totalRows: result.effect.summary.rowCount,
-                totalAccuracy: result.effect.summary.truncated ? 'unknown' : 'exact', scope: result.effect.summary.truncated ? 'page' : 'full_query_result',
-                truncated: result.effect.summary.truncated }, sourceFetchedAt: result.fetchedAt,
-            upstreamExecutionId: result.executionId, auditRef: result.auditRef };
+    async connection(id, actor) {
+        const integration = await this.queries.execute(new plugin_sdk_1.ResolveConnectorIntegrationQuery(id, integration_1.DATA_XPERT_INTEGRATION, { tenantId: actor.tenantId, organizationId: actor.organizationId }));
+        if (!integration || integration.tenantId !== actor.tenantId || (integration.organizationId && integration.organizationId !== actor.organizationId))
+            throw new Error('DATAX_INTEGRATION_UNAVAILABLE');
+        return integration_1.connectionSchema.parse(integration.options);
     }
+    async run(context, execute) {
+        const { integrationId, ...target } = optionsSchema.parse(context.options);
+        const connection = await this.connection(integrationId, context.actor);
+        const result = await execute({ ...context, options: { ...target, ...connection } });
+        const current = await this.connection(integrationId, context.actor);
+        if (JSON.stringify(current) !== JSON.stringify(connection))
+            throw new Error('DATAX_INTEGRATION_CHANGED');
+        return result;
+    }
+    discover(request, context) { return this.run(context, resolved => this.engine.discover(request, resolved)); }
+    execute(binding, parameters, context) { return this.run(context, resolved => this.engine.execute(binding, parameters, resolved)); }
 };
 exports.DataXpertAnalyticsProvider = DataXpertAnalyticsProvider;
 exports.DataXpertAnalyticsProvider = DataXpertAnalyticsProvider = __decorate([
     (0, plugin_sdk_1.AnalyticsProvider)('data-xpert.ontology'),
-    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
-    __metadata("design:paramtypes", [Object])
+    __metadata("design:paramtypes", [client_1.DataXpertAnalyticsClient, cqrs_1.QueryBus])
 ], DataXpertAnalyticsProvider);
-/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
-function bindParameters(params, paths, parameters) {
-    const result = structuredClone(params);
-    if (Object.keys(parameters).some((name) => !Object.hasOwn(paths, name)) || Object.keys(paths).some((name) => !Object.hasOwn(parameters, name)))
-        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
-    if (new Set(Object.values(paths).map((path) => JSON.stringify(path))).size !== Object.keys(paths).length)
-        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
-    for (const [name, path] of Object.entries(paths)) {
-        let current = result;
-        for (const [index, key] of path.entries()) {
-            if (['__proto__', 'prototype', 'constructor'].includes(key) || !current || typeof current !== 'object' || !Object.hasOwn(current, key))
-                throw new common_1.BadRequestException('DATAX_PARAMETER_PATH_INVALID: parameterPaths are relative to params. Omit the leading params segment and target an existing scalar, for example ["slicers","1","value"].');
-            if (Array.isArray(current)) {
-                if (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= current.length)
-                    throw new Error('DATAX_PARAMETER_PATH_INVALID');
-                const position = Number(key);
-                if (index === path.length - 1) {
-                    if (current[position] !== null && typeof current[position] === 'object')
-                        throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
-                    current[position] = parameters[name];
-                }
-                else
-                    current = current[position];
-            }
-            else if (index === path.length - 1) {
-                if (current[key] !== null && typeof current[key] === 'object')
-                    throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
-                current[key] = parameters[name];
-            }
-            else
-                current = current[key];
-        }
-    }
-    return result;
-}
-async function boundedJson(response) {
-    if (!response.body)
-        throw new Error('DATAX_EMPTY_RESPONSE');
-    const reader = response.body.getReader();
-    const chunks = [];
-    let size = 0;
-    try {
-        for (;;) {
-            const chunk = await reader.read();
-            if (chunk.done)
-                break;
-            size += chunk.value.byteLength;
-            if (size > 2_500_000)
-                throw new Error('DATAX_RESPONSE_TOO_LARGE');
-            chunks.push(chunk.value);
-        }
-        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-    }
-    finally {
-        await reader.cancel();
-    }
-}

package/dist/lib/result-schema.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod/v3';
+import type { JSONValue } from '@xpert-ai/contracts';
+export declare const dataXpertResultColumnSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    logicalType: z.ZodOptional<z.ZodEnum<["string", "boolean", "int64", "float64", "decimal", "date", "timestamp"]>>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    role: z.ZodOptional<z.ZodEnum<["dimension", "measure", "time", "identifier"]>>;
+    semanticRef: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    unit: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+} & {
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    label?: string | undefined;
+    logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp" | undefined;
+    nullable?: boolean | undefined;
+    role?: "dimension" | "measure" | "time" | "identifier" | undefined;
+    semanticRef?: string | undefined;
+    unit?: string | undefined;
+}, {
+    key: string;
+    label?: string | undefined;
+    logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp" | undefined;
+    nullable?: boolean | undefined;
+    role?: "dimension" | "measure" | "time" | "identifier" | undefined;
+    semanticRef?: string | undefined;
+    unit?: string | undefined;
+}>;
+export declare const dataXpertOutputSchema: z.ZodObject<{
+    datasetId: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sourceField: z.ZodString;
+        label: z.ZodString;
+        logicalType: z.ZodEnum<["string", "boolean", "int64", "float64", "decimal", "date", "timestamp"]>;
+        nullable: z.ZodBoolean;
+        role: z.ZodEnum<["dimension", "measure", "time", "identifier"]>;
+        semanticRef: z.ZodOptional<z.ZodString>;
+        unit: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        id?: string;
+        sourceField?: string;
+        label?: string;
+        logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp";
+        nullable?: boolean;
+        role?: "dimension" | "measure" | "time" | "identifier";
+        semanticRef?: string;
+        unit?: string;
+    }, {
+        id?: string;
+        sourceField?: string;
+        label?: string;
+        logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp";
+        nullable?: boolean;
+        role?: "dimension" | "measure" | "time" | "identifier";
+        semanticRef?: string;
+        unit?: string;
+    }>, "many">;
+    grain: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    datasetId?: string;
+    fields?: {
+        id?: string;
+        sourceField?: string;
+        label?: string;
+        logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp";
+        nullable?: boolean;
+        role?: "dimension" | "measure" | "time" | "identifier";
+        semanticRef?: string;
+        unit?: string;
+    }[];
+    grain?: string[];
+}, {
+    datasetId?: string;
+    fields?: {
+        id?: string;
+        sourceField?: string;
+        label?: string;
+        logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp";
+        nullable?: boolean;
+        role?: "dimension" | "measure" | "time" | "identifier";
+        semanticRef?: string;
+        unit?: string;
+    }[];
+    grain?: string[];
+}>;
+export declare function createDataXpertDatasetId(payload: JSONValue, requestedId?: string): string;
+export declare function createDataXpertOutput(datasetId: string, columns: z.output<typeof dataXpertResultColumnSchema>[]): {
+    datasetId?: string;
+    fields?: {
+        id?: string;
+        sourceField?: string;
+        label?: string;
+        logicalType?: "string" | "boolean" | "date" | "int64" | "float64" | "decimal" | "timestamp";
+        nullable?: boolean;
+        role?: "dimension" | "measure" | "time" | "identifier";
+        semanticRef?: string;
+        unit?: string;
+    }[];
+    grain?: string[];
+};

package/dist/lib/result-schema.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataXpertOutputSchema = exports.dataXpertResultColumnSchema = void 0;
+exports.createDataXpertDatasetId = createDataXpertDatasetId;
+exports.createDataXpertOutput = createDataXpertOutput;
+const node_crypto_1 = require("node:crypto");
+const v3_1 = require("zod/v3");
+const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
+// Optional on legacy responses; schema authoring requires explicit declarations.
+exports.dataXpertResultColumnSchema = analytics_1.analyticsFieldSchema
+    .omit({ id: true, sourceField: true })
+    .partial()
+    .extend({ key: v3_1.z.string() })
+    .strip();
+exports.dataXpertOutputSchema = analytics_1.analyticsBindingObjectSchema.shape.output;
+function createDataXpertDatasetId(payload, requestedId) {
+    const parsed = exports.dataXpertOutputSchema.shape.datasetId.safeParse(requestedId);
+    if (parsed.success)
+        return parsed.data;
+    // Native references are not output keys. Include the query projection to separate bindings.
+    return `dataset_${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(payload)).digest('hex')}`;
+}
+function createDataXpertOutput(datasetId, columns) {
+    if (columns.length === 0 || columns.length > 80)
+        throw new Error('DATAX_RESULT_SCHEMA_UNAVAILABLE: expected 1 to 80 declared columns');
+    if (new Set(columns.map(column => column.key)).size !== columns.length)
+        throw new Error('DATAX_RESULT_SCHEMA_AMBIGUOUS');
+    const fields = columns.map(column => {
+        if (column.logicalType === undefined || column.role === undefined || column.nullable === undefined)
+            throw new Error('DATAX_RESULT_SCHEMA_UNAVAILABLE');
+        // Repeated semantic selectors cannot identify a column; its unique native key can.
+        const semanticRef = columns.filter(item => item.semanticRef === column.semanticRef).length === 1
+            ? column.semanticRef : undefined;
+        return {
+            id: `field_${(0, node_crypto_1.createHash)('sha256').update(column.key).digest('hex')}`,
+            sourceField: column.key, label: column.label ?? column.key.slice(0, 160),
+            logicalType: column.logicalType, role: column.role, nullable: column.nullable,
+            ...(semanticRef === undefined ? {} : { semanticRef }),
+            ...(column.unit === undefined ? {} : { unit: column.unit })
+        };
+    });
+    // Column roles do not establish row uniqueness or business aggregation grain.
+    return exports.dataXpertOutputSchema.parse({ datasetId, fields, grain: [] });
+}

package/docs/index.mdx

@@ -7,8 +7,7 @@ description: "Adapt governed ontology Actions to Xpert Dataset/Binding without c
 
 Xpert owns the shared Dataset/Binding protocol, current actor, source configuration,
 parameter validation, execution budget and Artifact persistence. This system plugin registers
-`data-xpert.ontology`, operation `action`, contract version `1`, and the `data-xpert`
-DataSource type. It converts declared scalar parameters into native Action arguments and
+`data-xpert.ontology`, operation `action`, contract version `1`, a Definition configuration entry and the `analytics-data-xpert` Integration strategy. It converts declared scalar parameters into native Action arguments and
 maps canonical rows, completeness and audit receipts back to the shared Dataset path.
 
 Data-xpert owns published resource discovery, ontology adapter metadata, Action input
@@ -20,8 +19,7 @@ The provider ID is a stable Binding reference; package ownership uses the
 
 ## Server configuration and identity
 
-Configure `baseUrl` (including `/api`), `audience`, `assistantCode`, `assistantXpertId`
-and `workspaceId` on the platform DataSource. The Assistant and workspace must already
+Create a **data-xpert Analytics** Integration with `baseUrl` (including `/api`) and `audience`. In **Settings → Analytics**, publish a Definition with `integrationId`, `assistantCode`, `assistantXpertId` and `workspaceId`. The Integration is resolved in the current tenant/organization before and after each request. The Assistant and workspace must already
 have the intended published resources and viewer policy in data-xpert.
 
 The provider gets a short-lived token through

package/docs/verification.mdx

@@ -5,9 +5,10 @@ description: "Separate transport-contract tests from real SSO and end-to-end das
 
 ## Compatibility
 
-Development dependencies pin published SDK/contracts 3.25.0, which export AnalyticsProvider,
-AnalyticsQueryProvider, ActorTokenRuntimeFactoryCapability and the shared Dataset/Binding
-contracts. The host must provide the corresponding runtime capabilities.
+Development dependencies pin `@xpert-ai/contracts` and `@xpert-ai/plugin-sdk` to 3.32.0.
+Both peer dependencies require `^3.32.0`. The plugin validates upstream error responses with
+`parseAnalyticsDiagnostic` and returns accepted diagnostics through `AnalyticsProviderError`.
+The host must provide the Analytics and Actor Token runtime capabilities.
 
 Data-xpert must expose `POST /agent-workbench/analytics/discover` and
 `POST /agent-workbench/analytics/query` under the configured API base. Discovery returns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-analytics-data-xpert",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Governed data-xpert ontology analytics provider",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -27,21 +27,23 @@
     }
   },
   "peerDependencies": {
-    "@xpert-ai/plugin-sdk": "^3.25.0",
-    "@xpert-ai/contracts": "^3.25.0",
+    "@xpert-ai/plugin-sdk": "^3.32.0",
+    "@xpert-ai/contracts": "^3.32.0",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
-    "zod": "3.25.67"
+    "zod": "3.25.67",
+    "@nestjs/cqrs": "^11.0.3"
   },
   "devDependencies": {
-    "@xpert-ai/plugin-sdk": "3.25.0",
-    "@xpert-ai/contracts": "3.25.0",
+    "@xpert-ai/plugin-sdk": "3.32.0",
+    "@xpert-ai/contracts": "3.32.0",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
     "zod": "3.25.67",
     "typescript": "^5.9.2",
     "@types/node": "^20.19.9",
-    "reflect-metadata": "^0.2.2"
+    "reflect-metadata": "^0.2.2",
+    "@nestjs/cqrs": "^11.0.3"
   },
   "repository": {
     "type": "git",