@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/dist/dsl/types/special-functions.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Type definitions for Dimensions DSL special functions.
+ * Includes types for classify(), extract_concepts(), and similar_documents().
+ * @module types/special-functions
+ */
+/**
+ * Array of valid classification systems for runtime validation.
+ * Use this constant in Zod schemas and other runtime checks.
+ */
+export declare const CLASSIFICATION_SYSTEMS: readonly ["FOR", "FOR_2020", "SDG", "SDG_2021", "RCDC", "HRCS_HC", "HRCS_RAC", "HRA", "BRA", "ICRP_CSO", "ICRP_CT", "UOA"];
+/**
+ * Classification systems supported by the Dimensions API.
+ * These systems categorize research into standardized taxonomies.
+ */
+export type ClassificationSystem = "FOR" | "FOR_2020" | "SDG" | "SDG_2021" | "RCDC" | "HRCS_HC" | "HRCS_RAC" | "HRA" | "BRA" | "ICRP_CSO" | "ICRP_CT" | "UOA";
+/**
+ * A single classification entry returned by the classify() function.
+ * Contains an identifier and human-readable name for a category.
+ */
+export interface ClassificationEntry {
+    /** The classification code identifier */
+    readonly id: string;
+    /** The human-readable name of the classification */
+    readonly name: string;
+}
+/**
+ * Response from the classify() function.
+ * Keys are the classification system name, values are arrays of classification entries.
+ *
+ * @template S - The classification system type
+ *
+ * @example
+ * ```typescript
+ * // FOR classification response
+ * const response: ClassifyResponse<"FOR"> = {
+ *   FOR: [
+ *     { id: "1117", name: "Public Health and Health Services" },
+ *     { id: "1103", name: "Clinical Sciences" }
+ *   ]
+ * };
+ * ```
+ */
+export type ClassifyResponse<S extends ClassificationSystem = ClassificationSystem> = {
+    readonly [K in S]: readonly ClassificationEntry[];
+};
+/**
+ * A concept extracted without a relevance score.
+ * Used when return_scores is false or not specified.
+ */
+export interface ConceptBasic {
+    /** The extracted concept string */
+    readonly concept: string;
+}
+/**
+ * A concept extracted with its relevance score.
+ * Used when return_scores=true is specified.
+ */
+export interface ConceptWithScore {
+    /** The extracted concept string */
+    readonly concept: string;
+    /** Relevance score indicating how strongly the concept relates to the text */
+    readonly relevance: number;
+}
+/**
+ * Response from the extract_concepts() function.
+ * Structure depends on whether return_scores was requested.
+ *
+ * @template WithScores - Whether relevance scores are included
+ *
+ * @example
+ * ```typescript
+ * // Without scores (default)
+ * const simple: ExtractConceptsResponse<false> = {
+ *   extracted_concepts: ["machine learning", "neural networks", "deep learning"]
+ * };
+ *
+ * // With scores
+ * const withScores: ExtractConceptsResponse<true> = {
+ *   extracted_concepts: [
+ *     { concept: "machine learning", relevance: 0.95 },
+ *     { concept: "neural networks", relevance: 0.87 }
+ *   ]
+ * };
+ * ```
+ */
+export type ExtractConceptsResponse<WithScores extends boolean = false> = WithScores extends true ? {
+    readonly extracted_concepts: readonly ConceptWithScore[];
+} : {
+    readonly extracted_concepts: readonly string[];
+};
+/**
+ * Input parameters for the classify() function.
+ */
+export interface ClassifyInput {
+    /** Document title (at least title or abstract must be provided) */
+    readonly title?: string;
+    /** Document abstract (at least title or abstract must be provided) */
+    readonly abstract?: string;
+    /** Classification system to use */
+    readonly system: ClassificationSystem;
+}
+/**
+ * Input parameters for the extract_concepts() function.
+ */
+export interface ExtractConceptsInput {
+    /** Text to extract concepts from */
+    readonly text: string;
+    /** Whether to include relevance scores in the response */
+    readonly returnScores?: boolean;
+}
+/**
+ * A single affiliation input for extract_affiliations().
+ * Can be either freetext (affiliation field) or structured (name, city, state, country).
+ */
+export interface AffiliationInput {
+    /** Freetext affiliation string (use this OR structured fields) */
+    readonly affiliation?: string;
+    /** Organization name (structured input) */
+    readonly name?: string;
+    /** City (structured input) */
+    readonly city?: string;
+    /** State/province (structured input) */
+    readonly state?: string;
+    /** Country (structured input) */
+    readonly country?: string;
+}
+/**
+ * Input parameters for the extract_affiliations() function.
+ */
+export interface ExtractAffiliationsInput {
+    /** Array of affiliation inputs to resolve */
+    readonly affiliations: readonly AffiliationInput[];
+    /** Results detail level: "basic" (default), "full", or "publisher" */
+    readonly results?: "basic" | "full" | "publisher";
+}
+/**
+ * A single affiliation result from extract_affiliations().
+ */
+export interface AffiliationResult {
+    /** The organization identifier (e.g., "grid.xxx" or "or.xxx") */
+    readonly id: string;
+    /** The canonical organization name */
+    readonly name: string;
+    /** Country of the organization */
+    readonly country?: string;
+    /** Match confidence score (0-1) */
+    readonly score?: number;
+}
+/**
+ * Response from the extract_affiliations() function.
+ */
+export interface ExtractAffiliationsResponse {
+    readonly extracted_affiliations: readonly AffiliationResult[];
+}
+/**
+ * Input parameters for the extract_grants() function.
+ */
+export interface ExtractGrantsInput {
+    /** Grant number to look up */
+    readonly grantNumber: string;
+    /** FundRef ID of the funder (alternative to funderName) */
+    readonly fundref?: string;
+    /** Funder name (alternative to fundref) */
+    readonly funderName?: string;
+}
+/**
+ * Response from the extract_grants() function.
+ * The Dimensions API resolves a grant number to a single grant ID.
+ * Returns `null` when no matching grant is found.
+ */
+export interface ExtractGrantsResponse {
+    /** Resolved Dimensions grant ID (e.g. "grant.2544064"), or null if not found */
+    readonly grant_id: string | null;
+}
+//# sourceMappingURL=special-functions.d.ts.map

