@xpert-ai/plugin-live-dashboard 0.0.0-stage → 0.1.1

package/dist/lib/dashboard.schema.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryBindingSchema = exports.querySchema = exports.saveSchema = exports.controlsSchema = exports.dashboardChangesSchema = exports.dashboardSchema = void 0;
+const v3_1 = require("zod/v3");
+const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const id = v3_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,79}$/);
+exports.dashboardSchema = v3_1.z.object({
+    schema: v3_1.z.literal('xpert.live-dashboard/v1'), id: v3_1.z.string().uuid(), title: v3_1.z.string().min(1).max(160),
+    bindings: v3_1.z.array(analytics_1.analyticsBindingSchema).min(1).max(8),
+    presentation: v3_1.z.object({ type: v3_1.z.literal('html'), html: artifact_document_1.artifactDocumentHtml, dependencies: artifact_document_1.artifactDocumentDependencyLocks.optional() }).strict().optional(),
+    controls: v3_1.z.array(v3_1.z.object({ controlId: id, type: v3_1.z.enum(['string', 'number', 'boolean', 'date']),
+        defaultValue: v3_1.z.union([v3_1.z.string(), v3_1.z.number(), v3_1.z.boolean(), v3_1.z.null()]).optional(),
+        allowedValues: v3_1.z.array(v3_1.z.union([v3_1.z.string(), v3_1.z.number(), v3_1.z.boolean(), v3_1.z.null()])).max(200).optional(),
+        label: v3_1.z.string().min(1).max(160) }).strict()).max(24),
+    charts: v3_1.z.array(v3_1.z.object({ id, title: v3_1.z.string().min(1).max(160), type: v3_1.z.enum(['bar', 'line', 'area', 'pie', 'scatter']),
+        datasetId: id, x: id, y: id, color: id.optional() }).strict()).max(20),
+    tables: v3_1.z.array(v3_1.z.object({ id, title: v3_1.z.string().min(1).max(160), datasetId: id, fields: v3_1.z.array(id).min(1).max(30) }).strict()).max(20)
+}).strict().superRefine((manifest, ctx) => {
+    const unique = (values, name) => {
+        if (new Set(values).size !== values.length)
+            ctx.addIssue({ code: 'custom', message: `Duplicate ${name}` });
+    };
+    unique(manifest.bindings.map((binding) => binding.id), 'binding');
+    unique(manifest.bindings.map((binding) => binding.output.datasetId), 'dataset');
+    unique(manifest.controls.map((control) => control.controlId), 'control');
+    unique([...manifest.charts, ...manifest.tables].map((view) => view.id), 'view');
+    if (!manifest.presentation && !manifest.charts.length && !manifest.tables.length)
+        ctx.addIssue({ code: 'custom', message: 'At least one chart or table is required' });
+    if (manifest.presentation && (manifest.charts.length || manifest.tables.length))
+        ctx.addIssue({ code: 'custom', message: 'HTML presentation owns its charts; use empty charts/tables arrays' });
+    for (const control of manifest.controls) {
+        const parameters = manifest.bindings.flatMap((binding) => binding.parameters.filter((parameter) => parameter.controlId === control.controlId));
+        if (!parameters.length)
+            ctx.addIssue({ code: 'custom', message: 'Control is not bound to a query parameter' });
+        const values = [...(control.defaultValue !== undefined ? [control.defaultValue] : []), ...(control.allowedValues ?? [])];
+        if (values.some((value) => value !== null && (control.type === 'number' ? typeof value !== 'number' || !Number.isFinite(value) :
+            control.type === 'boolean' ? typeof value !== 'boolean' : typeof value !== 'string')))
+            ctx.addIssue({ code: 'custom', message: 'Control value has an incompatible type' });
+        if (control.allowedValues && control.defaultValue !== undefined && !control.allowedValues.includes(control.defaultValue))
+            ctx.addIssue({ code: 'custom', message: 'Default control value is not allowed' });
+        for (const parameter of parameters) {
+            if (parameter.defaultValue !== undefined && control.defaultValue !== undefined && parameter.defaultValue !== control.defaultValue)
+                ctx.addIssue({ code: 'custom', message: 'Control and parameter defaults disagree' });
+            // Match platform resolveAnalyticsParameters: null is governed by required, not the scalar allowlist.
+            if (values.some((value) => value === null ? parameter.required : parameter.allowedValues && !parameter.allowedValues.includes(value)))
+                ctx.addIssue({ code: 'custom', message: 'Control values conflict with parameter restrictions' });
+        }
+    }
+    for (const binding of manifest.bindings)
+        for (const parameter of binding.parameters) {
+            const control = manifest.controls.find((control) => control.controlId === parameter.controlId);
+            if (!control || control.type !== parameter.type)
+                ctx.addIssue({ code: 'custom', message: 'Control mapping is missing or has an incompatible type' });
+        }
+    for (const view of [...manifest.charts, ...manifest.tables]) {
+        const output = manifest.bindings.find((binding) => binding.output.datasetId === view.datasetId)?.output;
+        const fields = 'fields' in view ? view.fields : [view.x, view.y, ...(view.color ? [view.color] : [])];
+        if (!output || fields.some((id) => !output.fields.some((field) => field.id === id)))
+            ctx.addIssue({ code: 'custom', message: 'View references an undeclared Dataset field' });
+        if ('y' in view && !output?.fields.some((field) => field.id === view.y && ['float64', 'int64', 'decimal'].includes(field.logicalType)))
+            ctx.addIssue({ code: 'custom', message: 'Chart measure must be numeric' });
+        if ('y' in view && view.type !== 'scatter' && output?.grain.some((id) => id !== view.x && id !== view.color))
+            ctx.addIssue({ code: 'custom', message: 'Chart must encode every Dataset grain dimension in x/color; use another aggregated binding for totals' });
+    }
+});
+/** Updates never choose identity or source scope; those come from the authorized saved version. */
+exports.dashboardChangesSchema = exports.dashboardSchema.innerType().pick({ title: true, bindings: true,
+    controls: true, charts: true, tables: true, presentation: true }).partial().strict();
+exports.controlsSchema = v3_1.z.record(v3_1.z.union([v3_1.z.string().max(4000), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]));
+exports.saveSchema = v3_1.z.object({ manifest: exports.dashboardSchema, expectedVersionId: v3_1.z.string().uuid().nullable(), expectedRevision: v3_1.z.number().int().nonnegative().default(0) }).strict();
+exports.querySchema = v3_1.z.object({ artifactId: v3_1.z.string().uuid(), versionId: v3_1.z.string().uuid().optional(), draftRevision: v3_1.z.number().int().positive().optional(), controls: exports.controlsSchema.default({}) }).strict();
+/** Generated pages select a saved Binding by ID. Query text, provider and source overrides are rejected. */
+exports.queryBindingSchema = exports.querySchema.extend({ bindingId: id }).strict();

