@voyant-travel/reporting-contracts 0.1.0

package/dist/contracts.js

@@ -0,0 +1,293 @@
+import { z } from "zod";
+// Graph entity ids commonly include scoped package names and a `#facet.entity` suffix.
+const identifierPattern = /^[A-Za-z0-9@][A-Za-z0-9._/@#-]*$/;
+export const reportingIdentifierSchema = z.string().trim().min(1).max(160).regex(identifierPattern);
+export const reportingVersionSchema = z.number().int().positive();
+export const reportingScopeSchema = z.string().trim().min(3).max(160);
+export const reportScalarSchema = z.union([z.string(), z.number().finite(), z.boolean(), z.null()]);
+export const reportParameterValueSchema = z.union([
+    reportScalarSchema,
+    z.array(reportScalarSchema).max(500),
+]);
+export const reportParametersSchema = z.record(z.string(), reportParameterValueSchema);
+export const reportFieldValueTypeSchema = z.enum([
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "date",
+    "datetime",
+    "currency",
+    "json",
+]);
+export const reportFieldSensitivitySchema = z.enum(["public", "internal", "pii", "sensitive"]);
+export const reportAggregationSchema = z.enum([
+    "count",
+    "countDistinct",
+    "sum",
+    "average",
+    "minimum",
+    "maximum",
+]);
+export const reportDatasetFieldSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    label: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(1_000).optional(),
+    role: z.enum(["dimension", "measure"]),
+    valueType: reportFieldValueTypeSchema,
+    sensitivity: reportFieldSensitivitySchema.default("internal"),
+    requiredScopes: z.array(reportingScopeSchema).max(20).default([]),
+    aggregations: z.array(reportAggregationSchema).max(6).default([]),
+})
+    .strict();
+export const reportDatasetDefinitionSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    version: reportingVersionSchema,
+    label: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(2_000).optional(),
+    grain: z.string().trim().min(1).max(300),
+    requiredScopes: z.array(reportingScopeSchema).max(20).default([]),
+    fields: z.array(reportDatasetFieldSchema).min(1).max(250),
+    defaultLimit: z.number().int().positive().max(1_000).default(100),
+    maximumLimit: z.number().int().positive().max(5_000).default(1_000),
+})
+    .strict()
+    .superRefine((dataset, context) => {
+    const ids = new Set();
+    for (const [index, field] of dataset.fields.entries()) {
+        if (ids.has(field.id)) {
+            context.addIssue({
+                code: "custom",
+                message: `Duplicate dataset field ${JSON.stringify(field.id)}.`,
+                path: ["fields", index, "id"],
+            });
+        }
+        ids.add(field.id);
+    }
+    if (dataset.defaultLimit > dataset.maximumLimit) {
+        context.addIssue({
+            code: "custom",
+            message: "defaultLimit cannot exceed maximumLimit.",
+            path: ["defaultLimit"],
+        });
+    }
+});
+export const reportValueReferenceSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("literal"), value: reportParameterValueSchema }).strict(),
+    z.object({ kind: z.literal("parameter"), name: reportingIdentifierSchema }).strict(),
+]);
+export const reportFilterSchema = z
+    .object({
+    field: reportingIdentifierSchema,
+    operator: z.enum([
+        "equal",
+        "notEqual",
+        "in",
+        "notIn",
+        "greaterThan",
+        "greaterThanOrEqual",
+        "lessThan",
+        "lessThanOrEqual",
+        "between",
+        "contains",
+        "isNull",
+        "isNotNull",
+    ]),
+    value: reportValueReferenceSchema.optional(),
+})
+    .strict();
+export const reportSelectionSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("field"),
+        field: reportingIdentifierSchema,
+        as: reportingIdentifierSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("aggregate"),
+        operation: reportAggregationSchema,
+        field: reportingIdentifierSchema.optional(),
+        as: reportingIdentifierSchema,
+    })
+        .strict(),
+]);
+export const reportGroupSchema = z
+    .object({
+    field: reportingIdentifierSchema,
+    timeGrain: z.enum(["day", "week", "month", "quarter", "year"]).optional(),
+})
+    .strict();
+export const reportOrderSchema = z
+    .object({
+    by: reportingIdentifierSchema,
+    direction: z.enum(["ascending", "descending"]).default("ascending"),
+})
+    .strict();
+export const reportQuerySchema = z
+    .object({
+    dataset: z.object({
+        id: reportingIdentifierSchema,
+        version: reportingVersionSchema.optional(),
+    }),
+    select: z.array(reportSelectionSchema).min(1).max(50),
+    filters: z.array(reportFilterSchema).max(50).default([]),
+    groupBy: z.array(reportGroupSchema).max(20).default([]),
+    orderBy: z.array(reportOrderSchema).max(10).default([]),
+    limit: z.number().int().positive().max(5_000).optional(),
+})
+    .strict();
+export const reportColumnSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    label: z.string().trim().min(1).max(160),
+    valueType: reportFieldValueTypeSchema,
+})
+    .strict();
+export const reportResultSchema = z
+    .object({
+    columns: z.array(reportColumnSchema).max(100),
+    rows: z.array(z.record(z.string(), z.unknown())).max(5_000),
+    truncated: z.boolean().default(false),
+    warnings: z.array(z.string().max(500)).max(50).default([]),
+})
+    .strict();
+export const reportVisualizationSchema = z
+    .object({
+    type: z.enum(["kpi", "table", "line", "bar", "pie"]),
+    options: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const reportGridSizeSchema = z
+    .object({ width: z.number().int().min(1).max(12), height: z.number().int().min(1).max(100) })
+    .strict();
+export const reportGridLayoutSchema = reportGridSizeSchema
+    .extend({ x: z.number().int().min(0).max(11), y: z.number().int().min(0).max(10_000) })
+    .superRefine((layout, context) => {
+    if (layout.x + layout.width > 12) {
+        context.addIssue({ code: "custom", message: "Widget extends beyond the 12-column grid." });
+    }
+});
+export const reportWidgetDefinitionSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    version: reportingVersionSchema,
+    label: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(1_000).optional(),
+    query: reportQuerySchema,
+    visualization: reportVisualizationSchema,
+    defaultSize: reportGridSizeSchema,
+    minimumSize: reportGridSizeSchema.optional(),
+    maximumSize: reportGridSizeSchema.optional(),
+})
+    .strict();
+export const reportWidgetInstanceSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    source: z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("preset"),
+            widgetId: reportingIdentifierSchema,
+            version: reportingVersionSchema.optional(),
+        })
+            .strict(),
+        z.object({ kind: z.literal("custom"), definition: reportWidgetDefinitionSchema }).strict(),
+    ]),
+    title: z.string().trim().min(1).max(160).optional(),
+    layout: reportGridLayoutSchema,
+})
+    .strict();
+export const reportTemplateDefinitionSchema = z
+    .object({
+    id: reportingIdentifierSchema,
+    version: reportingVersionSchema,
+    label: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(2_000).optional(),
+    parameters: z.array(reportingIdentifierSchema).max(50).default([]),
+    widgets: z.array(reportWidgetInstanceSchema).max(50),
+})
+    .strict();
+export const reportDraftSchema = z
+    .object({
+    parameters: reportParametersSchema.default({}),
+    widgets: z.array(reportWidgetInstanceSchema).max(50).default([]),
+})
+    .strict()
+    .superRefine((draft, context) => {
+    const ids = new Set();
+    for (const [index, widget] of draft.widgets.entries()) {
+        if (ids.has(widget.id)) {
+            context.addIssue({
+                code: "custom",
+                message: `Duplicate widget instance ${JSON.stringify(widget.id)}.`,
+                path: ["widgets", index, "id"],
+            });
+        }
+        ids.add(widget.id);
+    }
+    for (let leftIndex = 0; leftIndex < draft.widgets.length; leftIndex += 1) {
+        const left = draft.widgets[leftIndex];
+        if (!left)
+            continue;
+        for (let rightIndex = leftIndex + 1; rightIndex < draft.widgets.length; rightIndex += 1) {
+            const right = draft.widgets[rightIndex];
+            if (!right)
+                continue;
+            const overlaps = left.layout.x < right.layout.x + right.layout.width &&
+                left.layout.x + left.layout.width > right.layout.x &&
+                left.layout.y < right.layout.y + right.layout.height &&
+                left.layout.y + left.layout.height > right.layout.y;
+            if (overlaps) {
+                context.addIssue({
+                    code: "custom",
+                    message: `Widget ${JSON.stringify(right.id)} overlaps ${JSON.stringify(left.id)}.`,
+                    path: ["widgets", rightIndex, "layout"],
+                });
+            }
+        }
+    }
+});
+export const createReportDefinitionSchema = z
+    .object({
+    name: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(2_000).nullable().optional(),
+    sourceTemplateId: reportingIdentifierSchema.nullable().optional(),
+    sourceTemplateVersion: reportingVersionSchema.nullable().optional(),
+    draft: reportDraftSchema.default({ parameters: {}, widgets: [] }),
+})
+    .strict();
+export const updateReportDefinitionSchema = z
+    .object({
+    revision: z.number().int().positive(),
+    name: z.string().trim().min(1).max(160).optional(),
+    description: z.string().trim().max(2_000).nullable().optional(),
+    draft: reportDraftSchema.optional(),
+})
+    .strict();
+export const listReportDefinitionsQuerySchema = z.object({
+    limit: z.coerce.number().int().positive().max(100).default(25),
+    offset: z.coerce.number().int().nonnegative().default(0),
+});
+export const createReportVersionSchema = z
+    .object({ expectedRevision: z.number().int().positive() })
+    .strict();
+export const executeReportVersionSchema = z
+    .object({ parameters: reportParametersSchema.default({}) })
+    .strict();
+export const previewReportQuerySchema = z
+    .object({ query: reportQuerySchema, parameters: reportParametersSchema.default({}) })
+    .strict();
+export const parseReportQuerySourceSchema = z
+    .object({ source: z.string().trim().min(1).max(10_000) })
+    .strict();
+export const instantiateReportTemplateSchema = z
+    .object({
+    name: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(2_000).nullable().optional(),
+    version: reportingVersionSchema.optional(),
+})
+    .strict();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./contracts.js";
+export * from "./query-language.js";
+export * from "./runtime-port.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./contracts.js";
+export * from "./query-language.js";
+export * from "./runtime-port.js";