package/dist/dsl/types/special-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"special-functions.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/special-functions.ts"],"names":[],"mappings":"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"}

package/dist/dsl/types/special-functions.js

@@ -0,0 +1,25 @@
+/**
+ * Type definitions for Dimensions DSL special functions.
+ * Includes types for classify(), extract_concepts(), and similar_documents().
+ * @module types/special-functions
+ */
+/**
+ * Array of valid classification systems for runtime validation.
+ * Use this constant in Zod schemas and other runtime checks.
+ */
+export const CLASSIFICATION_SYSTEMS = [
+    "FOR",
+    "FOR_2020",
+    "SDG",
+    "SDG_2021",
+    "RCDC",
+    "HRCS_HC",
+    "HRCS_RAC",
+    "HRA",
+    "BRA",
+    "ICRP_CSO",
+    "ICRP_CT",
+    "UOA",
+];
+// #endregion
+//# sourceMappingURL=special-functions.js.map

package/dist/dsl/types/special-functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"special-functions.js","sourceRoot":"","sources":["../../../src/dsl/types/special-functions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,KAAK;IACL,UAAU;IACV,KAAK;IACL,UAAU;IACV,MAAM;IACN,SAAS;IACT,UAAU;IACV,KAAK;IACL,KAAK;IACL,UAAU;IACV,SAAS;IACT,KAAK;CACG,CAAC;AAoMX,aAAa"}