package/dist/lib/dashboard.service.d.ts

@@ -0,0 +1,243 @@
+import type { AnalyticsValue, AnalyticsDiscoveryRequest, AnalyticsQueryRequest, XpertResolvedViewHostContext } from '@xpert-ai/contracts';
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { type DashboardManifest, type DashboardChanges } from './dashboard.schema';
+import { HtmlDashboardValidation } from './html-validation';
+export declare const PLUGIN_NAME = "@xpert-ai/plugin-live-dashboard";
+export declare class DashboardService {
+    private readonly runtime;
+    private readonly htmlValidation;
+    constructor(runtime: RuntimeCapabilityRegistry, htmlValidation: HtmlDashboardValidation);
+    sources(context: XpertResolvedViewHostContext): Promise<import("@xpert-ai/contracts").AnalyticsSourceSummary[]>;
+    discover(context: XpertResolvedViewHostContext, input: AnalyticsDiscoveryRequest): Promise<import("@xpert-ai/contracts").AnalyticsDiscoveryResult>;
+    preview(context: XpertResolvedViewHostContext, input: AnalyticsQueryRequest): Promise<import("@xpert-ai/contracts").AnalyticalDataset>;
+    list(context: XpertResolvedViewHostContext): Promise<{
+        title: string | null | undefined;
+        artifactId: string;
+        versionId: string | null | undefined;
+        versionNumber: number | undefined;
+        updatedAt: string | Date | undefined;
+    }[]>;
+    save(context: XpertResolvedViewHostContext, manifest: DashboardManifest, expectedVersionId: string | null, expectedRevision?: number): Promise<{
+        artifactId: string;
+        draftId: string;
+        draftRevision: number;
+        baseVersionId: string | null;
+        status: "draft";
+        title: string;
+    }>;
+    open(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
+        manifest: {
+            schema: "xpert.live-dashboard/v1";
+            id: string;
+            title: string;
+            bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+            controls: {
+                type: "string" | "number" | "boolean" | "date";
+                controlId: string;
+                label: string;
+                defaultValue?: string | number | boolean | null | undefined;
+                allowedValues?: (string | number | boolean | null)[] | undefined;
+            }[];
+            charts: {
+                type: "bar" | "line" | "area" | "pie" | "scatter";
+                id: string;
+                title: string;
+                datasetId: string;
+                x: string;
+                y: string;
+                color?: string | undefined;
+            }[];
+            tables: {
+                id: string;
+                title: string;
+                datasetId: string;
+                fields: string[];
+            }[];
+            presentation?: {
+                type: "html";
+                html: string;
+                dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+            } | undefined;
+        };
+        draftId?: string | undefined;
+        draftRevision?: number | undefined;
+        baseVersionId?: string | null | undefined;
+        isDraft?: boolean | undefined;
+        title: string | null | undefined;
+        updatedAt: string | Date | undefined;
+        artifactId: string;
+        versionId: string | null | undefined;
+        versionNumber: number | undefined;
+    }>;
+    /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
+    openDocument(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
+        manifest: {
+            schema: "xpert.live-dashboard/v1";
+            id: string;
+            title: string;
+            bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+            controls: {
+                type: "string" | "number" | "boolean" | "date";
+                controlId: string;
+                label: string;
+                defaultValue?: string | number | boolean | null | undefined;
+                allowedValues?: (string | number | boolean | null)[] | undefined;
+            }[];
+            charts: {
+                type: "bar" | "line" | "area" | "pie" | "scatter";
+                id: string;
+                title: string;
+                datasetId: string;
+                x: string;
+                y: string;
+                color?: string | undefined;
+            }[];
+            tables: {
+                id: string;
+                title: string;
+                datasetId: string;
+                fields: string[];
+            }[];
+            presentation?: {
+                type: "html";
+                html: string;
+                dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+            } | undefined;
+        };
+        dependencies: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyAsset[];
+        draftId?: string | undefined;
+        draftRevision?: number | undefined;
+        baseVersionId?: string | null | undefined;
+        isDraft?: boolean | undefined;
+        title: string | null | undefined;
+        updatedAt: string | Date | undefined;
+        artifactId: string;
+        versionId: string | null | undefined;
+        versionNumber: number | undefined;
+    }>;
+    history(context: XpertResolvedViewHostContext, artifactId: string): Promise<{
+        current: boolean;
+        artifactId: string;
+        versionId: string | null | undefined;
+        versionNumber: number | undefined;
+        title: string | null | undefined;
+        updatedAt: string | Date | undefined;
+    }[]>;
+    update(context: XpertResolvedViewHostContext, artifactId: string, expectedRevision: number, changes: DashboardChanges, expectedCurrentVersionId: string | null): Promise<{
+        artifactId: string;
+        draftId: string;
+        draftRevision: number;
+        baseVersionId: string | null;
+        status: "draft";
+        title: string;
+    }>;
+    publish(context: XpertResolvedViewHostContext, artifactId: string, expectedRevision: number, expectedCurrentVersionId: string | null): Promise<{
+        artifactId: string;
+        versionId: string;
+        versionNumber: number;
+        title: string | null | undefined;
+    }>;
+    query(context: XpertResolvedViewHostContext, artifactId: string, versionId: string | undefined, controls: Record<string, AnalyticsValue>, draftRevision?: number): Promise<{
+        payload?: {
+            ok: boolean;
+            widget_type: string;
+            surface: string;
+            sources: never[];
+            manifest: {
+                version: number;
+                surface: string;
+                title: string;
+                cards: never[];
+                filters: never[];
+                sources: never[];
+                charts: {
+                    id: string;
+                    title: string;
+                    type: "bar" | "line" | "area" | "pie" | "scatter";
+                    dataset: string;
+                    encodings: {
+                        color?: {
+                            field: string;
+                        } | undefined;
+                        x: {
+                            field: string;
+                        };
+                        y: {
+                            field: string;
+                        };
+                    };
+                }[];
+                tables: {
+                    id: string;
+                    title: string;
+                    dataset: string;
+                    columns: {
+                        field: string;
+                        label: string;
+                    }[];
+                }[];
+                blocks: ({
+                    id: string;
+                    type: string;
+                    chartId: string;
+                } | {
+                    id: string;
+                    type: string;
+                    tableId: string;
+                })[];
+            };
+            snapshot: {
+                version: number;
+                generatedAt: string;
+                status: string;
+                datasets: any;
+            };
+        } | undefined;
+        datasets: import("@xpert-ai/contracts").AnalyticalDataset[];
+        manifest: {
+            schema: "xpert.live-dashboard/v1";
+            id: string;
+            title: string;
+            bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+            controls: {
+                type: "string" | "number" | "boolean" | "date";
+                controlId: string;
+                label: string;
+                defaultValue?: string | number | boolean | null | undefined;
+                allowedValues?: (string | number | boolean | null)[] | undefined;
+            }[];
+            charts: {
+                type: "bar" | "line" | "area" | "pie" | "scatter";
+                id: string;
+                title: string;
+                datasetId: string;
+                x: string;
+                y: string;
+                color?: string | undefined;
+            }[];
+            tables: {
+                id: string;
+                title: string;
+                datasetId: string;
+                fields: string[];
+            }[];
+            presentation?: {
+                type: "html";
+                html: string;
+                dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+            } | undefined;
+        };
+        draftId?: string | undefined;
+        draftRevision?: number | undefined;
+        baseVersionId?: string | null | undefined;
+        isDraft?: boolean | undefined;
+        title: string | null | undefined;
+        updatedAt: string | Date | undefined;
+        artifactId: string;
+        versionId: string | null | undefined;
+        versionNumber: number | undefined;
+    }>;
+    queryBinding(context: XpertResolvedViewHostContext, artifactId: string, versionId: string | undefined, bindingId: string, input: Record<string, AnalyticsValue>, draftRevision?: number): Promise<import("@xpert-ai/contracts").AnalyticalDataset>;
+    private execute;
+    private probeControls;
+}

