@owox/backend 0.35.0 → 0.37.0

package/dist/src/ee/mcp/tools/create-report-run-schedule.tool.js

@@ -14,19 +14,19 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateReportRunScheduleTool = void 0;
 const common_1 = require("@nestjs/common");
-const zod_1 = require("zod");
+const zod_v4_1 = require("zod-v4");
 const public_origin_service_1 = require("../../../common/config/public-origin.service");
 const mcp_scheduled_triggers_facade_1 = require("../../../data-marts/facades/mcp-scheduled-triggers.facade");
 const mcp_tool_definition_1 = require("./mcp-tool.definition");
 const data_mart_ui_path_1 = require("./data-mart-ui-path");
 const mcp_public_url_util_1 = require("./mcp-public-url.util");
 const DEFAULT_TIME_ZONE = 'UTC';
-const inputSchema = zod_1.z
+const inputSchema = zod_v4_1.z
     .object({
-    report_id: zod_1.z.string().trim().min(1),
-    cron_expression: zod_1.z.string().trim().min(1),
-    time_zone: zod_1.z.string().trim().min(1).optional(),
-    is_active: zod_1.z.boolean().optional(),
+    report_id: zod_v4_1.z.string().trim().min(1),
+    cron_expression: zod_v4_1.z.string().trim().min(1),
+    time_zone: zod_v4_1.z.string().trim().min(1).optional(),
+    is_active: zod_v4_1.z.boolean().optional(),
 })
     .strict();
 let CreateReportRunScheduleTool = class CreateReportRunScheduleTool {
@@ -36,19 +36,19 @@ let CreateReportRunScheduleTool = class CreateReportRunScheduleTool {
     description = 'Creates a new recurring run schedule for a report. Translate the user\'s natural-language schedule ("every Monday at 9am", "daily at midnight") into a standard 5-field cron expression before calling (e.g. "0 9 * * 1"). This creates an additional schedule and does not replace, delete, or update existing schedules for the same report. To change an existing schedule, first call list_report_run_schedules and then call update_report_run_schedule with the specific trigger_id. time_zone must be a valid IANA timezone (e.g. "Europe/Kyiv"); if the user does not specify one, default to UTC and confirm with them. is_active defaults to true.';
     zodSchema = inputSchema.shape;
     outputSchema = {
-        trigger_id: zod_1.z.string(),
-        report_id: zod_1.z.string(),
-        schedules_url: zod_1.z.string().describe('Open report schedules in OWOX.'),
-        cron_expression: zod_1.z.string(),
-        time_zone: zod_1.z.string(),
-        is_active: zod_1.z.boolean(),
-        next_run_at: zod_1.z.string().nullable(),
+        trigger_id: zod_v4_1.z.string(),
+        report_id: zod_v4_1.z.string(),
+        schedules_url: zod_v4_1.z.string().describe('Open report schedules in OWOX.'),
+        cron_expression: zod_v4_1.z.string(),
+        time_zone: zod_v4_1.z.string(),
+        is_active: zod_v4_1.z.boolean(),
+        next_run_at: zod_v4_1.z.string().nullable(),
     };
     annotations = {
         title: 'Create Report Run Schedule',
         readOnlyHint: false,
         destructiveHint: false,
-        openWorldHint: false,
+        openWorldHint: true,
     };
     requiredScopes = ['mcp:read', 'mcp:write'];
     constructor(facade, publicOriginService) {

package/dist/src/ee/mcp/tools/data-mart-catalog.tool.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod-v4';
 import type { McpScope } from '@owox/idp-protocol';
 import { PublicOriginService } from '../../../common/config/public-origin.service';
 import { type McpProjectContextFacade } from '../../../idp/facades/mcp-project-context.facade';
@@ -6,12 +6,11 @@ import { type McpDataMartsFacade } from '../../../data-marts/facades/mcp-data-ma
 import type { McpAuthContext } from '../auth/mcp-auth-context';
 import { type McpToolDefinition, type McpToolResult } from './mcp-tool.definition';
 declare const inputSchema: z.ZodObject<{
-    status: z.ZodOptional<z.ZodEnum<["published", "draft"]>>;
-}, "strict", z.ZodTypeAny, {
-    status?: "published" | "draft" | undefined;
-}, {
-    status?: "published" | "draft" | undefined;
-}>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>>;
+}, z.core.$strict>;
 type ListDataMartsInput = z.infer<typeof inputSchema>;
 export declare class ListDataMartsTool implements McpToolDefinition<ListDataMartsInput> {
     private readonly dataMarts;
@@ -20,19 +19,16 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
     readonly name = "list_data_marts";
     readonly description = "List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog.";
     readonly zodSchema: {
-        status: z.ZodOptional<z.ZodEnum<["published", "draft"]>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            draft: "draft";
+            published: "published";
+        }>>;
     };
     readonly outputSchema: {
         project: z.ZodOptional<z.ZodObject<{
             id: z.ZodString;
             title: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            id: string;
-            title: string;
-        }, {
-            id: string;
-            title: string;
-        }>>;
+        }, z.core.$strip>>;
         data_marts: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             title: z.ZodString;
@@ -40,21 +36,7 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
             url: z.ZodString;
             status: z.ZodString;
             updated_at: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            id: string;
-            title: string;
-            status: string;
-            description: string;
-            url: string;
-            updated_at: string;
-        }, {
-            id: string;
-            title: string;
-            status: string;
-            description: string;
-            url: string;
-            updated_at: string;
-        }>, "many">;
+        }, z.core.$strip>>;
         getting_started: z.ZodOptional<z.ZodObject<{
             reason: z.ZodLiteral<"no_published_data_marts">;
             can_create_data_marts: z.ZodBoolean;
@@ -64,62 +46,14 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
                 core_concepts: z.ZodString;
                 connector_data_mart: z.ZodString;
                 sql_data_mart: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
-                core_concepts: string;
-                connector_data_mart: string;
-                sql_data_mart: string;
-            }, {
-                core_concepts: string;
-                connector_data_mart: string;
-                sql_data_mart: string;
-            }>;
+            }, z.core.$strip>;
             draft_data_marts: z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 title: z.ZodString;
                 url: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
