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

package/README.md

@@ -18,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/lib/client.d.ts

@@ -1,61 +1,14 @@
-import { z } from 'zod/v3';
 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'>;
-/** 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;
-}>;
 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

@@ -17,19 +17,18 @@ 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)]));
-/** 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({})
+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({
@@ -38,7 +37,7 @@ const optionsSchema = v3_1.z.object({
 }).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() })),
+        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)
@@ -48,6 +47,19 @@ let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
         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 });
@@ -69,25 +81,28 @@ let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
             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}`);
+            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 = 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));
+        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([
@@ -99,21 +114,21 @@ exports.DataXpertAnalyticsClient = DataXpertAnalyticsClient = __decorate([
 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');
+        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 new Error('DATAX_PARAMETER_MAPPING_INVALID');
+        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 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"].');
+                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 new Error('DATAX_PARAMETER_PATH_INVALID');
+                    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 new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                        throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_NOT_SCALAR');
                     current[position] = parameters[name];
                 }
                 else
@@ -121,7 +136,7 @@ function bindParameters(params, paths, parameters) {
             }
             else if (index === path.length - 1) {
                 if (current[key] !== null && typeof current[key] === 'object')
-                    throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                    throw (0, diagnostic_1.dataXpertParameterError)('DATAX_PARAMETER_PATH_NOT_SCALAR');
                 current[key] = parameters[name];
             }
             else

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/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/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/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.26.1, 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.2",
+  "version": "0.2.0",
   "description": "Governed data-xpert ontology analytics provider",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -27,16 +27,16 @@
     }
   },
   "peerDependencies": {
-    "@xpert-ai/plugin-sdk": "^3.26.1",
-    "@xpert-ai/contracts": "^3.26.1",
+    "@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",
     "@nestjs/cqrs": "^11.0.3"
   },
   "devDependencies": {
-    "@xpert-ai/plugin-sdk": "3.26.1",
-    "@xpert-ai/contracts": "3.26.1",
+    "@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",