package/dist/lib/dashboard.service.js

@@ -0,0 +1,185 @@
+"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.DashboardService = exports.PLUGIN_NAME = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const dashboard_schema_1 = require("./dashboard.schema");
+const renderer_1 = require("./renderer");
+const dashboard_queries_1 = require("./dashboard-queries");
+const html_validation_1 = require("./html-validation");
+const document_libraries_1 = require("./document-libraries");
+const document_package_1 = require("./document-package");
+exports.PLUGIN_NAME = '@xpert-ai/plugin-live-dashboard';
+const RESOURCE_TYPE = 'live-dashboard';
+const MIME_TYPE = 'application/json';
+let DashboardService = class DashboardService {
+    constructor(runtime, htmlValidation) {
+        this.runtime = runtime;
+        this.htmlValidation = htmlValidation;
+    }
+    sources(context) { return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).list(actor(context)); }
+    discover(context, input) { return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).discover(actor(context), input); }
+    async preview(context, input) {
+        const dataset = await this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).query(actor(context), input);
+        await this.probeControls(context, input.binding, input.controls ?? {});
+        return dataset;
+    }
+    async list(context) {
+        actor(context);
+        const result = await this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability).listArtifacts({ pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceIdPrefix: hostPrefix(context), status: 'active', pageSize: 100, includeCurrentVersion: true });
+        const items = result.items.filter((item) => item.resourceId.startsWith(hostPrefix(context)) && item.userId === context.userId);
+        const drafts = new Map((await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).list(items.map(item => item.id))).map(draft => [draft.artifactId, draft]));
+        return items.map(item => ({ ...summary(item), ...(drafts.has(item.id) ? { title: drafts.get(item.id).title ?? item.title } : {}) }));
+    }
+    async save(context, manifest, expectedVersionId, expectedRevision = 0) {
+        const scopedActor = actor(context);
+        const parsed = dashboard_schema_1.dashboardSchema.parse(manifest);
+        const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
+        const source = { pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceId: `${hostPrefix(context)}${parsed.id}` };
+        const existing = await artifacts.findArtifactBySource(source);
+        if (existing && existing.userId !== scopedActor.userId)
+            throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
+        // A failed first upload can leave an Artifact with no saved content; revision 0 initializes it.
+        const previous = existing && (existing.currentVersionId || expectedRevision > 0) ? await this.openDocument(context, existing.id) : null;
+        const dependencies = await (0, document_libraries_1.resolveLibraryAssets)(parsed.presentation?.dependencies ?? [], previous?.dependencies);
+        const buffer = (0, document_package_1.encodeDashboardPackage)(parsed, dependencies);
+        if (buffer.byteLength > document_package_1.MAX_DASHBOARD_PACKAGE_BYTES)
+            throw new common_1.BadRequestException('DASHBOARD_MANIFEST_TOO_LARGE');
+        const digest = (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
+        if ((existing?.currentVersionId ?? null) !== expectedVersionId)
+            throw new common_1.ConflictException('DASHBOARD_VERSION_CONFLICT');
+        // Recheck current data access even for an idempotent retry; the platform enforces the final CAS under a row lock.
+        const preview = await this.execute(context, parsed, Object.fromEntries(parsed.controls.filter((control) => control.defaultValue !== undefined).map((control) => [control.controlId, control.defaultValue ?? null])));
+        if (!parsed.presentation)
+            (0, renderer_1.toDataAnalyticsPayload)(parsed, preview);
+        for (const binding of parsed.bindings)
+            await this.probeControls(context, binding, Object.fromEntries(parsed.controls.filter((control) => control.defaultValue !== undefined).map((control) => [control.controlId, control.defaultValue ?? null])));
+        const htmlValidation = await this.htmlValidation.validate(context, parsed, preview, dependencies);
+        const artifact = existing ?? await artifacts.createArtifact({ source, kind: 'file', title: parsed.title,
+            scope: { ...scopedActor, ...(context.hostType === 'project' ? { projectId: context.hostId } : { xpertId: context.hostId }) } });
+        const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
+        const scope = { tenantId: scopedActor.tenantId, userId: scopedActor.userId, catalog: 'users' };
+        const file = await files.uploadBuffer({ ...scope, buffer, originalName: 'dashboard.json', fileName: `${digest}.json`, folder: `live-dashboards/${parsed.id}`, mimeType: MIME_TYPE });
+        const result = await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).save({ artifactId: artifact.id, expectedRevision,
+            expectedCurrentVersionId: expectedVersionId, mimeType: MIME_TYPE, title: parsed.title, fileName: 'dashboard.json', sha256: digest,
+            ...(htmlValidation ? { metadata: { htmlValidation } } : {}),
+            workspaceFileRef: { source: 'platform.workspace.files', ...scope, filePath: file.filePath, workspacePath: file.workspacePath } });
+        return { artifactId: artifact.id, draftId: result.id, draftRevision: result.revision, baseVersionId: result.baseVersionId, status: 'draft', title: parsed.title };
+    }
+    async open(context, artifactId, versionId, draftRevision) {
+        const { dependencies, ...saved } = await this.openDocument(context, artifactId, versionId, draftRevision);
+        return saved;
+    }
+    /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
+    async openDocument(context, artifactId, versionId, draftRevision) {
+        actor(context);
+        const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
+        const artifact = await artifacts.getArtifact(artifactId);
+        assertOwned(context, artifact);
+        const draft = !versionId || draftRevision !== undefined ? await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).get(artifactId) : null;
+        if (draftRevision !== undefined && draft?.revision !== draftRevision)
+            throw new common_1.ConflictException('DASHBOARD_DRAFT_CONFLICT');
+        const version = draft ?? (versionId ? (await artifacts.listArtifactVersions({ artifactId, status: 'active' })).find((item) => item.id === versionId) : artifact.currentVersion);
+        if (!version?.workspaceFileRef || version.mimeType !== MIME_TYPE)
+            throw new common_1.BadRequestException('DASHBOARD_VERSION_UNAVAILABLE');
+        const file = await this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability).readBuffer(version.workspaceFileRef);
+        if (file.buffer.byteLength > document_package_1.MAX_DASHBOARD_PACKAGE_BYTES)
+            throw new common_1.BadRequestException('DASHBOARD_MANIFEST_TOO_LARGE');
+        if (!version.sha256 || (0, node_crypto_1.createHash)('sha256').update(file.buffer).digest('hex') !== version.sha256)
+            throw new common_1.BadRequestException('DASHBOARD_VERSION_CONTENT_CHANGED');
+        const { manifest, dependencies } = (0, document_package_1.decodeDashboardPackage)(file.buffer);
+        if (artifact.resourceId !== `${hostPrefix(context)}${manifest.id}`)
+            throw new common_1.BadRequestException('DASHBOARD_IDENTITY_MISMATCH');
+        return { ...summary(artifact, 'versionNumber' in version ? version : undefined),
+            ...(draft ? { draftId: draft.id, draftRevision: draft.revision, baseVersionId: draft.baseVersionId,
+                isDraft: draft.revision !== draft.publishedRevision, title: draft.title, updatedAt: draft.updatedAt } : {}), manifest, dependencies };
+    }
+    async history(context, artifactId) {
+        actor(context);
+        const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
+        const artifact = await artifacts.getArtifact(artifactId);
+        assertOwned(context, artifact);
+        const versions = await artifacts.listArtifactVersions({ artifactId, status: 'active' });
+        return versions.map(version => ({ ...summary(artifact, version), current: version.id === artifact.currentVersionId }))
+            .sort((a, b) => (b.versionNumber ?? 0) - (a.versionNumber ?? 0));
+    }
+    async update(context, artifactId, expectedRevision, changes, expectedCurrentVersionId) {
+        const saved = await this.open(context, artifactId);
+        if ((saved.draftRevision ?? 0) !== expectedRevision || (saved.baseVersionId ?? saved.versionId ?? null) !== expectedCurrentVersionId)
+            throw new common_1.ConflictException('DASHBOARD_DRAFT_CONFLICT');
+        return this.save(context, dashboard_schema_1.dashboardSchema.parse({ ...saved.manifest, ...dashboard_schema_1.dashboardChangesSchema.parse(changes) }), saved.baseVersionId ?? saved.versionId ?? null, expectedRevision);
+    }
+    async publish(context, artifactId, expectedRevision, expectedCurrentVersionId) {
+        const saved = await this.open(context, artifactId, undefined, expectedRevision);
+        // Revalidate current source access and bindings before publishing the exact reviewed bytes.
+        await this.execute(context, saved.manifest, {});
+        const version = await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).publish({ artifactId, expectedRevision, expectedCurrentVersionId });
+        return { artifactId, versionId: version.id, versionNumber: version.versionNumber, title: version.title };
+    }
+    async query(context, artifactId, versionId, controls, draftRevision) {
+        const saved = await this.open(context, artifactId, versionId, draftRevision);
+        const datasets = await this.execute(context, saved.manifest, controls);
+        return { ...saved, datasets, ...(saved.manifest.presentation ? {} : { payload: (0, renderer_1.toDataAnalyticsPayload)(saved.manifest, datasets) }) };
+    }
+    async queryBinding(context, artifactId, versionId, bindingId, input, draftRevision) {
+        const saved = await this.open(context, artifactId, versionId, draftRevision);
+        return (0, dashboard_queries_1.queryDashboardBinding)(this.runtime, actor(context), saved.manifest, bindingId, input);
+    }
+    execute(context, manifest, input) {
+        return (0, dashboard_queries_1.queryDashboard)(this.runtime, actor(context), manifest, input);
+    }
+    async probeControls(context, binding, input) {
+        const controls = Object.fromEntries(binding.parameters.map((parameter) => [parameter.controlId,
+            Object.hasOwn(input, parameter.controlId) ? input[parameter.controlId] : parameter.defaultValue ?? null]));
+        // A null default can bypass a native predicate entirely. Verify a real selection too,
+        // using declared values only; never invent a business filter for open-ended controls.
+        for (const parameter of binding.parameters) {
+            const current = controls[parameter.controlId];
+            const alternative = parameter.allowedValues?.find((value) => value !== null && value !== current);
+            const samples = [...(alternative !== undefined ? [alternative] : []),
+                ...(current !== null && parameter.allowedValues?.includes(null) ? [null] : [])];
+            for (const value of samples) {
+                try {
+                    await this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).query(actor(context), { binding, controls: { ...controls, [parameter.controlId]: value } });
+                }
+                catch {
+                    throw new common_1.BadRequestException(`DASHBOARD_FILTER_PREVIEW_FAILED: ${parameter.controlId}; a declared non-default filter failed. Inspect the native parameter type and operator before retrying.`);
+                }
+            }
+        }
+    }
+};
+exports.DashboardService = DashboardService;
+exports.DashboardService = DashboardService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [Object, html_validation_1.HtmlDashboardValidation])
+], DashboardService);
+function actor(context) {
+    if (!context.tenantId || !context.organizationId || !context.userId || !['agent', 'project'].includes(context.hostType))
+        throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
+    return { tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId };
+}
+function hostPrefix(context) { return `${context.hostType}/${context.hostId}/`; }
+function assertOwned(context, artifact) {
+    if (artifact.pluginName !== exports.PLUGIN_NAME || artifact.resourceType !== RESOURCE_TYPE || !artifact.resourceId.startsWith(hostPrefix(context)) ||
+        artifact.tenantId !== context.tenantId || artifact.organizationId !== context.organizationId || artifact.userId !== context.userId)
+        throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
+}
+function summary(artifact, version = artifact.currentVersion) {
+    return { artifactId: artifact.id, versionId: version?.id ?? artifact.currentVersionId, versionNumber: version?.versionNumber,
+        title: version?.title ?? artifact.title, updatedAt: artifact.updatedAt };
+}