package/dist/query-language.d.ts

@@ -0,0 +1,11 @@
+import type { ReportQuery } from "./contracts.js";
+/** Error raised when the bounded report query language cannot compile a source string. */
+export declare class ReportQuerySyntaxError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compile the intentionally small reporting language into the public query AST.
+ * It is SQL-like for familiarity but has no joins, subqueries, statements, or
+ * table access. Dataset owners remain responsible for executing the AST.
+ */
+export declare function parseReportQuery(source: string): ReportQuery;

package/dist/query-language.js

@@ -0,0 +1,228 @@
+import { reportingIdentifierSchema, reportQuerySchema } from "./contracts.js";
+const forbiddenSource = /(?:;|--|\/\*|\*\/|\b(?:join|union|insert|update|delete|drop|alter|create|grant|revoke|truncate|execute|call)\b)/i;
+const aggregateFunctions = {
+    count: "count",
+    countdistinct: "countDistinct",
+    sum: "sum",
+    average: "average",
+    avg: "average",
+    minimum: "minimum",
+    min: "minimum",
+    maximum: "maximum",
+    max: "maximum",
+};
+/** Error raised when the bounded report query language cannot compile a source string. */
+export class ReportQuerySyntaxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReportQuerySyntaxError";
+    }
+}
+/**
+ * Compile the intentionally small reporting language into the public query AST.
+ * It is SQL-like for familiarity but has no joins, subqueries, statements, or
+ * table access. Dataset owners remain responsible for executing the AST.
+ */
+export function parseReportQuery(source) {
+    const normalized = source.trim().replace(/\s+/g, " ");
+    if (normalized.length === 0)
+        throw syntax("Query source is empty.");
+    if (normalized.length > 10_000)
+        throw syntax("Query source exceeds 10,000 characters.");
+    if (forbiddenSource.test(normalized))
+        throw syntax("Query contains a forbidden construct.");
+    if (normalized.includes("*"))
+        throw syntax("Wildcard selections are not supported.");
+    const clauses = normalized.match(/^from\s+(\S+?)(?:\s+where\s+(.+?))?(?:\s+group\s+by\s+(.+?))?\s+select\s+(.+?)(?:\s+order\s+by\s+(.+?))?(?:\s+limit\s+(\d+))?$/i);
+    if (!clauses) {
+        throw syntax("Expected `from <dataset> [where ...] [group by ...] select ... [order by ...] [limit ...]`.");
+    }
+    const [, datasetSource, filterSource, groupSource, selectSource, orderSource, limitSource] = clauses;
+    const dataset = parseIdentifier(datasetSource, "dataset");
+    const query = {
+        dataset: { id: dataset },
+        select: splitList(required(selectSource, "select")).map(parseSelection),
+        filters: filterSource ? splitAnd(filterSource).map(parseFilter) : [],
+        groupBy: groupSource ? splitList(groupSource).map(parseGroup) : [],
+        orderBy: orderSource ? splitList(orderSource).map(parseOrder) : [],
+        limit: limitSource ? Number.parseInt(limitSource, 10) : undefined,
+    };
+    const parsed = reportQuerySchema.safeParse(query);
+    if (!parsed.success)
+        throw syntax(parsed.error.issues[0]?.message ?? "Invalid report query.");
+    return parsed.data;
+}
+function parseSelection(source) {
+    const aggregate = source.match(/^([a-z]+)\(([^)]*)\)\s+as\s+([a-z0-9][a-z0-9._/-]*)$/i);
+    if (aggregate) {
+        const operation = aggregateFunctions[aggregate[1]?.toLowerCase()];
+        if (!operation)
+            throw syntax(`Unsupported aggregate function ${JSON.stringify(aggregate[1])}.`);
+        const fieldSource = aggregate[2]?.trim();
+        if (operation !== "count" && !fieldSource) {
+            throw syntax(`${aggregate[1]}() requires a field.`);
+        }
+        return {
+            kind: "aggregate",
+            operation,
+            ...(fieldSource ? { field: parseIdentifier(fieldSource, "aggregate field") } : {}),
+            as: parseIdentifier(aggregate[3], "selection alias"),
+        };
+    }
+    const field = source.match(/^([a-z0-9][a-z0-9._/-]*)(?:\s+as\s+([a-z0-9][a-z0-9._/-]*))?$/i);
+    if (!field)
+        throw syntax(`Unsupported selection ${JSON.stringify(source)}.`);
+    return {
+        kind: "field",
+        field: parseIdentifier(field[1], "selected field"),
+        ...(field[2] ? { as: parseIdentifier(field[2], "selection alias") } : {}),
+    };
+}
+function parseFilter(source) {
+    const nullFilter = source.match(/^([a-z0-9][a-z0-9._/-]*)\s+is\s+(not\s+)?null$/i);
+    if (nullFilter) {
+        return {
+            field: parseIdentifier(nullFilter[1], "filter field"),
+            operator: nullFilter[2] ? "isNotNull" : "isNull",
+        };
+    }
+    const match = source.match(/^([a-z0-9][a-z0-9._/-]*)\s+(not\s+in|in|contains|>=|<=|!=|=|>|<)\s+(.+)$/i);
+    if (!match)
+        throw syntax(`Unsupported filter ${JSON.stringify(source)}.`);
+    const operator = {
+        "=": "equal",
+        "!=": "notEqual",
+        ">": "greaterThan",
+        ">=": "greaterThanOrEqual",
+        "<": "lessThan",
+        "<=": "lessThanOrEqual",
+        in: "in",
+        "not in": "notIn",
+        contains: "contains",
+    };
+    const operatorKey = required(match[2], "filter operator")
+        .toLowerCase()
+        .replace(/\s+/g, " ");
+    return {
+        field: parseIdentifier(match[1], "filter field"),
+        operator: operator[operatorKey],
+        value: parseValueReference(required(match[3], "filter value")),
+    };
+}
+function parseValueReference(source) {
+    const value = source.trim();
+    if (value.startsWith("$")) {
+        return { kind: "parameter", name: parseIdentifier(value.slice(1), "parameter") };
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+        const inner = value.slice(1, -1).trim();
+        const values = inner ? splitList(inner).map(parseLiteral) : [];
+        return { kind: "literal", value: values };
+    }
+    return { kind: "literal", value: parseLiteral(value) };
+}
+function parseLiteral(source) {
+    const value = source.trim();
+    if (/^'.*'$/.test(value) || /^".*"$/.test(value))
+        return value.slice(1, -1);
+    if (/^-?\d+(?:\.\d+)?$/.test(value))
+        return Number(value);
+    if (/^true$/i.test(value))
+        return true;
+    if (/^false$/i.test(value))
+        return false;
+    if (/^null$/i.test(value))
+        return null;
+    throw syntax(`Literal ${JSON.stringify(source)} must be quoted, numeric, boolean, or null.`);
+}
+function parseGroup(source) {
+    const bucket = source.match(/^(day|week|month|quarter|year)\(([a-z0-9][a-z0-9._/-]*)\)$/i);
+    if (bucket) {
+        return {
+            field: parseIdentifier(bucket[2], "group field"),
+            timeGrain: required(bucket[1], "time grain").toLowerCase(),
+        };
+    }
+    return { field: parseIdentifier(source, "group field") };
+}
+function parseOrder(source) {
+    const match = source.match(/^([a-z0-9][a-z0-9._/-]*)(?:\s+(asc|desc))?$/i);
+    if (!match)
+        throw syntax(`Unsupported ordering ${JSON.stringify(source)}.`);
+    return {
+        by: parseIdentifier(match[1], "order field"),
+        direction: match[2]?.toLowerCase() === "desc" ? "descending" : "ascending",
+    };
+}
+function splitList(source) {
+    const values = [];
+    let quote;
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (quote) {
+            if (character === quote && source[index - 1] !== "\\")
+                quote = undefined;
+            continue;
+        }
+        if (character === "'" || character === '"')
+            quote = character;
+        else if (character === "(" || character === "[")
+            depth += 1;
+        else if (character === ")" || character === "]")
+            depth -= 1;
+        else if (character === "," && depth === 0) {
+            values.push(source.slice(start, index).trim());
+            start = index + 1;
+        }
+        if (depth < 0)
+            throw syntax("Unbalanced query delimiters.");
+    }
+    if (quote || depth !== 0)
+        throw syntax("Unbalanced query delimiters.");
+    values.push(source.slice(start).trim());
+    if (values.some((value) => value.length === 0))
+        throw syntax("Query list contains an empty item.");
+    return values;
+}
+function splitAnd(source) {
+    // AND inside quoted literals remains part of the literal.
+    const parts = [];
+    let quote;
+    let start = 0;
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (quote) {
+            if (character === quote && source[index - 1] !== "\\")
+                quote = undefined;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            continue;
+        }
+        if (source.slice(index).match(/^\s+and\s+/i)) {
+            const separator = required(source.slice(index).match(/^\s+and\s+/i)?.[0], "AND separator");
+            parts.push(source.slice(start, index).trim());
+            index += separator.length - 1;
+            start = index + 1;
+        }
+    }
+    parts.push(source.slice(start).trim());
+    return parts;
+}
+function parseIdentifier(value, label) {
+    const parsed = reportingIdentifierSchema.safeParse(value);
+    if (!parsed.success)
+        throw syntax(`Invalid ${label} ${JSON.stringify(value)}.`);
+    return parsed.data;
+}
+function required(value, label) {
+    if (!value)
+        throw syntax(`Missing ${label}.`);
+    return value;
+}
+function syntax(message) {
+    return new ReportQuerySyntaxError(message);
+}