-                id: string;
-                title: string;
-                url: string;
-            }, {
-                id: string;
-                title: string;
-                url: string;
-            }>, "many">;
+            }, z.core.$strip>>;
             instructions: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            reason: "no_published_data_marts";
-            instructions: string;
-            can_create_data_marts: boolean;
-            create_data_mart_url: string;
-            data_marts_url: string;
-            guides: {
-                core_concepts: string;
-                connector_data_mart: string;
-                sql_data_mart: string;
-            };
-            draft_data_marts: {
-                id: string;
-                title: string;
-                url: string;
-            }[];
-        }, {
-            reason: "no_published_data_marts";
-            instructions: string;
-            can_create_data_marts: boolean;
-            create_data_mart_url: string;
-            data_marts_url: string;
-            guides: {
-                core_concepts: string;
-                connector_data_mart: string;
-                sql_data_mart: string;
-            };
-            draft_data_marts: {
-                id: string;
-                title: string;
-                url: string;
-            }[];
-        }>>;
+        }, z.core.$strip>>;
     };
     readonly annotations: {
         title: string;

package/dist/src/ee/mcp/tools/data-mart-catalog.tool.js

@@ -14,7 +14,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ListDataMartsTool = void 0;
 const common_1 = require("@nestjs/common");
-const zod_1 = require("zod");
+const zod_v4_1 = require("zod-v4");
 const public_origin_service_1 = require("../../../common/config/public-origin.service");
 const mcp_project_context_facade_1 = require("../../../idp/facades/mcp-project-context.facade");
 const mcp_data_marts_facade_1 = require("../../../data-marts/facades/mcp-data-marts.facade");
@@ -23,9 +23,9 @@ const data_mart_ui_path_1 = require("./data-mart-ui-path");
 const mcp_getting_started_util_1 = require("./mcp-getting-started.util");
 const mcp_project_summary_util_1 = require("./mcp-project-summary.util");
 const mcp_public_url_util_1 = require("./mcp-public-url.util");
-const inputSchema = zod_1.z
+const inputSchema = zod_v4_1.z
     .object({
-    status: zod_1.z
+    status: zod_v4_1.z
         .enum(['published', 'draft'])
         .optional()
         .describe('Catalog state filter. Defaults to published. Draft returns draft metadata only; only published Data Marts can be inspected or queried through MCP.'),
@@ -39,14 +39,14 @@ let ListDataMartsTool = class ListDataMartsTool {
     description = 'List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog.';
     zodSchema = inputSchema.shape;
     outputSchema = {
-        project: zod_1.z.object({ id: zod_1.z.string(), title: zod_1.z.string() }).optional(),
-        data_marts: zod_1.z.array(zod_1.z.object({
-            id: zod_1.z.string(),
-            title: zod_1.z.string(),
-            description: zod_1.z.string(),
-            url: zod_1.z.string(),
-            status: zod_1.z.string(),
-            updated_at: zod_1.z.string(),
+        project: zod_v4_1.z.object({ id: zod_v4_1.z.string(), title: zod_v4_1.z.string() }).optional(),
+        data_marts: zod_v4_1.z.array(zod_v4_1.z.object({
+            id: zod_v4_1.z.string(),
+            title: zod_v4_1.z.string(),
+            description: zod_v4_1.z.string(),
+            url: zod_v4_1.z.string(),
+            status: zod_v4_1.z.string(),
+            updated_at: zod_v4_1.z.string(),
         })),
         getting_started: mcp_getting_started_util_1.gettingStartedSchema
             .optional()

package/dist/src/ee/mcp/tools/data-mart-details.tool.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod-v4';
 import type { McpScope } from '@owox/idp-protocol';
 import { type McpDataMartsFacade } from '../../../data-marts/facades/mcp-data-marts.facade';
 import { PublicOriginService } from '../../../common/config/public-origin.service';
@@ -6,23 +6,23 @@ import type { McpAuthContext } from '../auth/mcp-auth-context';
 import { type McpToolDefinition, type McpToolResult } from './mcp-tool.definition';
 declare const inputSchema: z.ZodObject<{
     data_mart_id: z.ZodString;
-    detail_level: z.ZodOptional<z.ZodEnum<["native", "with_joined_fields"]>>;
-}, "strict", z.ZodTypeAny, {
-    data_mart_id: string;
-    detail_level?: "native" | "with_joined_fields" | undefined;
-}, {
-    data_mart_id: string;
-    detail_level?: "native" | "with_joined_fields" | undefined;
-}>;
+    detail_level: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        with_joined_fields: "with_joined_fields";
+    }>>;
+}, z.core.$strict>;
 type GetDataMartDetailsInput = z.infer<typeof inputSchema>;
 export declare class GetDataMartDetailsTool implements McpToolDefinition<GetDataMartDetailsInput> {
     private readonly dataMarts;
     private readonly publicOriginService;
     readonly name = "get_data_mart_details_by_id";
-    readonly description = "Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type \"category\", and every field carries the effective \"allowedAggregations\" query_data_mart may apply to it; \"operators_by_category\" maps each category to the filter/slice operators its fields accept \u2014 build queries from these instead of guessing. An empty allowedAggregations on a field whose \"calculated\" level is \"metric\" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the \"usage\" note carried on that field. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.";
+    readonly description = "Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type \"category\", and every field carries the effective \"allowedAggregations\" query_data_mart may apply to it; \"operators_by_category\" maps each category to the filter/slice operators its fields accept \u2014 build queries from these instead of guessing. An empty allowedAggregations on a field whose \"calculated\" level is \"metric\" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the \"usage\" note carried on that field \u2014 it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.";
     readonly zodSchema: {
         data_mart_id: z.ZodString;
-        detail_level: z.ZodOptional<z.ZodEnum<["native", "with_joined_fields"]>>;
+        detail_level: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            with_joined_fields: "with_joined_fields";
+        }>>;
     };
     readonly outputSchema: {
         id: z.ZodString;
@@ -36,48 +36,12 @@ export declare class GetDataMartDetailsTool implements McpToolDefinition<GetData
             businessName: z.ZodOptional<z.ZodString>;
             displayName: z.ZodOptional<z.ZodString>;
             category: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString>>;
             calculated: z.ZodOptional<z.ZodObject<{
                 level: z.ZodOptional<z.ZodString>;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">>>;
+            }, z.core.$loose>>;
             usage: z.ZodOptional<z.ZodString>;
-        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-            name: z.ZodString;
-            type: z.ZodString;
-            description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-            businessName: z.ZodOptional<z.ZodString>;
-            displayName: z.ZodOptional<z.ZodString>;
-            category: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            calculated: z.ZodOptional<z.ZodObject<{
-                level: z.ZodOptional<z.ZodString>;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">>>;
-            usage: z.ZodOptional<z.ZodString>;
-        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-            name: z.ZodString;
-            type: z.ZodString;
-            description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-            businessName: z.ZodOptional<z.ZodString>;
-            displayName: z.ZodOptional<z.ZodString>;
-            category: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            calculated: z.ZodOptional<z.ZodObject<{
-                level: z.ZodOptional<z.ZodString>;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                level: z.ZodOptional<z.ZodString>;
-            }, z.ZodTypeAny, "passthrough">>>;
-            usage: z.ZodOptional<z.ZodString>;
-        }, z.ZodTypeAny, "passthrough">>, "many">;
+        }, z.core.$loose>>;
         joined_fields_included: z.ZodBoolean;
         joined_fields: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -88,28 +52,8 @@ export declare class GetDataMartDetailsTool implements McpToolDefinition<GetData
             category: z.ZodOptional<z.ZodString>;
             sliceType: z.ZodOptional<z.ZodString>;
             sliceCategory: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-            name: z.ZodString;
-            displayName: z.ZodString;
-            type: z.ZodString;
-            description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-            sourceDataMart: z.ZodString;
-            category: z.ZodOptional<z.ZodString>;
-            sliceType: z.ZodOptional<z.ZodString>;
-            sliceCategory: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-            name: z.ZodString;
-            displayName: z.ZodString;
-            type: z.ZodString;
-            description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-            sourceDataMart: z.ZodString;
-            category: z.ZodOptional<z.ZodString>;
-            sliceType: z.ZodOptional<z.ZodString>;
-            sliceCategory: z.ZodOptional<z.ZodString>;
-            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        }, z.ZodTypeAny, "passthrough">>, "many">;
+            allowedAggregations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>>;
         joins: z.ZodArray<z.ZodObject<{
             aliasPath: z.ZodString;
             sourceDataMart: z.ZodString;
@@ -117,46 +61,10 @@ export declare class GetDataMartDetailsTool implements McpToolDefinition<GetData
             joinConditions: z.ZodArray<z.ZodObject<{
                 sourceFieldName: z.ZodString;
                 targetFieldName: z.ZodString;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">>, "many">;
-            description: z.ZodOptional<z.ZodString>;
-        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-            aliasPath: z.ZodString;
-            sourceDataMart: z.ZodString;
-            targetDataMart: z.ZodString;
-            joinConditions: z.ZodArray<z.ZodObject<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">>, "many">;
-            description: z.ZodOptional<z.ZodString>;
-        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-            aliasPath: z.ZodString;
-            sourceDataMart: z.ZodString;
-            targetDataMart: z.ZodString;
-            joinConditions: z.ZodArray<z.ZodObject<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-                sourceFieldName: z.ZodString;
-                targetFieldName: z.ZodString;
-            }, z.ZodTypeAny, "passthrough">>, "many">;
+            }, z.core.$loose>>;
             description: z.ZodOptional<z.ZodString>;
-        }, z.ZodTypeAny, "passthrough">>, "many">;
-        operators_by_category: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>;
+        }, z.core.$loose>>;
+        operators_by_category: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
     };
     readonly annotations: {
         title: string;

package/dist/src/ee/mcp/tools/data-mart-details.tool.js

@@ -14,7 +14,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetDataMartDetailsTool = void 0;
 const common_1 = require("@nestjs/common");
-const zod_1 = require("zod");
+const zod_v4_1 = require("zod-v4");
 const mcp_data_marts_facade_1 = require("../../../data-marts/facades/mcp-data-marts.facade");
 const public_origin_service_1 = require("../../../common/config/public-origin.service");
 const mcp_tool_definition_1 = require("./mcp-tool.definition");
@@ -25,26 +25,26 @@ const formula_level_1 = require("../../../data-marts/calculated-fields/formula-l
 const data_mart_schema_utils_1 = require("../../../data-marts/data-storage-types/data-mart-schema.utils");
 const field_type_compatibility_1 = require("../../../data-marts/data-storage-types/field-type-compatibility");
 const field_type_matrix_1 = require("./field-type-matrix");
-const inputSchema = zod_1.z
+const inputSchema = zod_v4_1.z
     .object({
-    data_mart_id: zod_1.z.string().trim().min(1),
-    detail_level: zod_1.z
+    data_mart_id: zod_v4_1.z.string().trim().min(1),
+    detail_level: zod_v4_1.z
         .enum(['native', 'with_joined_fields'])
         .optional()
         .describe('Use native (default) for ordinary queries. Request with_joined_fields only when the answer requires data from a joined Data Mart.'),
 })
     .strict();
-const makeCategoryField = () => zod_1.z
+const makeCategoryField = () => zod_v4_1.z
     .string()
     .optional()
     .describe('Field-type category (number/string/date/time/boolean/other) — the key into operators_by_category for the operators this field accepts in filters. Omitted for array fields, which can only be selected as columns. For slice operators, use "sliceCategory" instead when it is present.');
-const makeAllowedAggregationsField = () => zod_1.z
-    .array(zod_1.z.string())
+const makeAllowedAggregationsField = () => zod_v4_1.z
+    .array(zod_v4_1.z.string())
     .optional()
     .describe('The aggregation functions query_data_mart may apply to THIS field (type defaults narrowed by per-field settings). Use only these. An empty array means this field takes no aggregation — because it is an array, because its settings allow none, or because it is a Calculated Field that already aggregates; read "calculated" and "usage" to tell which.');
-const makeCalculatedField = () => zod_1.z
+const makeCalculatedField = () => zod_v4_1.z
     .object({
-    level: zod_1.z
+    level: zod_v4_1.z
         .string()
         .optional()
         .describe('"metric" — the formula is ALREADY aggregated: select it by name and it is recomputed correctly at whatever grain your query asks for, including in a query that reads a joined Data Mart; it cannot be aggregated again (its allowedAggregations is empty), used as a group-by dimension, or given a date_bucket. This is also the meaning when the property is absent. "column" — the formula is row-level, so the field IS an ordinary dimension: select it by name and group by it exactly like a real column, including in a query that reads a joined Data Mart; it also accepts any aggregation listed in its own allowedAggregations (e.g. COUNT_DISTINCT), and applying one makes it a metric of that query rather than one of its grouping keys; when its declared type is DATE or TIMESTAMP it also takes a date_bucket, on the same rule a real date column follows. Filtering works at BOTH levels: a row-level field filters on its computed value like an ordinary column, and a metric filters on its aggregated value — but a metric filter needs the query to name its fields explicitly rather than relying on the default all-columns projection.'),
@@ -54,58 +54,62 @@ const makeCalculatedField = () => zod_1.z
     .describe('Present when this field is a Calculated Field: a value the Data Mart computes from a formula instead of reading it from a warehouse column. Its "level" says whether it behaves as a metric or as a dimension — read that before using the field. When "level" is absent the field is a metric; nothing backfills it, so every field defined before levels existed arrives without one.');
 const AGGREGATE_LEVEL_USAGE = 'Already computed by OWOX at the grain your query asks for: list it in "fields" and read the ' +
     'value. Do not recompute it from other fields, and do not name it in "aggregations".';
-const DataMartFieldSchema = zod_1.z
+const GRAIN_CAVEAT_PREFIX = 'Caveat to pass on to the user with this number — a change to its formula belongs in the ' +
+    'Data Mart:';
+const DataMartFieldSchema = zod_v4_1.z
     .object({
-    name: zod_1.z.string(),
-    type: zod_1.z.string(),
-    description: zod_1.z.string().optional().nullable(),
-    businessName: zod_1.z.string().optional(),
-    displayName: zod_1.z.string().optional(),
+    name: zod_v4_1.z.string(),
+    type: zod_v4_1.z.string(),
+    description: zod_v4_1.z.string().optional().nullable(),
+    businessName: zod_v4_1.z.string().optional(),
+    displayName: zod_v4_1.z.string().optional(),
     category: makeCategoryField(),
     allowedAggregations: makeAllowedAggregationsField(),
     calculated: makeCalculatedField(),
-    usage: zod_1.z
+    usage: zod_v4_1.z
         .string()
         .optional()
-        .describe('Present only on a field the Data Mart has ALREADY computed for you. Read it before writing a query that mentions this field.'),
+        .describe('Present on a field that needs reading before you query it: one the Data Mart has ' +
+        'ALREADY computed for you, one whose number a join can distort, or both. Read it ' +
+        'before writing a query that mentions this field.'),
 })
     .passthrough();
-const JoinedFieldSchema = zod_1.z
+const JoinedFieldSchema = zod_v4_1.z
     .object({
-    name: zod_1.z
+    name: zod_v4_1.z
         .string()
         .describe('Qualified field name (<alias>__<field>) — copy verbatim into query_data_mart fields, and into filters/slices only when the corresponding category is present.'),
-    displayName: zod_1.z
+    displayName: zod_v4_1.z
         .string()
         .describe('Business-friendly label for presentation; use name for queries.'),
-    type: zod_1.z
+    type: zod_v4_1.z
         .string()
         .describe('Type in the blended result. Use filter operators or aggregation functions only when the corresponding category or allowedAggregations metadata is present. For slices, use "sliceType" when present. A field without category whose sliceType is an ARRAY can only be selected as a column.'),
-    description: zod_1.z.string().optional().nullable(),
-    sourceDataMart: zod_1.z.string().describe('Title of the joined data mart this field comes from.'),
+    description: zod_v4_1.z.string().optional().nullable(),
+    sourceDataMart: zod_v4_1.z.string().describe('Title of the joined data mart this field comes from.'),
     category: makeCategoryField(),
-    sliceType: zod_1.z
+    sliceType: zod_v4_1.z
         .string()
         .optional()
         .describe('Present only when this field is deduplicated with a type-changing aggregation. A slice runs BEFORE the join on the original value, so pick slice operators for this pre-join type — not "type". An ARRAY sliceType means the field can only be selected as a column. Absent when the two types are the same.'),
-    sliceCategory: zod_1.z
+    sliceCategory: zod_v4_1.z
         .string()
         .optional()
         .describe('Category of "sliceType" — the operators_by_category key for SLICE operators on this field. Omitted for array fields; otherwise present when sliceType is.'),
     allowedAggregations: makeAllowedAggregationsField(),
 })
     .passthrough();
-const JoinSchema = zod_1.z
+const JoinSchema = zod_v4_1.z
     .object({
-    aliasPath: zod_1.z
+    aliasPath: zod_v4_1.z
         .string()
         .describe('Dotted alias path of the joined source — matches the "<alias>__" prefix of joined_fields names.'),
-    sourceDataMart: zod_1.z.string().describe('Title of the data mart on the left side of this join.'),
-    targetDataMart: zod_1.z.string().describe('Title of the joined data mart.'),
-    joinConditions: zod_1.z
-        .array(zod_1.z.object({ sourceFieldName: zod_1.z.string(), targetFieldName: zod_1.z.string() }).passthrough())
+    sourceDataMart: zod_v4_1.z.string().describe('Title of the data mart on the left side of this join.'),
+    targetDataMart: zod_v4_1.z.string().describe('Title of the joined data mart.'),
+    joinConditions: zod_v4_1.z
+        .array(zod_v4_1.z.object({ sourceFieldName: zod_v4_1.z.string(), targetFieldName: zod_v4_1.z.string() }).passthrough())
         .describe('Field pairs the rows are matched on (source field = target field).'),
-    description: zod_1.z
+    description: zod_v4_1.z
         .string()
         .optional()
         .describe('Analyst-written business meaning of this join (e.g. "Visitors from the website sign up for the product and convert into users"). May be specific to this join path — the same two data marts can carry a different meaning when joined through a different path. Use it to interpret joined fields and to reason about cause and effect across the joined data marts.'),
@@ -125,25 +129,25 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
     dataMarts;
     publicOriginService;
     name = 'get_data_mart_details_by_id';
-    description = 'Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type "category", and every field carries the effective "allowedAggregations" query_data_mart may apply to it; "operators_by_category" maps each category to the filter/slice operators its fields accept — build queries from these instead of guessing. An empty allowedAggregations on a field whose "calculated" level is "metric" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the "usage" note carried on that field. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.';
+    description = 'Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type "category", and every field carries the effective "allowedAggregations" query_data_mart may apply to it; "operators_by_category" maps each category to the filter/slice operators its fields accept — build queries from these instead of guessing. An empty allowedAggregations on a field whose "calculated" level is "metric" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the "usage" note carried on that field — it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.';
     zodSchema = inputSchema.shape;
     outputSchema = {
-        id: zod_1.z.string().describe('Data mart identifier.'),
-        name: zod_1.z.string().describe('Data mart display name.'),
-        url: zod_1.z.string().describe('Open this Data Mart in OWOX.'),
-        description: zod_1.z.string().describe('Data mart description.'),
-        fields: zod_1.z.array(DataMartFieldSchema).describe("The data mart's own (native) output fields."),
-        joined_fields_included: zod_1.z
+        id: zod_v4_1.z.string().describe('Data mart identifier.'),
+        name: zod_v4_1.z.string().describe('Data mart display name.'),
+        url: zod_v4_1.z.string().describe('Open this Data Mart in OWOX.'),
+        description: zod_v4_1.z.string().describe('Data mart description.'),
+        fields: zod_v4_1.z.array(DataMartFieldSchema).describe("The data mart's own (native) output fields."),
+        joined_fields_included: zod_v4_1.z
             .boolean()
             .describe('Whether joined_fields were requested and evaluated. false means joined fields were intentionally omitted; true means an empty joined_fields array has no accessible joined fields.'),
-        joined_fields: zod_1.z
+        joined_fields: zod_v4_1.z
             .array(JoinedFieldSchema)
             .describe('Fields available from joined/blended data marts when joined_fields_included is true. Reference each by its exact "name" in query_data_mart. Controllable joined fields may also be used in "slices"; an array field without category can only be used in "fields".'),
-        joins: zod_1.z
+        joins: zod_v4_1.z
             .array(JoinSchema)
             .describe('How the joined data marts relate to this one — one entry per join edge (populated only when joined_fields_included is true): the matched key fields plus, when set, the business meaning of the relationship. Read these before interpreting joined_fields.'),
-        operators_by_category: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.array(zod_1.z.string()))
+        operators_by_category: zod_v4_1.z
+            .record(zod_v4_1.z.string(), zod_v4_1.z.array(zod_v4_1.z.string()))
             .describe('For each controllable field-type category present in this data mart, the query_data_mart filter/slice operators its fields accept. Look up a field via its "category"; an array field without category can only be used in "fields". For boolean fields, eq/neq take a boolean true or false as the value.'),
     };
     annotations = {
@@ -169,9 +173,17 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
             roles: context.roles,
             dataMartId: parsed.data_mart_id,
             includeJoinedFields,
+            includeGrainCaveats: true,
         });
         const categories = new Set();
-        const fields = result.fields.map(f => this.enrichField(f, categories));
+        const grainCaveats = result.grainCaveats ?? {};
+        const fields = result.fields.map(f => {
+            const field = f;
+            const caveat = typeof field.name === 'string' && Object.hasOwn(grainCaveats, field.name)
+                ? grainCaveats[field.name]
+                : undefined;
+            return this.enrichField(field, categories, caveat);
+        });
         const joinedFields = result.joinedFields.map(f => this.enrichField(f, categories));
         const operatorsByCategory = {};
         for (const category of categories) {
@@ -190,7 +202,7 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
         };
         return (0, mcp_tool_definition_1.jsonToolResult)(structuredContent);
     }
-    enrichField(field, categories) {
+    enrichField(field, categories, grainCaveat) {
         const out = { ...field };
         let isArray = false;
         if (typeof out.type === 'string') {
@@ -217,9 +229,13 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
                         aggregationRole: out.aggregationRole,
                         allowedAggregations: out.allowedAggregations,
                     });
-            if (isAggregateLevelCalculatedField(out)) {
-                out.usage = AGGREGATE_LEVEL_USAGE;
-            }
+        }
+        const caveat = grainCaveat === undefined ? undefined : `${GRAIN_CAVEAT_PREFIX} ${grainCaveat}`;
+        if (isAggregateLevelCalculatedField(out)) {
+            out.usage = caveat ? `${AGGREGATE_LEVEL_USAGE} ${caveat}` : AGGREGATE_LEVEL_USAGE;
+        }
+        else if (caveat) {
+            out.usage = caveat;
         }
         if (out.category !== undefined && typeof out.sliceType === 'string') {
             const sliceCategory = (0, field_type_category_1.categorizeFieldType)(out.sliceType);