package/dist/dsl/types/vocabulary.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Dimensions DSL vocabulary types and runtime validation lists.
+ * @module types/vocabulary
+ */
+/** Comparison operators supported in WHERE clause filters. */
+export type Operator = "=" | "!=" | "<" | ">" | "<=" | ">=" | "in" | "~" | "@";
+/** Backward-compatible alias for {@link Operator}. */
+export type WhereOperator = Operator;
+/** Supported entity types (data sources) in the Dimensions DSL. */
+export type EntityType = "publications" | "grants" | "researchers" | "patents" | "clinical_trials" | "datasets" | "policy_documents" | "organizations";
+/** Search indexes for `search <source> in <index> for "..."` clauses. */
+export type SearchIndex = "full_data" | "full_data_exact" | "title_abstract_only" | "title_only" | "authors" | "inventors" | "investigators" | "concepts" | "funding" | "acknowledgements" | "raw_affiliations" | "assignees" | "title_abstract_claims";
+/** Sort direction for order-by clauses. */
+export type SortOrder = "asc" | "desc";
+/** Valid operators for runtime validation. */
+export declare const VALID_OPERATORS: readonly Operator[];
+/** Valid entity types for runtime validation. */
+export declare const VALID_ENTITIES: readonly EntityType[];
+/** Valid search indexes for runtime validation. */
+export declare const VALID_INDEXES: readonly SearchIndex[];
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/dsl/types/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/vocabulary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAE/E,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;AAErC,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,QAAQ,GACR,aAAa,GACb,SAAS,GACT,iBAAiB,GACjB,UAAU,GACV,kBAAkB,GAClB,eAAe,CAAC;AAEpB,yEAAyE;AACzE,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,iBAAiB,GACjB,qBAAqB,GACrB,YAAY,GACZ,SAAS,GACT,WAAW,GACX,eAAe,GACf,UAAU,GACV,SAAS,GACT,kBAAkB,GAClB,kBAAkB,GAClB,WAAW,GACX,uBAAuB,CAAC;AAE5B,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvC,8CAA8C;AAC9C,eAAO,MAAM,eAAe,EAAE,SAAS,QAAQ,EAUrC,CAAC;AAEX,iDAAiD;AACjD,eAAO,MAAM,cAAc,EAAE,SAAS,UAAU,EAStC,CAAC;AAEX,mDAAmD;AACnD,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EActC,CAAC"}

package/dist/dsl/types/vocabulary.js

@@ -0,0 +1,44 @@
+/**
+ * Dimensions DSL vocabulary types and runtime validation lists.
+ * @module types/vocabulary
+ */
+/** Valid operators for runtime validation. */
+export const VALID_OPERATORS = [
+    "=",
+    "!=",
+    ">",
+    "<",
+    ">=",
+    "<=",
+    "in",
+    "~",
+    "@",
+];
+/** Valid entity types for runtime validation. */
+export const VALID_ENTITIES = [
+    "publications",
+    "grants",
+    "researchers",
+    "patents",
+    "clinical_trials",
+    "datasets",
+    "policy_documents",
+    "organizations",
+];
+/** Valid search indexes for runtime validation. */
+export const VALID_INDEXES = [
+    "full_data",
+    "full_data_exact",
+    "title_abstract_only",
+    "title_only",
+    "authors",
+    "inventors",
+    "investigators",
+    "concepts",
+    "funding",
+    "acknowledgements",
+    "raw_affiliations",
+    "assignees",
+    "title_abstract_claims",
+];
+//# sourceMappingURL=vocabulary.js.map

package/dist/dsl/types/vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../../src/dsl/types/vocabulary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsCH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,eAAe,GAAwB;IAClD,GAAG;IACH,IAAI;IACJ,GAAG;IACH,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,GAAG;IACH,GAAG;CACK,CAAC;AAEX,iDAAiD;AACjD,MAAM,CAAC,MAAM,cAAc,GAA0B;IACnD,cAAc;IACd,QAAQ;IACR,aAAa;IACb,SAAS;IACT,iBAAiB;IACjB,UAAU;IACV,kBAAkB;IAClB,eAAe;CACP,CAAC;AAEX,mDAAmD;AACnD,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,WAAW;IACX,iBAAiB;IACjB,qBAAqB;IACrB,YAAY;IACZ,SAAS;IACT,WAAW;IACX,eAAe;IACf,UAAU;IACV,SAAS;IACT,kBAAkB;IAClB,kBAAkB;IAClB,WAAW;IACX,uBAAuB;CACf,CAAC"}

