@agile-team/mach-report 2.16.0 → 2.18.0

package/dist/index.d.cts

@@ -10,6 +10,14 @@ declare interface AggregateDefinition {
 
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 /** 复制发生变化的页/组件/行；原计划保持不变，并拒绝覆盖已改变的单元格。 */
 export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEdit): RenderPlan;
 
@@ -29,6 +37,8 @@ export declare function assertRenderPlan(input: unknown): PlanPage[];
 
 export declare function assertReportParams(defs: readonly ReportParamDef[], input?: Record<string, unknown>): Record<string, string>;
 
+export declare function assertReportValidation(issues: readonly ReportValidationIssue[], warningPolicy?: "allow" | "block"): void;
+
 export declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -42,6 +52,8 @@ export declare interface AssetRenderBudget {
 
 export declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
     assetFailure?: "throw" | "placeholder";
@@ -162,6 +174,36 @@ export declare type ColumnFormat = {
 /** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
 export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
 
+export declare type ColumnVisual = {
+    /** Defaults to the column field; never changes the cell's raw value or business identity. */
+    field?: string;
+    /** Numeric text requires explicit opt-in; formatting an identifier does not turn it into a measure. */
+    numeric?: "number" | "decimal";
+    min?: number;
+    max?: number;
+} & ({
+    kind: "colorScale";
+    lowColor?: string;
+    highColor?: string;
+} | {
+    kind: "dataBar";
+    color?: string;
+    negativeColor?: string;
+});
+
+/** Stable-key comparison of business data or instance snapshots. Never compares report coordinates. */
+export declare function compareReportData(before: ReportDataSnapshot, after: ReportDataSnapshot, options: ReportDataComparisonOptions): ReportDataComparison;
+
+/** Bounded declarative conditions shared by visibility, styles, IF and candidate validation. */
+export declare function compileReportPredicate(predicate: ReportPredicate, budget?: {
+    nodes: number;
+}, depth?: number): ReportPredicateReader;
+
+export declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 export declare interface ComponentBinding {
     field: string;
@@ -265,6 +307,16 @@ export declare function createLocalTemplateCatalog(input: LocalTemplateCatalogIt
 /** 单进程参考适配器；多实例服务请实现具备数据库事务/CAS 的持久化适配器。 */
 export declare function createMemoryTemplateStore(): ReportTemplateStore;
 
+/** Owned preview controller; only mounted grids are windowed. Static renderPage and exports stay complete. */
+export declare function createPageViewportRenderer(page: PlanPage, dpi: number, options: RenderOptions, doc: Document): {
+    element: HTMLElement;
+    update(viewport: ReportViewport, retained?: {
+        componentIndex: number;
+        rowIndex: number;
+        columnIndex: number;
+    }): boolean;
+};
+
 export declare function createProviderReport(definition: Omit<ReportDefinition, "load" | "datasets"> & {
     provider: ReportProvider;
 }): ReportDefinition;
@@ -278,6 +330,12 @@ export declare function createReportCellEditBatch(plan: RenderPlan, inputs: read
 /** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
 export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
 
+/** One bounded scan, shared aggregate semantics; labels never coerce identifier source values. */
+export declare function createReportChartData(rows: readonly Record<string, unknown>[], binding: ReportChartBinding, signal?: AbortSignal): ReportChartData;
+
+/** Explicit per-host registry. Templates contain bounded JSON bindings; loaders never come from a template. */
+export declare function createReportComponentRegistry(definitions: readonly ReportComponentExtensionDefinition[]): ReportComponentRegistry;
+
 /** Revalidates the current cell on activation; returns only bounded scalar values and explicit return state. */
 export declare function createReportDrillRequest(plan: RenderPlan, address: ReportCellAddress, action: ReportDrillAction, params?: Readonly<Record<string, string>>): ReportDrillRequest;
 
@@ -288,6 +346,9 @@ export declare function createReportEditSession(options: {
     pagination?: PaginateOptions;
 }): ReportEditSession;
 
+/** Explicit field allowlist + stable business keys. Does not mutate, persist or replace a workbook. */
+export declare function createReportPrefill(plan: RenderPlan, options: ReportPrefillOptions): ReportPrefillPreview;
+
 /**
  * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
  * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
@@ -297,6 +358,7 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
     onDatasets?: (reportId: string, datasets: DatasetRows, template: ReportTemplate) => void;
     maxPages?: number;
     maxCells?: number;
+    maxChartComponents?: number;
 }): ReportSource;
 
 /**
@@ -310,6 +372,8 @@ export declare function createTemplate(): TemplateBuilder;
 /** 持久化和框架无关的发布流程；历史返回快照，回滚会产生新修订而不会覆盖旧历史。 */
 export declare function createTemplateManager(store: ReportTemplateStore, options?: {
     migrate?: (input: unknown) => unknown | Promise<unknown>;
+    /** Explicit schema chain, applied to saved drafts and loaded/rolled-back documents. Legacy migrate remains save-only. */
+    migrations?: readonly ReportTemplateMigration[];
     now?: () => Date;
     /** Optional publication gate; receives explicit draft snapshots and never replaces CAS. */
     beforePublish?: (context: {
@@ -319,6 +383,9 @@ export declare function createTemplateManager(store: ReportTemplateStore, option
     }) => ReportTemplateReview | Promise<ReportTemplateReview>;
 }): ReportTemplateManager;
 
+/** Explicit, bounded migration chain. Unknown/future versions are never silently downgraded. */
+export declare function createTemplateMigrator(steps?: readonly ReportTemplateMigration[]): (input: unknown) => Promise<ReportTemplateMigrationResult>;
+
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
 export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
 
@@ -409,6 +476,11 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** A tiny arithmetic parser: no functions, property access, globals, assignments or executable source. */
 export declare function evaluateReportAggregateExpression(expression: string, values: Readonly<Record<string, number>>): number;
 
+export declare function evaluateReportPredicate(row: Readonly<Record<string, unknown>>, predicate: ReportPredicate): boolean;
+
+/** Derives locatable explanations only from explicit business declarations; never evaluates formulas. */
+export declare function explainDatasetField(contract: DatasetContract, target: ReportDataTarget): ReportDiagnostic[];
+
 declare interface ExpressionOptions {
     numeric?: "number" | "decimal";
     digits?: number;
@@ -416,6 +488,8 @@ declare interface ExpressionOptions {
     divisionByZero?: "null" | "error";
 }
 
+export declare function formatReportCascaderPath(value: readonly string[]): string;
+
 /** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
 export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
 
@@ -424,6 +498,10 @@ export declare function formatReportClipboard(rows: readonly (readonly string[])
 
 export declare function formatReportDateRange(range: ReportDateRange): string;
 
+export declare function formatReportNumberRange(value: ReportNumberRange): string;
+
+export declare function formatReportParamSelection(value: readonly string[]): string;
+
 /**
  * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
  * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
@@ -448,6 +526,12 @@ export declare function getReportCellContext(plan: RenderPlan, address: ReportCe
 export declare function getReportEditSession(plan: RenderPlan): ReportEditSession | undefined;
 
 export declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -660,6 +744,8 @@ export declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -779,6 +865,26 @@ export declare interface LocalTemplateCatalogItem {
 /** O(action count), no row scans or listeners per cell; invoke for the focused cell only. */
 export declare function matchReportDrillActions(plan: RenderPlan, address: ReportCellAddress, actions: readonly ReportDrillAction[]): ReportDrillAction[];
 
+declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+
+declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+
+declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -793,6 +899,10 @@ declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 
 export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
@@ -827,6 +937,11 @@ export declare interface OutputDiagnostic {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 
@@ -898,6 +1013,13 @@ export declare class PaginateCellLimitError extends Error {
     constructor(limit: number, actual: number);
 }
 
+export declare class PaginateChartComponentLimitError extends Error {
+    readonly limit: number;
+    readonly estimated: number;
+    readonly code = "chart-component-limit";
+    constructor(limit: number, estimated: number);
+}
+
 export declare interface PaginateOptions {
     /** 每行额外占高（mm），压测专用钩子 */
     mmPerRow?: number;
@@ -907,6 +1029,8 @@ export declare interface PaginateOptions {
     maxPages?: number;
     /** Actual grid cells, including repeated furniture and nested children; checked before each page is appended. */
     maxCells?: number;
+    /** Shared bound-chart primitive budget, checked before expansion; default 50000, range 1..1000000. */
+    maxChartComponents?: number;
     signal?: AbortSignal;
     /** Streaming total-page anchors can skip the bounded counting pass when known. */
     knownTotalPages?: number;
@@ -925,6 +1049,8 @@ export declare class PaginatePageLimitError extends Error {
 export declare interface PaginateResult {
     plan: RenderPlan;
     warnings: string[];
+    /** Actual resolved bound-chart primitives, including empty placeholders. */
+    chartComponents: number;
 }
 
 /** Compatibility collector: the pagination engine is shared with the bounded page iterator. */
@@ -944,6 +1070,8 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+export declare function parseReportCascaderPath(value: unknown): string[] | undefined;
+
 /** Core type parsing is authoritative; field controls add restrictions, never coerce IDs or bypass readonly. */
 export declare function parseReportCellFieldInput(context: ReportCellContext, input: ReportCellValue, field?: ReportCellFieldOptions): ReportCellValue;
 
@@ -956,10 +1084,16 @@ export declare function parseReportClipboard(text: string, maxCells?: number): s
 /** Only complete, ordered, real calendar dates are accepted; there is no timezone conversion. */
 export declare function parseReportDateRange(value: string): ReportDateRange | undefined;
 
+export declare function parseReportNumberRange(value: unknown): ReportNumberRange | undefined;
+
+export declare function parseReportParamSelection(value: unknown): string[] | undefined;
+
 /** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
 export declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -1111,6 +1245,11 @@ export declare interface ReportCalculationSelection {
     focus: ReportCellAddress;
 }
 
+export declare interface ReportCandidateValidationOptions extends Pick<ReportDatasetValidationOptions, "rules" | "maxChecks" | "maxIssues"> {
+    /** Warnings are visible and allowed by default; block explicitly when required by business policy. */
+    warningPolicy?: "allow" | "block";
+}
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 export declare interface ReportCellAddress {
     pageIndex: number;
@@ -1225,6 +1364,209 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+export declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+export declare interface ReportChartData {
+    categories: string[];
+    series: ReportChartSeries[];
+}
+
+export declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+
+export declare interface ReportComparison {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar;
+    right?: ReportPredicateOperand;
+    values?: readonly [ReportPredicateScalar, ReportPredicateScalar];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+
+export declare interface ReportComponentExtensionBinding {
+    id: string;
+    version: string;
+    props: Readonly<Record<string, ReportComponentValue>>;
+    /** Host-defined JSON only: core does not execute queries, scripts or property paths in this binding. */
+    binding?: ReportComponentJson;
+}
+
+export declare interface ReportComponentExtensionContext extends ComponentImageContext {
+    readonly extension: Readonly<ReportComponentExtensionBinding>;
+}
+
+export declare interface ReportComponentExtensionDefinition extends ReportComponentExtensionMetadata {
+    /** Trusted runtime loader, never read from template JSON or a remote import URL. */
+    load(signal: AbortSignal): ReportComponentExtensionRenderer | Promise<ReportComponentExtensionRenderer>;
+}
+
+export declare class ReportComponentExtensionError extends Error {
+    readonly code: "definition" | "binding" | "load" | "disposed";
+    readonly path: string;
+    readonly extensionId?: string | undefined;
+    constructor(code: "definition" | "binding" | "load" | "disposed", message: string, path?: string, extensionId?: string | undefined);
+}
+
+export declare interface ReportComponentExtensionMetadata {
+    id: string;
+    version: string;
+    kind: ImageComponentKind;
+    label: string;
+    description?: string;
+    properties?: Readonly<Record<string, ReportComponentProperty>>;
+}
+
+export declare interface ReportComponentExtensionRenderer {
+    render(context: ReportComponentExtensionContext): string | Promise<string>;
+    dispose?(): void | Promise<void>;
+}
+
+export declare type ReportComponentJson = ReportComponentValue | readonly ReportComponentJson[] | {
+    readonly [key: string]: ReportComponentJson;
+};
+
+export declare interface ReportComponentProperty {
+    label: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    default?: ReportComponentValue;
+    options?: readonly ReportComponentValue[];
+    min?: number;
+    max?: number;
+    maxLength?: number;
+}
+
+export declare interface ReportComponentRegistry extends ComponentAssetRegistry {
+    /** Pass directly as Preview/Runtime assets; no component-specific adapter wiring is needed. */
+    readonly assets: Readonly<Pick<AssetRenderOptions, "assetRegistry">>;
+    describe(kind?: ImageComponentKind): readonly Readonly<ReportComponentExtensionMetadata>[];
+    /** Add native geometry and insert into the existing template/canvas command path. */
+    createComponent(id: string, values?: {
+        props?: Readonly<Record<string, ReportComponentValue>>;
+        binding?: ReportComponentJson;
+    }): Pick<PlanComponent, "kind" | "meta">;
+    /** Idempotent. Abort active consumers, release loaded renderers, and release a late loader when it finishes. */
+    dispose(): Promise<void>;
+}
+
+export declare type ReportComponentValue = string | number | boolean | null;
+
+export declare interface ReportDataComparison {
+    sourceScope?: string;
+    datasetId: string;
+    differences: readonly ReportDataDifference[];
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+        cells: number;
+    };
+}
+
+export declare interface ReportDataComparisonField {
+    field: string;
+    label?: string;
+    /** Numeric comparison is explicit; identifiers containing digits stay text. */
+    type?: "value" | "decimal";
+    /** Absolute decimal tolerance, inclusive. No binary floating-point subtraction. */
+    tolerance?: string;
+    /** Fractional ratio digits. changeRatio is (after - before) / before, not a percent. */
+    ratioDigits?: number;
+    zeroDenominator?: "omit" | "zero-if-equal";
+    missing?: "distinct" | "empty-equivalent" | "zero";
+}
+
+export declare interface ReportDataComparisonOptions extends ReportDataLimits {
+    fields: readonly ReportDataComparisonField[];
+    maxDifferences?: number;
+}
+
+export declare interface ReportDataDifference {
+    rowKey: string | number;
+    kind: "added" | "removed" | "changed";
+    field: string;
+    label: string;
+    before: ReportCellValue | undefined;
+    after: ReportCellValue | undefined;
+    /** Exact base-ten difference. Undefined when either input is missing/non-numeric. */
+    delta?: string;
+    changeRatio?: string;
+    ratioUnavailable?: "zero-denominator" | "missing";
+}
+
+export declare class ReportDataError extends Error {
+    readonly code: "identity" | "duplicate" | "limit" | "value" | "conflict";
+    constructor(code: "identity" | "duplicate" | "limit" | "value" | "conflict", message: string);
+}
+
+export declare interface ReportDataLimits {
+    maxRows?: number;
+    maxFields?: number;
+    maxCells?: number;
+}
+
+/** A business record, never a physical report row index. */
+export declare interface ReportDataRecord {
+    rowKey: string | number;
+    values: Readonly<Record<string, ReportCellValue>>;
+}
+
+export declare interface ReportDatasetValidationOptions {
+    rules: readonly ReportValidationRule[];
+    rowKey?: string;
+    computed?: readonly ComputedField[];
+    /** Explicit trusted engine, shared with pagination; never read from a serialized template. */
+    formula?: FormulaAdapter;
+    /** Uses the same bounded tree preparation and descendant-leaf summaries as pagination. */
+    tree?: TreeTableOptions;
+    maxChecks?: number;
+    maxIssues?: number;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportDataSnapshot {
+    sourceScope?: string;
+    datasetId: string;
+    rows: readonly ReportDataRecord[];
+}
+
+/** Extracts explicit fields from the same rendered query; never makes a second business request. */
+export declare function reportDataSnapshotFromPlan(plan: RenderPlan, options: ReportPlanDataOptions): ReportDataSnapshot;
+
 export declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -1235,6 +1577,17 @@ export declare interface ReportDataTarget {
     reportScope?: string;
 }
 
+/** Resolve a business calendar default once per request; returns only a portable date value. */
+export declare function reportDateDefault(options: ReportDateDefaultOptions): string;
+
+export declare interface ReportDateDefaultOptions {
+    preset: "today" | "yesterday" | "month-start" | "month-end";
+    /** Explicit business clock in milliseconds or Date; no hidden browser/server clock. */
+    now: number | Date;
+    timeZone: string;
+    offsetDays?: number;
+}
+
 /** Wire values deliberately remain strings in browsers, Workers and backend runtimes. */
 export declare interface ReportDateRange {
     start: string;
@@ -1337,6 +1690,7 @@ export declare interface ReportEditConflict {
 
 export declare interface ReportEditPreparationOptions {
     signal?: AbortSignal;
+    validation?: ReportCandidateValidationOptions;
 }
 
 export declare interface ReportEditResult {
@@ -1361,6 +1715,8 @@ declare interface ReportEditSessionPart {
 
 export declare interface ReportEditSessionRegistration {
     parts: readonly ReportEditSessionPart[];
+    /** Trusted runtime adapters stay outside the serializable guarded source snapshot. */
+    validationFormulas?: readonly (FormulaAdapter | undefined)[];
     rebuild(parts: readonly ReportEditSessionPart[], signal?: AbortSignal): Promise<RenderPlan>;
 }
 
@@ -1373,10 +1729,14 @@ declare type ReportExpression = {
     field?: string;
     weightField?: string;
 } | {
-    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    op: ReportExpressionOperation;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate;
     args: readonly ReportExpression[];
 };
 
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 export declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1393,7 +1753,15 @@ export declare interface ReportFetchInput extends ReportTaskMonitoring {
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 
-export declare interface ReportFieldContract {
+export declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+
+export declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+
+export declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1408,6 +1776,17 @@ export declare interface ReportFieldContract {
     unit?: string;
 }
 
+export declare interface ReportFieldSemantics {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation;
+}
+
 export declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -1429,6 +1808,8 @@ export declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+export declare type ReportNumberRange = readonly [number, number];
+
 export declare function reportOutputDiagnostics(plan: RenderPlan, format: OutputFormat, options: OutputDiagnosticOptions): OutputDiagnostic[];
 
 export declare interface ReportPageFlow {
@@ -1441,12 +1822,9 @@ export declare interface ReportParamDef {
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
     optionsSource?: string;
     /** Select dependencies must be declared parameters; changing a parent clears descendants. */
@@ -1459,6 +1837,9 @@ export declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 
 export declare interface ReportParamIssue {
@@ -1468,17 +1849,26 @@ export declare interface ReportParamIssue {
     message: string;
 }
 
-export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
+export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength" | "minItems" | "maxItems";
 
 /** 描述 typedValues 的 Draft 2020-12 Schema；日期区间额外保留 x-report-* 扩展。 */
 export declare function reportParamsJsonSchema(defs: readonly ReportParamDef[]): Record<string, unknown>;
 
+/** Cascader values are unique within each sibling list. */
+export declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+export declare type ReportParamTypedValue = string | number | string[] | ReportNumberRange;
+
 export declare interface ReportParamValidation {
     ok: boolean;
     /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
     values: Record<string, string>;
     /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
-    typedValues: Record<string, string | number>;
+    typedValues: Record<string, ReportParamTypedValue>;
     issues: ReportParamIssue[];
 }
 
@@ -1488,9 +1878,80 @@ export declare class ReportParamValidationError extends Error {
     constructor(issues: readonly ReportParamIssue[]);
 }
 
+export declare interface ReportPlanDataOptions extends ReportDataLimits {
+    sourceScope?: string;
+    datasetId: string;
+    fields: readonly string[];
+}
+
+export declare type ReportPredicate = ReportComparison | {
+    all: readonly ReportPredicate[];
+} | {
+    any: readonly ReportPredicate[];
+} | {
+    not: ReportPredicate;
+};
+
+export declare function reportPredicateFields(predicate: ReportPredicate): string[];
+
+export declare type ReportPredicateOperand = {
+    field: string;
+} | {
+    value: ReportPredicateScalar;
+};
+
+export declare type ReportPredicateReader = (row: Readonly<Record<string, unknown>>) => boolean;
+
+export declare type ReportPredicateScalar = string | number | boolean | null;
+
+export declare interface ReportPrefillField {
+    field: string;
+    sourceField?: string;
+    label?: string;
+}
+
+/** Re-resolve coordinates after reflow; any changed value/token rejects the complete application. */
+export declare function reportPrefillInputs(plan: RenderPlan, preview: ReportPrefillPreview, canEdit?: (context: ReportCellContext) => boolean): ReportCellInput[];
+
+export declare interface ReportPrefillItem {
+    source: Readonly<ReportCellSource>;
+    label: string;
+    status: ReportPrefillStatus;
+    reason?: ReportPrefillReason;
+    before?: ReportCellValue;
+    after?: ReportCellValue;
+}
+
+export declare interface ReportPrefillOptions extends ReportDataLimits {
+    sourceScope?: string;
+    datasetId: string;
+    fields: readonly ReportPrefillField[];
+    rows: readonly ReportDataRecord[];
+    /** Default: fill only null/empty string. Existing zero, false and whitespace are data. */
+    mode?: "empty" | "replace";
+    maxChanges?: number;
+    canEdit?(context: ReportCellContext): boolean;
+}
+
+export declare interface ReportPrefillPreview {
+    sourceScope?: string;
+    datasetId: string;
+    items: readonly ReportPrefillItem[];
+    counts: Readonly<Record<ReportPrefillStatus, number>>;
+    /** Optimistic source tokens and previous values are retained for an atomic edit. */
+    edits: readonly ReportCellEdit[];
+}
+
+export declare type ReportPrefillReason = "unchanged" | "readonly" | "occupied" | "missing-source" | "missing-target" | "ambiguous" | "invalid";
+
+export declare type ReportPrefillStatus = "matched" | "changed" | "skipped" | "conflict";
+
 export declare interface ReportPreparedEdit {
     /** Calculated preview; no source/session state changes until commit succeeds. */
     readonly plan: RenderPlan;
+    readonly validationIssues: readonly ReportValidationIssue[];
+    /** Validate complete candidate source rows and derived fields before invoking persistence. */
+    validate(options: ReportCandidateValidationOptions): readonly ReportValidationIssue[];
     /** Call after persistence. A stale or repeated commit fails instead of publishing mixed state. */
     commit(result?: void | ReportEditResult): RenderPlan;
 }
@@ -1703,6 +2164,26 @@ export declare interface ReportTemplateManager {
     rollback(id: string, revision: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
 }
 
+export declare interface ReportTemplateMigration {
+    from: string;
+    to: string;
+    /** Pure document transformation; business data, credentials and I/O belong to the host. */
+    migrate(input: Readonly<Record<string, unknown>>): unknown | Promise<unknown>;
+}
+
+export declare class ReportTemplateMigrationError extends Error {
+    readonly code: "definition" | "unsupported" | "result";
+    constructor(code: "definition" | "unsupported" | "result", message: string);
+}
+
+export declare interface ReportTemplateMigrationResult {
+    document: ReportTemplateDocument;
+    steps: readonly {
+        from: string;
+        to: string;
+    }[];
+}
+
 export declare interface ReportTemplateProvider {
     list(context: {
         signal?: AbortSignal;
@@ -1818,9 +2299,47 @@ export declare interface ReportTemplateVersion {
     restoredFrom?: string;
 }
 
+export declare class ReportValidationError extends Error {
+    readonly issues: readonly ReportValidationIssue[];
+    constructor(issues: readonly ReportValidationIssue[]);
+}
+
+export declare interface ReportValidationIssue {
+    ruleId: string;
+    rowKey?: string | number;
+    rowIndex?: number;
+    field?: string;
+    dataset?: string;
+    sourceScope?: string;
+    severity: "error" | "warning";
+    message: string;
+}
+
+export declare interface ReportValidationRule {
+    id: string;
+    /** Optional target; omitted applies to each candidate dataset. */
+    dataset?: string;
+    assert: ReportPredicate;
+    when?: ReportPredicate;
+    field?: string;
+    severity?: "error" | "warning";
+    message: string;
+    scope?: "row" | "dataset";
+    /** Dataset-scope assertions read this explicit summary row, never an arbitrary detail row. */
+    aggregates?: readonly AggregateDefinition[];
+}
+
 /** Optional business explanations never replace raw data or schema validation. */
 export declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 
+/** Preview coordinates only. Output plans and their complete geometry remain unchanged. */
+export declare interface ReportViewport {
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+}
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
@@ -1921,13 +2440,7 @@ export declare function serializeReportTemplate(document: ReportTemplateDocument
 
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 export declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-        /** Explicit decimal comparisons retain decimal thresholds as text. */
-        numeric?: "number" | "decimal";
-    };
+    when: ReportPredicate;
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
 }
@@ -2151,6 +2664,11 @@ export declare function validateRenderPlan(input: unknown): ValidationResult;
 /** Check configuration before opening an input, including JSON/JavaScript callers. */
 export declare function validateReportCellFieldDefinition(context: ReportCellContext, field: ReportCellFieldOptions): void;
 
+export declare function validateReportChartBinding(binding: ReportChartBinding): void;
+
+/** Pure candidate validation shared by browsers and Node; checks the complete proposed dataset before persistence. */
+export declare function validateReportDataset(input: readonly Record<string, unknown>[], options: ReportDatasetValidationOptions): ReportValidationIssue[];
+
 export declare function validateReportDrillActions(actions: readonly ReportDrillAction[]): void;
 
 /** 模板参数配置错误也统一返回结构化问题，不让无效默认值或边界静默进入后端。 */