package/dist/lib/document-libraries.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod/v3';
+import { type ArtifactDocumentDependencyAsset, type ArtifactDocumentDependencyLock } from '@xpert-ai/plugin-sdk/artifact-document';
+/** The plugin owns its catalog. The platform owns verification and isolated execution. */
+export declare const libraryRequestsSchema: z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three"]>, "many">, ("echarts" | "three")[], ("echarts" | "three")[]>;
+export type LibraryRequests = z.output<typeof libraryRequestsSchema>;
+export declare function bundledLibraries(): Promise<ArtifactDocumentDependencyAsset[]>;
+export declare function libraryLocks(ids: LibraryRequests): Promise<ArtifactDocumentDependencyLock[]>;
+export declare function resolveLibraryAssets(locks: ArtifactDocumentDependencyLock[], previous?: ArtifactDocumentDependencyAsset[], loadCatalog?: typeof bundledLibraries): Promise<ArtifactDocumentDependencyAsset[]>;

package/dist/lib/document-libraries.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.libraryRequestsSchema = void 0;
+exports.bundledLibraries = bundledLibraries;
+exports.libraryLocks = libraryLocks;
+exports.resolveLibraryAssets = resolveLibraryAssets;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const v3_1 = require("zod/v3");
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+/** The plugin owns its catalog. The platform owns verification and isolated execution. */
+exports.libraryRequestsSchema = v3_1.z.array(v3_1.z.enum(['echarts', 'three'])).max(2)
+    .refine(ids => new Set(ids).size === ids.length, 'Duplicate library');
+async function bundledLibraries() {
+    return (0, artifact_document_1.verifyArtifactDocumentDependencies)(JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(__dirname, '../libraries/catalog.json'), 'utf8')));
+}
+async function libraryLocks(ids) {
+    const catalog = await bundledLibraries();
+    return exports.libraryRequestsSchema.parse(ids).map(id => {
+        const asset = catalog.find(item => item.id === id);
+        if (!asset)
+            throw new Error('DASHBOARD_LIBRARY_UNAVAILABLE');
+        const { source, ...lock } = asset;
+        return lock;
+    });
+}
+async function resolveLibraryAssets(locks, previous = [], loadCatalog = bundledLibraries) {
+    const requested = artifact_document_1.artifactDocumentDependencyLocks.parse(locks);
+    if (!requested.length)
+        return [];
+    const hasPrevious = (lock) => previous.some(item => item.id === lock.id && item.version === lock.version && item.sha256 === lock.sha256 && item.global === lock.global && item.format === lock.format);
+    const catalog = requested.every(hasPrevious) ? [] : await loadCatalog();
+    const assets = requested.map(lock => {
+        // Authorized prior bytes take precedence, including after a plugin/library upgrade.
+        const asset = [...previous, ...catalog].find(item => item.id === lock.id && item.version === lock.version && item.sha256 === lock.sha256 && item.global === lock.global && item.format === lock.format);
+        if (!asset)
+            throw new Error(`DASHBOARD_LIBRARY_LOCK_UNAVAILABLE: ${lock.id}@${lock.version}`);
+        return asset;
+    });
+    return (0, artifact_document_1.verifyArtifactDocumentDependencies)(assets, requested);
+}