package/dist/dsl/usage-policy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Dimensions reasonable-use policy guardrails for MCP tools.
+ * @see https://docs.dimensions.ai/dsl/usagepolicy.html
+ * @module dsl/usage-policy
+ */
+import { SCHEMA_LIMITS } from "./schema/store.js";
+/** Official Dimensions usage policy URL. */
+export declare const USAGE_POLICY_URL = "https://docs.dimensions.ai/dsl/usagepolicy.html";
+/** MCP resource URI for policy guidance. */
+export declare const USAGE_POLICY_RESOURCE_URI = "dimensions://schema/policy";
+/** Short notice included in guarded tool responses. */
+export declare const POLICY_NOTICE: string;
+/** Parsed skip/limit modifiers from a DSL query string. */
+export type DslPaginationModifiers = {
+    readonly limit?: number;
+    readonly skip?: number;
+};
+/** Payload for dimensions://schema/policy. */
+export type UsagePolicyPayload = {
+    readonly source: string;
+    readonly purpose: string;
+    readonly limits: typeof SCHEMA_LIMITS;
+    readonly guardrails: {
+        readonly largeResultWarningThreshold: number;
+        readonly confirmLargeFetchRequiredWhen: {
+            readonly batchMaxPagesExceeds: number;
+            readonly batchRecordsExceeds: number;
+            readonly searchSkipAtLeast: number;
+            readonly searchPageAtLeast: number;
+        };
+        readonly clientRateLimitPerMinute: number;
+    };
+    readonly recommendations: readonly string[];
+    readonly notice: string;
+};
+/**
+ * Builds the usage policy payload for MCP resources and agent discovery.
+ * @returns Policy guidance object
+ */
+export declare function buildUsagePolicy(): UsagePolicyPayload;
+/**
+ * Extracts `limit` and `skip` modifiers from a DSL query string.
+ * @param dsl - Raw DSL query
+ * @returns Parsed modifiers (undefined when absent)
+ */
+export declare function parseDslPagination(dsl: string): DslPaginationModifiers;
+/**
+ * Returns true when the DSL appears to be a facet-only query (no entity row pagination).
+ * @param dsl - Raw DSL query
+ * @returns Whether the query targets facets without entity records
+ */
+export declare function isFacetOnlyQuery(dsl: string): boolean;
+/** Options for single-page search policy validation. */
+export type SearchPolicyOptions = {
+    readonly skip: number;
+    readonly limit: number;
+    readonly confirmLargeFetch?: boolean;
+};
+/**
+ * Validates single-page search pagination against reasonable-use guardrails.
+ * @param options - Resolved skip/limit and optional confirmation flag
+ * @throws {ValidationError} When deep pagination lacks confirmation
+ */
+export declare function validateSearchPaginationPolicy(options: SearchPolicyOptions): void;
+/** Options for raw DSL policy validation. */
+export type ExecuteDslPolicyOptions = {
+    readonly dsl: string;
+    readonly confirmLargeFetch?: boolean;
+};
+/**
+ * Validates a raw DSL query against pagination and reasonable-use guardrails.
+ * @param options - DSL string and optional confirmation flag
+ * @throws {ValidationError} When the query violates policy bounds
+ */
+export declare function validateExecuteDslPolicy(options: ExecuteDslPolicyOptions): void;
+/**
+ * Builds response-level policy hints for execute_dsl results.
+ * @param dsl - Executed DSL query
+ * @param response - Raw API response
+ * @returns Optional policy fields to merge into the tool result
+ */
+export declare function buildExecuteDslPolicyHints(dsl: string, response: Record<string, unknown>): {
+    policyNotice?: string;
+    largeResultWarning?: string;
+    paginationHint?: string;
+};
+//# sourceMappingURL=usage-policy.d.ts.map

package/dist/dsl/usage-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-policy.d.ts","sourceRoot":"","sources":["../../src/dsl/usage-policy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,oDAAoD,CAAC;AAElF,4CAA4C;AAC5C,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE,uDAAuD;AACvD,eAAO,MAAM,aAAa,QAEmC,CAAC;AAE9D,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;QAC7C,QAAQ,CAAC,6BAA6B,EAAE;YACtC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;YACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;YACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;YACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;SACpC,CAAC;QACF,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;KAC3C,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAyBrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAOtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAarD;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAgBjF;AAED,6CAA6C;AAC7C,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAmB/E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;IACD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CA0BA"}

package/dist/dsl/usage-policy.js

