@xpert-ai/plugin-live-dashboard 0.5.0 → 0.6.0

package/dist/lib/save-requests.js

@@ -0,0 +1,199 @@
+"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.DashboardSaveRequests = exports.waitSaveRequestSchema = exports.saveRequestSchema = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:timers/promises");
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const dashboard_service_1 = require("./dashboard.service");
+const dashboard_schema_1 = require("./dashboard.schema");
+const TTL = 86400, MAX_RUNTIME = 10 * 60_000, WAIT_MS = 20_000;
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+const key = (scope, id) => {
+    if (!scope.tenantId || !scope.organizationId)
+        throw new Error('DASHBOARD_SAVE_REQUEST_DENIED');
+    return `live_dashboard:save:${scope.tenantId}:${scope.organizationId}:${id}`;
+};
+const contextSchema = v3_1.z.object({ tenantId: v3_1.z.string().uuid(), organizationId: v3_1.z.string().uuid(), userId: v3_1.z.string().uuid(),
+    hostType: v3_1.z.enum(['agent', 'project']), hostId: v3_1.z.string().uuid(), projectId: v3_1.z.string().uuid().optional() }).strict();
+const fileSchema = v3_1.z.object({ filePath: v3_1.z.string(), workspacePath: v3_1.z.string(), sha256: v3_1.z.string(), size: v3_1.z.number() }).strict();
+const receiptSchema = v3_1.z.object({ artifactId: v3_1.z.string().uuid(), draftId: v3_1.z.string(), draftRevision: v3_1.z.number(), baseVersionId: v3_1.z.string().nullable(), status: v3_1.z.literal('draft'), title: v3_1.z.string() });
+const sourceFileSchema = v3_1.z.object({ path: v3_1.z.string().max(300), sha256: v3_1.z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+const recordSchema = v3_1.z.object({ requestId: v3_1.z.string().uuid(), jobId: v3_1.z.string(), context: contextSchema, file: fileSchema,
+    manifestId: v3_1.z.string().uuid(), expectedRevision: v3_1.z.number(), state: v3_1.z.enum(['queued', 'running', 'succeeded', 'failed']), stage: v3_1.z.string(), completed: v3_1.z.number(), total: v3_1.z.number(),
+    fingerprint: v3_1.z.string(), createdAt: v3_1.z.number(), deadline: v3_1.z.number(), error: v3_1.z.string().optional(), dashboard: receiptSchema.optional(), sourceFile: sourceFileSchema.optional() }).strict();
+const inputSchema = v3_1.z.object({ manifest: dashboard_schema_1.dashboardSchema, expectedVersionId: v3_1.z.string().uuid().nullable(), expectedRevision: v3_1.z.number().int().nonnegative(),
+    dependencies: artifact_document_1.artifactDocumentDependencyAssets.optional() }).strict();
+exports.saveRequestSchema = v3_1.z.object({ requestId: v3_1.z.string().uuid() }).strict();
+exports.waitSaveRequestSchema = exports.saveRequestSchema.extend({ cursor: v3_1.z.string().min(1).max(100) }).strict();
+function trustedScope(context) {
+    return contextSchema.parse({ tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId,
+        hostType: context.hostType, hostId: context.hostId,
+        ...(context.hostType === 'project' ? { projectId: context.hostId } : context.runtimeScope?.projectId ? { projectId: context.runtimeScope.projectId } : {}) });
+}
+function restoredScope(scope) {
+    return { ...scope, slots: [], ...(scope.projectId ? { runtimeScope: { projectId: scope.projectId, conversationId: null,
+                dataScopeKey: `project:${scope.projectId}`, workspaceFiles: { catalog: 'projects', scopeId: scope.projectId, projectId: scope.projectId } } } : {}) };
+}
+/** Durable save orchestration; domain validation and CAS remain in DashboardService. */
+let DashboardSaveRequests = class DashboardSaveRequests {
+    constructor(service, runtime, queue) {
+        this.service = service;
+        this.runtime = runtime;
+        this.queue = queue;
+    }
+    async submit(context, manifest, expectedVersionId, expectedRevision, idempotencyKey, sourceFile, dependencies) {
+        await this.service.authorizeProject(context, 'write');
+        const scope = trustedScope(context), parsed = inputSchema.parse({ manifest, expectedVersionId, expectedRevision, dependencies });
+        const fingerprint = hash(JSON.stringify({ ...parsed, manifest: { ...parsed.manifest, ...(expectedRevision === 0 ? { id: 'new' } : {}) }, sourceFile }));
+        const previousCount = await this.service.previousBindingCount(context, parsed.manifest);
+        this.service.assertCapacity(parsed.manifest.bindings.length, previousCount);
+        const redis = await this.queue.getRedis(), files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
+        const dedupe = `${key(scope, 'submission')}:${hash(JSON.stringify([scope, idempotencyKey]))}`;
+        const previous = await redis.get(dedupe);
+        if (previous) {
+            if ((await this.read(context, previous)).fingerprint !== fingerprint)
+                throw new Error('DASHBOARD_SAVE_IDEMPOTENCY_CONFLICT');
+            return this.get(context, previous);
+        }
+        const requestId = (0, node_crypto_1.randomUUID)(), buffer = Buffer.from(JSON.stringify(parsed));
+        if (buffer.length > 12_000_000)
+            throw new Error('DASHBOARD_MANIFEST_TOO_LARGE');
+        const stored = await files.uploadBuffer({ tenantId: scope.tenantId, userId: scope.userId, catalog: 'users', buffer,
+            originalName: 'save.json', fileName: 'save.json', folder: `live-dashboard-save/${requestId}`, mimeType: 'application/json' });
+        const record = { requestId, jobId: `dashboard-save-${requestId}`, context: scope,
+            file: { filePath: stored.filePath, workspacePath: stored.workspacePath, sha256: hash(buffer), size: buffer.length },
+            fingerprint, manifestId: manifest.id, expectedRevision, state: 'queued', stage: 'queued', completed: 0, total: manifest.bindings.length, createdAt: Date.now(), deadline: Date.now() + MAX_RUNTIME,
+            ...(sourceFile ? { sourceFile: sourceFileSchema.parse(sourceFile) } : {}) };
+        const winner = await redis.eval("local id=redis.call('GET',KEYS[1]); if id then return id end; redis.call('SET',KEYS[2],ARGV[2],'EX',ARGV[3]); redis.call('SET',KEYS[1],ARGV[1],'EX',ARGV[3]); return ARGV[1]", 2, dedupe, key(scope, requestId), requestId, JSON.stringify(record), TTL);
+        if (winner !== requestId) {
+            await files.deleteFile(this.reference(record));
+            if ((await this.read(context, String(winner))).fingerprint !== fingerprint)
+                throw new Error('DASHBOARD_SAVE_IDEMPOTENCY_CONFLICT');
+            return this.get(context, String(winner));
+        }
+        // Recovery can enqueue the same deterministic job if the process stops at this boundary.
+        await this.enqueue(record);
+        return this.snapshot(record);
+    }
+    reference(record) {
+        return { source: 'platform.workspace.files', tenantId: record.context.tenantId, userId: record.context.userId, catalog: 'users',
+            filePath: record.file.filePath, workspacePath: record.file.workspacePath };
+    }
+    async enqueue(record) {
+        await this.queue.enqueue({ pluginName: dashboard_service_1.PLUGIN_NAME, queueName: 'save-validation', jobName: 'save', payload: { requestId: record.requestId },
+            tenantId: record.context.tenantId, organizationId: record.context.organizationId, userId: record.context.userId,
+            scopeKey: 'system:global', jobId: record.jobId, attempts: 1, removeOnComplete: { age: TTL, count: 1000 }, removeOnFail: { age: TTL, count: 1000 } });
+    }
+    async read(context, requestId) {
+        v3_1.z.string().uuid().parse(requestId);
+        const redis = await this.queue.getRedis(), value = await redis.get(key(context, requestId));
+        if (!value)
+            throw new Error('DASHBOARD_SAVE_REQUEST_UNAVAILABLE');
+        const record = recordSchema.parse(JSON.parse(value));
+        if (JSON.stringify(trustedScope(context)) !== JSON.stringify(record.context))
+            throw new Error('DASHBOARD_SAVE_REQUEST_DENIED');
+        return record;
+    }
+    snapshot(record) {
+        const terminal = record.state === 'succeeded' || record.state === 'failed';
+        const result = { requestId: record.requestId, state: record.state, stage: record.stage, completed: record.completed, total: record.total,
+            terminal, ...(record.dashboard ? { dashboard: record.dashboard, ...(record.sourceFile ? { sourceFile: record.sourceFile } : {}) } : {}),
+            ...(record.error ? { error: record.error } : {}), nextAction: terminal ? 'report_result' : 'wait' };
+        return { ...result, cursor: hash(JSON.stringify(result)) };
+    }
+    async get(context, requestId) {
+        await this.service.authorizeProject(context);
+        let record = await this.read(context, requestId);
+        if (record.state === 'queued' || record.state === 'running') {
+            const job = await this.queue.getJob({ jobId: record.jobId });
+            if (!job && record.deadline > Date.now())
+                await this.enqueue(record);
+            else if (job?.state === 'failed' || !job && record.deadline <= Date.now()) {
+                // A completed domain receipt always wins a racing observation.
+                record = await this.read(context, requestId);
+                if (record.state !== 'succeeded') {
+                    const receipt = await this.service.savedRequestReceipt(context, record.manifestId, record.requestId, record.expectedRevision);
+                    record = receipt ? { ...record, state: 'succeeded', stage: 'saved', completed: record.total, dashboard: receipt }
+                        : { ...record, state: 'failed', error: 'DASHBOARD_SAVE_JOB_FAILED: retrieve the current draft before retrying; no new save receipt was confirmed.' };
+                    await (await this.queue.getRedis()).set(key(record.context, requestId), JSON.stringify(record), 'EX', TTL);
+                    await this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability).deleteFile(this.reference(record)).catch(() => undefined);
+                }
+            }
+        }
+        return this.snapshot(record);
+    }
+    async wait(context, requestId, cursor, signal) {
+        const until = Date.now() + WAIT_MS;
+        let current = await this.get(context, requestId);
+        while (!current.terminal && current.cursor === cursor && Date.now() < until) {
+            await (0, promises_1.setTimeout)(Math.min(2000, until - Date.now()), undefined, { signal });
+            current = this.snapshot(await this.read(context, requestId));
+        }
+        return current.terminal || current.cursor !== cursor ? current : this.get(context, requestId);
+    }
+    async handle(job, identity) {
+        const requestId = v3_1.z.string().uuid().parse(job.data.requestId), redis = await this.queue.getRedis();
+        let record = recordSchema.parse(JSON.parse(await redis.get(key(identity, requestId)) ?? 'null'));
+        if (record.context.tenantId !== identity.tenantId || record.context.organizationId !== identity.organizationId || record.context.userId !== identity.userId)
+            throw new Error('DASHBOARD_SAVE_REQUEST_DENIED');
+        if (record.state === 'succeeded')
+            return;
+        let committed = false, terminalPersisted = false;
+        const persist = async () => { await redis.set(key(record.context, requestId), JSON.stringify(record), 'EX', TTL); };
+        const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
+        try {
+            const file = await files.readBuffer(this.reference(record));
+            if (file.buffer.length !== record.file.size || hash(file.buffer) !== record.file.sha256)
+                throw new Error('DASHBOARD_SAVE_INPUT_CHANGED');
+            const input = inputSchema.parse(JSON.parse(file.buffer.toString('utf8')));
+            const dashboard = await this.service.save(restoredScope(record.context), input.manifest, input.expectedVersionId, input.expectedRevision, input.dependencies, { requestId, progress: async (stage, completed, total) => {
+                    if (Date.now() >= record.deadline)
+                        throw new Error('DASHBOARD_SAVE_DEADLINE');
+                    record = { ...record, state: 'running', stage, completed, total };
+                    await persist();
+                } });
+            committed = true;
+            record = { ...record, state: 'succeeded', stage: 'saved', completed: record.total, dashboard };
+            await persist();
+            terminalPersisted = true;
+        }
+        catch (error) {
+            // Keep frozen input for recovery when the Artifact CAS succeeded but status persistence did not.
+            if (committed)
+                throw new Error('DASHBOARD_SAVE_COMMIT_UNCONFIRMED');
+            // Do not persist native provider messages or private query configuration.
+            const code = error instanceof Error ? error.message.match(/^DASHBOARD_[A-Z_]+/)?.[0] : undefined;
+            record = { ...record, state: 'failed', error: code ?? 'DASHBOARD_SAVE_VALIDATION_FAILED' };
+            await persist();
+            terminalPersisted = true;
+            throw new Error(record.error);
+        }
+        finally {
+            if (terminalPersisted)
+                await files.deleteFile(this.reference(record)).catch(() => undefined);
+        }
+    }
+};
+exports.DashboardSaveRequests = DashboardSaveRequests;
+exports.DashboardSaveRequests = DashboardSaveRequests = __decorate([
+    (0, common_1.Injectable)(),
+    (0, plugin_sdk_1.PluginJobProcessor)({ pluginName: dashboard_service_1.PLUGIN_NAME, queueName: 'save-validation', jobName: 'save', concurrency: 2 }),
+    __param(1, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __param(2, (0, common_1.Inject)(plugin_sdk_1.MANAGED_QUEUE_SERVICE_TOKEN)),
+    __metadata("design:paramtypes", [dashboard_service_1.DashboardService, Object, Object])
+], DashboardSaveRequests);

package/dist/lib/source-executions.d.ts

@@ -169,20 +169,261 @@ export declare const sourceDatasetSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>;
 }, z.ZodTypeAny, "passthrough">>;
 export type SourceDataset = z.infer<typeof sourceDatasetSchema>;
+/** Rendering needs the complete typed contract; inspection deliberately accepts a smaller projection. */
+export declare const renderDatasetSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"xpert.analytics.dataset">;
+    datasetId: z.ZodString;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    provenance: z.ZodObject<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+} & {
+    fields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        sourceField: 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;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }, {
+        id: string;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }>, "many">;
+    grain: z.ZodArray<z.ZodString, "many">;
+    completeness: z.ZodObject<{
+        returnedRows: z.ZodNumber;
+        totalRows: z.ZodOptional<z.ZodNumber>;
+        totalAccuracy: z.ZodEnum<["exact", "estimated", "unknown"]>;
+        scope: z.ZodEnum<["full_query_result", "page", "sample", "top_n"]>;
+        truncated: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }>;
+    freshness: z.ZodObject<{
+        executedAt: z.ZodString;
+        sourceFetchedAt: z.ZodString;
+        dataAsOf: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    schema: z.ZodLiteral<"xpert.analytics.dataset">;
+    datasetId: z.ZodString;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    provenance: z.ZodObject<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+} & {
+    fields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        sourceField: 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;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }, {
+        id: string;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }>, "many">;
+    grain: z.ZodArray<z.ZodString, "many">;
+    completeness: z.ZodObject<{
+        returnedRows: z.ZodNumber;
+        totalRows: z.ZodOptional<z.ZodNumber>;
+        totalAccuracy: z.ZodEnum<["exact", "estimated", "unknown"]>;
+        scope: z.ZodEnum<["full_query_result", "page", "sample", "top_n"]>;
+        truncated: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }>;
+    freshness: z.ZodObject<{
+        executedAt: z.ZodString;
+        sourceFetchedAt: z.ZodString;
+        dataAsOf: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    schema: z.ZodLiteral<"xpert.analytics.dataset">;
+    datasetId: z.ZodString;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    provenance: z.ZodObject<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        executionId: z.ZodString;
+        bindingId: z.ZodString;
+        providerId: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+} & {
+    fields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        sourceField: 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;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }, {
+        id: string;
+        label: string;
+        sourceField: string;
+        logicalType: "string" | "boolean" | "date" | "float64" | "int64" | "decimal" | "timestamp";
+        nullable: boolean;
+        role: "time" | "dimension" | "measure" | "identifier";
+        semanticRef?: string | undefined;
+        unit?: string | undefined;
+    }>, "many">;
+    grain: z.ZodArray<z.ZodString, "many">;
+    completeness: z.ZodObject<{
+        returnedRows: z.ZodNumber;
+        totalRows: z.ZodOptional<z.ZodNumber>;
+        totalAccuracy: z.ZodEnum<["exact", "estimated", "unknown"]>;
+        scope: z.ZodEnum<["full_query_result", "page", "sample", "top_n"]>;
+        truncated: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }, {
+        scope: "page" | "full_query_result" | "sample" | "top_n";
+        truncated: boolean;
+        returnedRows: number;
+        totalAccuracy: "exact" | "unknown" | "estimated";
+        totalRows?: number | undefined;
+    }>;
+    freshness: z.ZodObject<{
+        executedAt: z.ZodString;
+        sourceFetchedAt: z.ZodString;
+        dataAsOf: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }, {
+        sourceFetchedAt: string;
+        executedAt: string;
+        dataAsOf?: string | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">>;
 export interface SourceExecution {
     requestId: string;
-    state: 'running' | 'succeeded' | 'failed';
+    state: 'queued' | 'running' | 'succeeded' | 'failed';
     controls: Record<string, string | number | boolean | null>;
     requestedAt: string;
+    startedAt?: string;
     finishedAt?: string;
     result?: SourceDataset;
     resultControls?: SourceExecution['controls'];
+    previewEvicted?: boolean;
 }
 export type SourceEvent = {
     bindingId: string;
     requestId: string;
 } & ({
-    type: 'start';
+    type: 'queue' | 'start';
     controls: SourceExecution['controls'];
     at: string;
 } | {

package/dist/lib/source-executions.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sourceDatasetSchema = void 0;
+exports.renderDatasetSchema = exports.sourceDatasetSchema = void 0;
 exports.reduceSourceExecutions = reduceSourceExecutions;
 const v3_1 = require("zod/v3");
+const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
 const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number(), v3_1.z.boolean(), v3_1.z.null()]);
 exports.sourceDatasetSchema = v3_1.z.object({
     schema: v3_1.z.literal('xpert.analytics.dataset'), datasetId: v3_1.z.string(),
@@ -11,15 +12,38 @@ exports.sourceDatasetSchema = v3_1.z.object({
     freshness: v3_1.z.object({ sourceFetchedAt: v3_1.z.string(), executedAt: v3_1.z.string().optional(), dataAsOf: v3_1.z.string().optional() }),
     provenance: v3_1.z.object({ executionId: v3_1.z.string(), bindingId: v3_1.z.string(), providerId: v3_1.z.string() }).passthrough()
 }).passthrough();
+/** Rendering needs the complete typed contract; inspection deliberately accepts a smaller projection. */
+exports.renderDatasetSchema = exports.sourceDatasetSchema.extend({
+    fields: v3_1.z.array(analytics_1.analyticsFieldSchema.required({ id: true, sourceField: true, label: true, logicalType: true, nullable: true, role: true })), grain: v3_1.z.array(v3_1.z.string()),
+    completeness: v3_1.z.object({ returnedRows: v3_1.z.number(), totalRows: v3_1.z.number().optional(), totalAccuracy: v3_1.z.enum(['exact', 'estimated', 'unknown']),
+        scope: v3_1.z.enum(['full_query_result', 'page', 'sample', 'top_n']), truncated: v3_1.z.boolean() }),
+    freshness: v3_1.z.object({ executedAt: v3_1.z.string(), sourceFetchedAt: v3_1.z.string(), dataAsOf: v3_1.z.string().optional() })
+});
 function reduceSourceExecutions(state, event) {
     const previous = state[event.bindingId];
-    if (event.type === 'start')
+    if (event.type === 'start' || event.type === 'queue')
         return { ...state, [event.bindingId]: {
-                requestId: event.requestId, state: 'running', controls: event.controls, requestedAt: event.at,
+                requestId: event.requestId, state: event.type === 'queue' ? 'queued' : 'running', controls: event.controls,
+                requestedAt: previous?.requestId === event.requestId ? previous.requestedAt : event.at,
+                ...(event.type === 'start' ? { startedAt: event.at } : {}),
                 result: previous?.result, resultControls: previous?.resultControls
             } };
     if (!previous || previous.requestId !== event.requestId)
         return state;
-    return { ...state, [event.bindingId]: { ...previous, state: event.type === 'success' ? 'succeeded' : 'failed', finishedAt: event.at,
-            ...(event.type === 'success' ? { result: { ...event.result, rows: event.result.rows.slice(0, 50) }, resultControls: previous.controls } : {}) } };
+    const next = { ...state, [event.bindingId]: { ...previous, state: event.type === 'success' ? 'succeeded' : 'failed', finishedAt: event.at,
+            ...(event.type === 'success' ? { result: preview(event.result), resultControls: previous.controls, previewEvicted: false } : {}) } };
+    // Limit inspection snapshots independently of the rendering result budget.
+    const byAge = Object.values(next).filter(item => item.result).sort((a, b) => (a.finishedAt ?? '').localeCompare(b.finishedAt ?? ''));
+    while (new TextEncoder().encode(JSON.stringify(Object.values(next).map(item => item.result ?? null))).byteLength > 2_000_000 && byAge.length) {
+        const oldest = byAge.shift();
+        const id = Object.keys(next).find(id => next[id] === oldest);
+        next[id] = { ...oldest, result: undefined, resultControls: undefined, previewEvicted: true };
+    }
+    return next;
+}
+function preview(result) {
+    const rows = result.rows.slice(0, 50);
+    while (new TextEncoder().encode(JSON.stringify(rows)).byteLength > 64_000)
+        rows.pop();
+    return { ...result, rows };
 }

package/dist/lib/view.provider.d.ts

@@ -1,3 +1,4 @@
+import { DashboardSaveRequests } from './save-requests';
 import { DashboardProjectsService } from './projects.service';
 import type { XpertExtensionViewManifest, XpertResolvedViewHostContext, XpertViewActionRequest, XpertViewQuery, XpertViewFileAccessRequest } from '@xpert-ai/contracts';
 import { type IXpertViewExtensionProvider, type XpertViewFileActionFile } from '@xpert-ai/plugin-sdk';
@@ -12,7 +13,8 @@ export declare class DashboardViewProvider implements IXpertViewExtensionProvide
     private readonly sharing;
     private readonly projects;
     private readonly archives;
-    constructor(service: DashboardService, sharing: DashboardSharingService, projects: DashboardProjectsService, archives: DashboardArchiveService);
+    private readonly saves?;
+    constructor(service: DashboardService, sharing: DashboardSharingService, projects: DashboardProjectsService, archives: DashboardArchiveService, saves?: DashboardSaveRequests | undefined);
     supports(context: XpertResolvedViewHostContext): boolean;
     getViewManifests(context: XpertResolvedViewHostContext, slot: string): XpertExtensionViewManifest[];
     getRemoteComponentEntry(): Promise<{
@@ -71,8 +73,8 @@ export declare class DashboardViewProvider implements IXpertViewExtensionProvide
                         allowedValues?: (string | number | boolean | null)[] | undefined;
                     }[];
                     charts: {
-                        title: string;
                         type: "bar" | "line" | "area" | "pie" | "scatter";
+                        title: string;
                         id: string;
                         datasetId: string;
                         x: string;
@@ -198,6 +200,39 @@ export declare class DashboardViewProvider implements IXpertViewExtensionProvide
         };
     }>;
     executeViewAction(context: XpertResolvedViewHostContext, viewKey: string, action: string, request: XpertViewActionRequest): Promise<{
+        success: boolean;
+        data: {
+            artifactId: string;
+            draftId: string;
+            draftRevision: number;
+            baseVersionId: string | null;
+            status: "draft";
+            title: string;
+        } | {
+            cursor: string;
+            nextAction: string;
+            error?: string | undefined;
+            sourceFile?: {
+                path: string;
+                sha256: string;
+            } | undefined;
+            dashboard?: {
+                status: "draft";
+                title: string;
+                artifactId: string;
+                draftRevision: number;
+                draftId: string;
+                baseVersionId: string | null;
+            } | undefined;
+            requestId: string;
+            state: "failed" | "running" | "succeeded" | "queued";
+            stage: string;
+            completed: number;
+            total: number;
+            terminal: boolean;
+        };
+        refresh: boolean;
+    } | {
         success: boolean;
         data: import("@xpert-ai/contracts").AnalyticsDiscoveryResult;
         refresh: boolean;
@@ -354,8 +389,8 @@ export declare class DashboardViewProvider implements IXpertViewExtensionProvide
                     allowedValues?: (string | number | boolean | null)[] | undefined;
                 }[];
                 charts: {
-                    title: string;
                     type: "bar" | "line" | "area" | "pie" | "scatter";
+                    title: string;
                     id: string;
                     datasetId: string;
                     x: string;