package/dist/lib/document-package.d.ts

@@ -0,0 +1,41 @@
+import { type ArtifactDocumentDependencyAsset } from '@xpert-ai/plugin-sdk/artifact-document';
+import { type DashboardManifest } from './dashboard.schema';
+export declare const MAX_DASHBOARD_PACKAGE_BYTES = 9000000;
+/** Definition and exact library bytes share one immutable Artifact Version and content checksum. */
+export declare function encodeDashboardPackage(manifest: DashboardManifest, dependencies: ArtifactDocumentDependencyAsset[]): Buffer<ArrayBuffer>;
+export declare function decodeDashboardPackage(bytes: Buffer): {
+    manifest: {
+        schema: "xpert.live-dashboard/v1";
+        id: string;
+        title: string;
+        bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+        controls: {
+            type: "string" | "number" | "boolean" | "date";
+            controlId: string;
+            label: string;
+            defaultValue?: string | number | boolean | null | undefined;
+            allowedValues?: (string | number | boolean | null)[] | undefined;
+        }[];
+        charts: {
+            type: "bar" | "line" | "area" | "pie" | "scatter";
+            id: string;
+            title: string;
+            datasetId: string;
+            x: string;
+            y: string;
+            color?: string | undefined;
+        }[];
+        tables: {
+            id: string;
+            title: string;
+            datasetId: string;
+            fields: string[];
+        }[];
+        presentation?: {
+            type: "html";
+            html: string;
+            dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+        } | undefined;
+    };
+    dependencies: ArtifactDocumentDependencyAsset[];
+};