@@ -0,0 +1,133 @@
+/**
+ * Dimensions reasonable-use policy guardrails for MCP tools.
+ * @see https://docs.dimensions.ai/dsl/usagepolicy.html
+ * @module dsl/usage-policy
+ */
+import { ValidationError } from "../client/index.js";
+import { CONFIRM_LARGE_FETCH_PAGES, CONFIRM_LARGE_FETCH_RECORDS, LARGE_RESULT_THRESHOLD, largeResultWarning, validatePaginationBounds, } from "./pagination.js";
+import { SCHEMA_LIMITS } from "./schema/store.js";
+/** Official Dimensions usage policy URL. */
+export const USAGE_POLICY_URL = "https://docs.dimensions.ai/dsl/usagepolicy.html";
+/** MCP resource URI for policy guidance. */
+export const USAGE_POLICY_RESOURCE_URI = "dimensions://schema/policy";
+/** Short notice included in guarded tool responses. */
+export const POLICY_NOTICE = "Dimensions API is for task-sized analytical queries, not bulk local copies or training data. " +
+    `See ${USAGE_POLICY_RESOURCE_URI} and ${USAGE_POLICY_URL}.`;
+/**
+ * Builds the usage policy payload for MCP resources and agent discovery.
+ * @returns Policy guidance object
+ */
+export function buildUsagePolicy() {
+    return {
+        source: USAGE_POLICY_URL,
+        purpose: "Support complex analytical tasks — not local copies of Dimensions data, training corpora, or open-ended crawling.",
+        limits: SCHEMA_LIMITS,
+        guardrails: {
+            largeResultWarningThreshold: LARGE_RESULT_THRESHOLD,
+            confirmLargeFetchRequiredWhen: {
+                batchMaxPagesExceeds: CONFIRM_LARGE_FETCH_PAGES,
+                batchRecordsExceeds: CONFIRM_LARGE_FETCH_RECORDS,
+                searchSkipAtLeast: CONFIRM_LARGE_FETCH_RECORDS,
+                searchPageAtLeast: CONFIRM_LARGE_FETCH_PAGES,
+            },
+            clientRateLimitPerMinute: SCHEMA_LIMITS.requestsPerMinute,
+        },
+        recommendations: [
+            "Start with narrow filters and facet_query before paginating large sets",
+            "Use search_* with default limit 100 for discovery; raise only when needed",
+            "Use fetch_search_pages aggregate mode for ID lists and counts without full rows",
+            "Use fetch_search_pages file mode (JSONL or CSV) only with outputPath and confirmLargeFetch for large exports",
+            "Facets return at most 1000 buckets with no pagination — do not loop facet queries",
+        ],
+        notice: POLICY_NOTICE,
+    };
+}
+/**
+ * Extracts `limit` and `skip` modifiers from a DSL query string.
+ * @param dsl - Raw DSL query
+ * @returns Parsed modifiers (undefined when absent)
+ */
+export function parseDslPagination(dsl) {
+    const limitMatch = dsl.match(/\blimit\s+(\d+)\b/i);
+    const skipMatch = dsl.match(/\bskip\s+(\d+)\b/i);
+    return {
+        ...(limitMatch ? { limit: Number.parseInt(limitMatch[1], 10) } : {}),
+        ...(skipMatch ? { skip: Number.parseInt(skipMatch[1], 10) } : {}),
+    };
+}
+/**
+ * Returns true when the DSL appears to be a facet-only query (no entity row pagination).
+ * @param dsl - Raw DSL query
+ * @returns Whether the query targets facets without entity records
+ */
+export function isFacetOnlyQuery(dsl) {
+    const hasFacetReturn = /\breturn\s+(?:year|journal|funder|researcher|category|phase|source|repository|funder_orgs?)\b/i.test(dsl) ||
+        /\breturn\s+\w+\s+facet\b/i.test(dsl) ||
+        /\bfacet\s+\w+/i.test(dsl);
+    const hasEntityReturn = /\breturn\s+(?:publications|grants|patents|clinical_trials|datasets|policy_documents|researchers|organizations)\b/i.test(dsl);
+    const limitZero = /\blimit\s+0\b/i.test(dsl);
+    return hasFacetReturn && (!hasEntityReturn || limitZero);
+}
+/**
+ * Validates single-page search pagination against reasonable-use guardrails.
+ * @param options - Resolved skip/limit and optional confirmation flag
+ * @throws {ValidationError} When deep pagination lacks confirmation
+ */
+export function validateSearchPaginationPolicy(options) {
+    const { skip, limit, confirmLargeFetch } = options;
+    const page = limit > 0 ? Math.floor(skip / limit) : 0;
+    const needsConfirm = skip >= CONFIRM_LARGE_FETCH_RECORDS ||
+        page >= CONFIRM_LARGE_FETCH_PAGES ||
+        (limit === SCHEMA_LIMITS.maxLimit && skip > 0);
+    if (needsConfirm && !confirmLargeFetch) {
+        throw new ValidationError(`Deep pagination requires confirmLargeFetch: true (skip=${skip}, limit=${limit}, page≈${page}). ` +
+            "Narrow filters first or use facet_query. See dimensions://schema/policy.", { skip, limit, page, confirmLargeFetch, policyUri: USAGE_POLICY_RESOURCE_URI });
+    }
+}
+/**
+ * Validates a raw DSL query against pagination and reasonable-use guardrails.
+ * @param options - DSL string and optional confirmation flag
+ * @throws {ValidationError} When the query violates policy bounds
+ */
+export function validateExecuteDslPolicy(options) {
+    const { dsl, confirmLargeFetch } = options;
+    const { limit, skip } = parseDslPagination(dsl);
+    if (isFacetOnlyQuery(dsl) && skip !== undefined && skip > 0) {
+        throw new ValidationError("Facet queries cannot be paginated with skip — facets return at most 1000 buckets with no pagination.", { skip, policyUri: USAGE_POLICY_RESOURCE_URI });
+    }
+    if (skip !== undefined || limit !== undefined) {
+        validatePaginationBounds(skip ?? 0, limit ?? SCHEMA_LIMITS.maxLimit);
+        validateSearchPaginationPolicy({
+            skip: skip ?? 0,
+            limit: limit ?? 100,
+            confirmLargeFetch,
+        });
+    }
+}
+/**
+ * Builds response-level policy hints for execute_dsl results.
+ * @param dsl - Executed DSL query
+ * @param response - Raw API response
+ * @returns Optional policy fields to merge into the tool result
+ */
+export function buildExecuteDslPolicyHints(dsl, response) {
+    const stats = response._stats;
+    const totalCount = stats?.total_count;
+    const hints = {};
+    const warning = totalCount !== undefined ? largeResultWarning(totalCount) : undefined;
+    if (warning) {
+        hints.largeResultWarning = warning;
+        hints.policyNotice = POLICY_NOTICE;
+    }
+    const { limit, skip } = parseDslPagination(dsl);
+    if (totalCount !== undefined && limit !== undefined && totalCount > (skip ?? 0) + limit) {
+        const pages = Math.ceil(totalCount / limit);
+        const minutes = Math.ceil(pages / SCHEMA_LIMITS.requestsPerMinute);
+        hints.paginationHint =
+            `${totalCount} total matches; this page returned up to ${limit}. ` +
+                `Full pagination ≈${pages} requests (~${minutes} min). Prefer search_* or fetch_search_pages.`;
+        hints.policyNotice ??= POLICY_NOTICE;
+    }
+    return hints;
+}
+//# sourceMappingURL=usage-policy.js.map

package/dist/dsl/usage-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-policy.js","sourceRoot":"","sources":["../../src/dsl/usage-policy.ts"],"names":[],"mappings":"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"}

package/dist/dsl/utils/escape.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Escapes a string for safe inclusion in a DSL query.
+ *
+ * Handles backslashes, double quotes (including Unicode smart quotes),
+ * and control characters to prevent DSL injection attacks when
+ * user-supplied strings are interpolated into queries.
+ *
+ * Characters escaped via `\uXXXX` (ANTLR grammar-compatible):
+ * - Null byte and C0 controls (U+0000–U+001F) not covered by named escapes
+ * - DEL and C1 controls (U+007F–U+009F)
+ * - Smart single quotes (U+2018, U+2019)
+ * - Line and paragraph separators (U+2028, U+2029)
+ *
+ * @param text - The string to escape
+ * @returns The escaped string safe for DSL interpolation
+ */
+export declare function escapeDslString(text: string): string;
+/**
+ * Unescapes DSL string literal content (inverse of {@link escapeDslString} for common sequences).
+ * @param text - Escaped string content without surrounding quotes
+ * @returns Unescaped string
+ */
+export declare function unescapeDslString(text: string): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/dsl/utils/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../../src/dsl/utils/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkDpD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiDtD"}