package/dist/query-language.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/query-language.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { parseReportQuery, ReportQuerySyntaxError } from "./query-language.js";
+describe("bounded report query language", () => {
+    it("compiles a single-dataset query with filters, grouping, ordering, and a limit", () => {
+        expect(parseReportQuery(`
+        from bookings
+        where status in ["confirmed", "completed"] and created_at >= $from
+        group by month(created_at)
+        select month as month, count() as bookings, sum(sell_amount) as revenue
+        order by month asc
+        limit 24
+      `)).toEqual({
+            dataset: { id: "bookings" },
+            filters: [
+                {
+                    field: "status",
+                    operator: "in",
+                    value: { kind: "literal", value: ["confirmed", "completed"] },
+                },
+                {
+                    field: "created_at",
+                    operator: "greaterThanOrEqual",
+                    value: { kind: "parameter", name: "from" },
+                },
+            ],
+            groupBy: [{ field: "created_at", timeGrain: "month" }],
+            select: [
+                { kind: "field", field: "month", as: "month" },
+                { kind: "aggregate", operation: "count", as: "bookings" },
+                { kind: "aggregate", operation: "sum", field: "sell_amount", as: "revenue" },
+            ],
+            orderBy: [{ by: "month", direction: "ascending" }],
+            limit: 24,
+        });
+    });
+    it.each([
+        "from bookings join invoices select count() as rows",
+        "delete from bookings",
+        "from bookings select *",
+        "from bookings select count() as rows; drop table bookings",
+        "from (select bookings) select count() as rows",
+        "from bookings select revenue + tax as total",
+    ])("rejects unsupported or unsafe source: %s", (source) => {
+        expect(() => parseReportQuery(source)).toThrow(ReportQuerySyntaxError);
+    });
+});