package/dist/lib/document-package.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DASHBOARD_PACKAGE_BYTES = void 0;
+exports.encodeDashboardPackage = encodeDashboardPackage;
+exports.decodeDashboardPackage = decodeDashboardPackage;
+const v3_1 = require("zod/v3");
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const dashboard_schema_1 = require("./dashboard.schema");
+exports.MAX_DASHBOARD_PACKAGE_BYTES = 9_000_000;
+const storedSchema = v3_1.z.union([
+    v3_1.z.object({ schema: v3_1.z.literal('xpert.live-dashboard.package/v1'), manifest: dashboard_schema_1.dashboardSchema, dependencies: artifact_document_1.artifactDocumentDependencyAssets }).strict(),
+    dashboard_schema_1.dashboardSchema.transform(manifest => ({ manifest, dependencies: [] }))
+]);
+/** Definition and exact library bytes share one immutable Artifact Version and content checksum. */
+function encodeDashboardPackage(manifest, dependencies) {
+    (0, artifact_document_1.verifyArtifactDocumentDependencies)(dependencies, manifest.presentation?.dependencies ?? []);
+    return Buffer.from(JSON.stringify(dependencies.length ? { schema: 'xpert.live-dashboard.package/v1', manifest, dependencies } : manifest));
+}
+function decodeDashboardPackage(bytes) {
+    if (bytes.byteLength > exports.MAX_DASHBOARD_PACKAGE_BYTES)
+        throw new Error('DASHBOARD_PACKAGE_TOO_LARGE');
+    const stored = storedSchema.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+    const dependencies = (0, artifact_document_1.verifyArtifactDocumentDependencies)(stored.dependencies, stored.manifest.presentation?.dependencies ?? []);
+    return { manifest: stored.manifest, dependencies };
+}