package/dist/runtime-port.d.ts

@@ -0,0 +1,28 @@
+import type { ReportDatasetDefinition, ReportParameters, ReportQuery, ReportResult, ReportTemplateDefinition, ReportWidgetDefinition } from "./contracts.js";
+export interface ReportDatasetExecutionContext {
+    db: unknown;
+    actorId?: string;
+    grantedScopes: readonly string[];
+    signal?: AbortSignal;
+}
+export interface ReportDatasetExecutionInput {
+    query: ReportQuery;
+    parameters: ReportParameters;
+    maximumRows: number;
+}
+/** Executable half of a manifest-declared dataset. */
+export interface ReportDatasetRuntime {
+    execute(context: ReportDatasetExecutionContext, input: ReportDatasetExecutionInput): Promise<ReportResult> | ReportResult;
+}
+/** Programmatic contribution shape for datasets which do not come from a package manifest. */
+export interface ReportDatasetContribution extends ReportDatasetRuntime {
+    definition: ReportDatasetDefinition;
+}
+/** One module-owned contribution to the reporting catalog. */
+export interface ReportingContributionRuntime {
+    namespace: string;
+    datasets?: readonly ReportDatasetContribution[];
+    widgets?: readonly ReportWidgetDefinition[];
+    templates?: readonly ReportTemplateDefinition[];
+}
+export declare const reportingContributionRuntimePort: import("@voyant-travel/core/project").VoyantPort<ReportingContributionRuntime>;

package/dist/runtime-port.js

@@ -0,0 +1,18 @@
+import { definePort } from "@voyant-travel/core/project";
+export const reportingContributionRuntimePort = definePort({
+    id: "reporting.contribution",
+    test(provider) {
+        if (!provider || typeof provider !== "object") {
+            throw new Error("reporting.contribution provider must be an object.");
+        }
+        const contribution = provider;
+        if (typeof contribution.namespace !== "string" || contribution.namespace.length === 0) {
+            throw new Error("reporting.contribution provider must declare a namespace.");
+        }
+        for (const dataset of contribution.datasets ?? []) {
+            if (!dataset || typeof dataset !== "object" || typeof dataset.execute !== "function") {
+                throw new Error("reporting.contribution datasets must implement execute().");
+            }
+        }
+    },
+});