@agile-team/mach-report 2.10.0 → 2.11.0

package/dist/server.d.cts

@@ -10,6 +10,8 @@ declare interface AggregateDefinition {
 
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+export declare function checkInstanceIdentity(scope: string, id: string): void;
+
 export declare function checkJobIdentity(scope: string, id: string): void;
 
 export declare function cloneJob<T>(value: T): T;
@@ -73,9 +75,42 @@ declare interface ComputedField extends ExpressionOptions {
     dependsOn?: readonly string[];
 }
 
+/** Bounded reference store for tests/local sessions. Production hosts implement durable transactional CAS. */
+export declare function createMemoryReportInstanceStore(options?: MemoryReportInstanceStoreOptions): ReportInstanceStore;
+
 /** Reference store for tests; use a database CAS or the single-process durable Node adapter in production. */
 export declare function createMemoryReportJobStore(options?: ReportJobStoreBudgetOptions): ReportJobStore;
 
+/** Bind immutable template revisions to the same runtime registration. Rebuild the service on publication. */
+export declare function createReportGenerationService(options: {
+    runtime: ReportRuntime;
+    instances: ReportInstanceStore;
+    templateRevisions: Record<string, string>;
+    maxSnapshotBytes?: number;
+    now?: () => Date;
+}): {
+    generate(input: ReportGenerationInput): Promise<ReportInstanceSnapshot>;
+    read: (scope: string, id: string, revision?: number, signal?: AbortSignal) => Promise<ReportInstanceSnapshot | undefined>;
+    list: (scope: string, options?: ReportInstanceListOptions) => Promise<ReportInstancePage>;
+    /** Instance edits are explicit snapshots; source business persistence remains the Provider.save responsibility. */
+    save: (input: Omit<ReportInstanceSnapshot, "revision">, options: {
+        expectedRevision: number | null;
+        signal?: AbortSignal;
+    }) => Promise<ReportInstanceSnapshot>;
+};
+
+/** Save is explicit. A preview/query never calls this manager or overwrites a prior instance. */
+export declare function createReportInstanceManager(store: ReportInstanceStore, options?: {
+    maxSnapshotBytes?: number;
+}): {
+    read: (scope: string, id: string, revision?: number, signal?: AbortSignal) => Promise<ReportInstanceSnapshot | undefined>;
+    list: (scope: string, options?: ReportInstanceListOptions) => Promise<ReportInstancePage>;
+    save: (input: Omit<ReportInstanceSnapshot, "revision">, options: {
+        expectedRevision: number | null;
+        signal?: AbortSignal;
+    }) => Promise<ReportInstanceSnapshot>;
+};
+
 /** Durable at-least-once dispatch; export/artifact handlers must be idempotent by scope+taskId. */
 export declare function createReportJobService(options: ReportJobServiceOptions): ReportJobService;
 
@@ -125,6 +160,8 @@ declare interface GridCell {
     value?: string | number | boolean | null;
     /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
     numberFormat?: string;
+    /** Physical left inset for hierarchical labels; raw value stays unchanged. */
+    indentMm?: number;
     /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
@@ -171,6 +208,8 @@ declare interface ListColumn {
 
 declare interface ListComponent {
     kind: "list";
+    /** Opaque serializable layout annotations; interpreted only by explicit optional adapters. */
+    meta?: Record<string, unknown>;
     id?: string;
     /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
     layout?: "page" | "wide";
@@ -180,6 +219,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** Headerless record/region bindings do not allocate a synthetic list header. */
+    header?: boolean;
+    /** A fixed record region rejects multiple rows instead of dropping source data. */
+    cardinality?: "record";
     /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
     rowKey?: string;
     revisionField?: string;
@@ -206,6 +249,8 @@ declare interface ListComponent {
     computed?: ComputedField[];
     /** Dynamic pivot of the current source dataset, with read-only derived identities. */
     matrix?: MatrixTableOptions;
+    /** Full ordered hierarchy; source parent values and descendant-leaf rollups are explicit. */
+    tree?: TreeTableOptions;
     /** Explicit row visibility; hidden rows do not participate in summaries. */
     rowVisibleWhen?: StyleRule["when"];
     /** Master/detail relation is keyed by business identity, never by display row index. */
@@ -272,6 +317,13 @@ declare interface MatrixTableOptions {
     maxCells?: number;
 }
 
+export declare interface MemoryReportInstanceStoreOptions {
+    maxInstances?: number;
+    maxRevisions?: number;
+    maxBytes?: number;
+    maxSnapshotBytes?: number;
+}
+
 declare interface OutputDiagnostic {
     code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
     severity: "warning";
@@ -340,6 +392,7 @@ declare interface PlanGrid {
 }
 
 declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -385,6 +438,43 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+export declare interface ReportBatchCase {
+    id: string;
+    params: Record<string, string>;
+}
+
+export declare interface ReportBatchOptions {
+    concurrency?: number;
+    maxCases?: number;
+    signal?: AbortSignal;
+    /** Stop launching new cases after the first failure; already running cases finish. */
+    failure?: "continue" | "stop";
+    onProgress?: (progress: ReportBatchProgress) => void;
+}
+
+export declare type ReportBatchOutcome<T> = {
+    id: string;
+    index: number;
+} & ({
+    status: "completed";
+    value: T;
+} | {
+    status: "failed";
+    error: {
+        name: string;
+        message: string;
+    };
+} | {
+    status: "cancelled";
+});
+
+export declare interface ReportBatchProgress {
+    completed: number;
+    total: number;
+    failed: number;
+    cancelled: number;
+}
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 declare interface ReportCellAddress {
     pageIndex: number;
@@ -486,6 +576,78 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+declare interface ReportFlowBand {
+    /** Exact stable component IDs. Static components use nid, lists use id. */
+    componentIds: string[];
+    /** Source-template coordinates; following bands keep their original gap. */
+    topMm: number;
+    heightMm: number;
+}
+
+export declare interface ReportGenerationInput {
+    scope: string;
+    id: string;
+    title: string;
+    reportIds: string[];
+    params?: Record<string, string>;
+    expectedRevision: number | null;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportInstanceArtifact {
+    key: string;
+    format: "pdf" | "xlsx";
+    bytes: number;
+    sha256?: string;
+}
+
+export declare class ReportInstanceError extends Error {
+    readonly code: "input" | "conflict" | "capacity";
+    constructor(code: "input" | "conflict" | "capacity", message: string);
+}
+
+export declare interface ReportInstanceListOptions {
+    after?: string;
+    limit?: number;
+    reportId?: string;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportInstancePage {
+    items: ReportInstanceSummary[];
+    next?: string;
+}
+
+/** Stable parameter identity without adding a database, user account or credential to the SDK. */
+export declare function reportInstanceParameterKey(reportIds: string[], params: Record<string, string>): string;
+
+export declare interface ReportInstanceSnapshot {
+    scope: string;
+    id: string;
+    revision: number;
+    title: string;
+    generatedAt: string;
+    reportIds: string[];
+    params: Record<string, string>;
+    /** Exact template/data revisions used by generation, never inferred from a later template read. */
+    templateRevisions: Record<string, string>;
+    sourceRevisions: Record<string, string>;
+    plan: RenderPlan;
+    /** Private storage keys; signed download URLs must be generated by the host after authorization. */
+    artifacts?: ReportInstanceArtifact[];
+}
+
+export declare interface ReportInstanceStore {
+    read(scope: string, id: string, revision?: number, signal?: AbortSignal): Promise<ReportInstanceSnapshot | undefined>;
+    list(scope: string, options?: ReportInstanceListOptions): Promise<ReportInstancePage>;
+    /** Atomic append + current-revision advance. Historical revisions must never be overwritten. */
+    compareAndSwap(scope: string, id: string, expectedRevision: number | null, next: ReportInstanceSnapshot, signal?: AbortSignal): Promise<boolean>;
+}
+
+export declare type ReportInstanceSummary = Omit<ReportInstanceSnapshot, "plan" | "artifacts">;
+
+export declare function reportInstanceSummary(snapshot: ReportInstanceSnapshot): ReportInstanceSummary;
+
 export declare class ReportJobError extends Error {
     readonly code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity";
     constructor(code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity", message: string);
@@ -616,13 +778,17 @@ declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+declare interface ReportPageFlow {
+    bands: ReportFlowBand[];
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
     /** select 选项 */
     options?: Array<{
         label: string;
@@ -631,7 +797,7 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    /** 数字上下界；日期/月/年使用对应规范字符串；dateRange 对两端使用 YYYY-MM-DD 边界（含边界）。 */
     min?: number | string;
     max?: number | string;
     minLength?: number;
@@ -968,12 +1134,22 @@ declare interface RichSegment {
 
 export declare function runnableJob(record: ReportJobRecord, now: number): boolean;
 
+/** Browser/Node shared bounded runner. Return small receipts; persist/export large artifacts inside execute. */
+export declare function runReportBatch<T>(input: readonly ReportBatchCase[], execute: (item: ReportBatchCase, context: {
+    index: number;
+    signal: AbortSignal;
+}) => Promise<T>, options?: ReportBatchOptions): Promise<ReportBatchOutcome<T>[]>;
+
 /** Canonical plain JSON rejects getters/scripts and gives stable idempotency without coercion. */
 export declare function serializeJobJson(value: unknown, budget?: {
     maxNodes?: number;
     maxCharacters?: number;
 }): string;
 
+export declare function snapshotReportBatchCases(input: readonly ReportBatchCase[], maximum?: number): ReportBatchCase[];
+
+export declare function snapshotReportInstance(value: ReportInstanceSnapshot, maxBytes?: number): ReportInstanceSnapshot;
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
     when: {
@@ -999,6 +1175,9 @@ declare interface TemplatePage {
     marginLeftMm?: number;
     marginRightMm?: number;
     components: TemplateComponent[];
+    /** Explicit vertical bands preserve source gaps as dynamic regions expand. */
+    flow?: ReportPageFlow;
+    meta?: Record<string, unknown>;
 }
 
 /**
@@ -1021,6 +1200,26 @@ declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** A serialized tree contract. Sibling and root order follow input order. */
+declare interface TreeTableOptions {
+    input: "flat" | "nested";
+    idField: string;
+    /** Flat roots have null/undefined parent values. */
+    parentField?: string;
+    /** Nested child arrays, defaults to children. Every node still needs an ID. */
+    childrenField?: string;
+    labelField: string;
+    indentMm?: number;
+    orphan?: "error" | "root";
+    /** Source preserves parent values; leaf-aggregate derives only parents from descendant leaves. */
+    parentValues?: "source" | "leaf-aggregate";
+    aggregates?: AggregateDefinition[];
+    maxRows?: number;
+    maxDepth?: number;
+    /** Bounded leaf-to-ancestor aggregate work; default one million. */
+    maxAggregationVisits?: number;
+}
+
 export declare function validateJobRecord(record: ReportJobRecord, scope: string, id: string, expectedRevision: number | null): void;
 
 export declare function validateJobTransition(previous: ReportJobRecord | undefined, next: ReportJobRecord): void;

package/dist/server.d.ts

@@ -10,6 +10,8 @@ declare interface AggregateDefinition {
 
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+export declare function checkInstanceIdentity(scope: string, id: string): void;
+
 export declare function checkJobIdentity(scope: string, id: string): void;
 
 export declare function cloneJob<T>(value: T): T;
@@ -73,9 +75,42 @@ declare interface ComputedField extends ExpressionOptions {
     dependsOn?: readonly string[];
 }
 
+/** Bounded reference store for tests/local sessions. Production hosts implement durable transactional CAS. */
+export declare function createMemoryReportInstanceStore(options?: MemoryReportInstanceStoreOptions): ReportInstanceStore;
+
 /** Reference store for tests; use a database CAS or the single-process durable Node adapter in production. */
 export declare function createMemoryReportJobStore(options?: ReportJobStoreBudgetOptions): ReportJobStore;
 
+/** Bind immutable template revisions to the same runtime registration. Rebuild the service on publication. */
+export declare function createReportGenerationService(options: {
+    runtime: ReportRuntime;
+    instances: ReportInstanceStore;
+    templateRevisions: Record<string, string>;
+    maxSnapshotBytes?: number;
+    now?: () => Date;
+}): {
+    generate(input: ReportGenerationInput): Promise<ReportInstanceSnapshot>;
+    read: (scope: string, id: string, revision?: number, signal?: AbortSignal) => Promise<ReportInstanceSnapshot | undefined>;
+    list: (scope: string, options?: ReportInstanceListOptions) => Promise<ReportInstancePage>;
+    /** Instance edits are explicit snapshots; source business persistence remains the Provider.save responsibility. */
+    save: (input: Omit<ReportInstanceSnapshot, "revision">, options: {
+        expectedRevision: number | null;
+        signal?: AbortSignal;
+    }) => Promise<ReportInstanceSnapshot>;
+};
+
+/** Save is explicit. A preview/query never calls this manager or overwrites a prior instance. */
+export declare function createReportInstanceManager(store: ReportInstanceStore, options?: {
+    maxSnapshotBytes?: number;
+}): {
+    read: (scope: string, id: string, revision?: number, signal?: AbortSignal) => Promise<ReportInstanceSnapshot | undefined>;
+    list: (scope: string, options?: ReportInstanceListOptions) => Promise<ReportInstancePage>;
+    save: (input: Omit<ReportInstanceSnapshot, "revision">, options: {
+        expectedRevision: number | null;
+        signal?: AbortSignal;
+    }) => Promise<ReportInstanceSnapshot>;
+};
+
 /** Durable at-least-once dispatch; export/artifact handlers must be idempotent by scope+taskId. */
 export declare function createReportJobService(options: ReportJobServiceOptions): ReportJobService;
 
@@ -125,6 +160,8 @@ declare interface GridCell {
     value?: string | number | boolean | null;
     /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
     numberFormat?: string;
+    /** Physical left inset for hierarchical labels; raw value stays unchanged. */
+    indentMm?: number;
     /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
@@ -171,6 +208,8 @@ declare interface ListColumn {
 
 declare interface ListComponent {
     kind: "list";
+    /** Opaque serializable layout annotations; interpreted only by explicit optional adapters. */
+    meta?: Record<string, unknown>;
     id?: string;
     /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
     layout?: "page" | "wide";
@@ -180,6 +219,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** Headerless record/region bindings do not allocate a synthetic list header. */
+    header?: boolean;
+    /** A fixed record region rejects multiple rows instead of dropping source data. */
+    cardinality?: "record";
     /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
     rowKey?: string;
     revisionField?: string;
@@ -206,6 +249,8 @@ declare interface ListComponent {
     computed?: ComputedField[];
     /** Dynamic pivot of the current source dataset, with read-only derived identities. */
     matrix?: MatrixTableOptions;
+    /** Full ordered hierarchy; source parent values and descendant-leaf rollups are explicit. */
+    tree?: TreeTableOptions;
     /** Explicit row visibility; hidden rows do not participate in summaries. */
     rowVisibleWhen?: StyleRule["when"];
     /** Master/detail relation is keyed by business identity, never by display row index. */
@@ -272,6 +317,13 @@ declare interface MatrixTableOptions {
     maxCells?: number;
 }
 
+export declare interface MemoryReportInstanceStoreOptions {
+    maxInstances?: number;
+    maxRevisions?: number;
+    maxBytes?: number;
+    maxSnapshotBytes?: number;
+}
+
 declare interface OutputDiagnostic {
     code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
     severity: "warning";
@@ -340,6 +392,7 @@ declare interface PlanGrid {
 }
 
 declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -385,6 +438,43 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+export declare interface ReportBatchCase {
+    id: string;
+    params: Record<string, string>;
+}
+
+export declare interface ReportBatchOptions {
+    concurrency?: number;
+    maxCases?: number;
+    signal?: AbortSignal;
+    /** Stop launching new cases after the first failure; already running cases finish. */
+    failure?: "continue" | "stop";
+    onProgress?: (progress: ReportBatchProgress) => void;
+}
+
+export declare type ReportBatchOutcome<T> = {
+    id: string;
+    index: number;
+} & ({
+    status: "completed";
+    value: T;
+} | {
+    status: "failed";
+    error: {
+        name: string;
+        message: string;
+    };
+} | {
+    status: "cancelled";
+});
+
+export declare interface ReportBatchProgress {
+    completed: number;
+    total: number;
+    failed: number;
+    cancelled: number;
+}
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 declare interface ReportCellAddress {
     pageIndex: number;
@@ -486,6 +576,78 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+declare interface ReportFlowBand {
+    /** Exact stable component IDs. Static components use nid, lists use id. */
+    componentIds: string[];
+    /** Source-template coordinates; following bands keep their original gap. */
+    topMm: number;
+    heightMm: number;
+}
+
+export declare interface ReportGenerationInput {
+    scope: string;
+    id: string;
+    title: string;
+    reportIds: string[];
+    params?: Record<string, string>;
+    expectedRevision: number | null;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportInstanceArtifact {
+    key: string;
+    format: "pdf" | "xlsx";
+    bytes: number;
+    sha256?: string;
+}
+
+export declare class ReportInstanceError extends Error {
+    readonly code: "input" | "conflict" | "capacity";
+    constructor(code: "input" | "conflict" | "capacity", message: string);
+}
+
+export declare interface ReportInstanceListOptions {
+    after?: string;
+    limit?: number;
+    reportId?: string;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportInstancePage {
+    items: ReportInstanceSummary[];
+    next?: string;
+}
+
+/** Stable parameter identity without adding a database, user account or credential to the SDK. */
+export declare function reportInstanceParameterKey(reportIds: string[], params: Record<string, string>): string;
+
+export declare interface ReportInstanceSnapshot {
+    scope: string;
+    id: string;
+    revision: number;
+    title: string;
+    generatedAt: string;
+    reportIds: string[];
+    params: Record<string, string>;
+    /** Exact template/data revisions used by generation, never inferred from a later template read. */
+    templateRevisions: Record<string, string>;
+    sourceRevisions: Record<string, string>;
+    plan: RenderPlan;
+    /** Private storage keys; signed download URLs must be generated by the host after authorization. */
+    artifacts?: ReportInstanceArtifact[];
+}
+
+export declare interface ReportInstanceStore {
+    read(scope: string, id: string, revision?: number, signal?: AbortSignal): Promise<ReportInstanceSnapshot | undefined>;
+    list(scope: string, options?: ReportInstanceListOptions): Promise<ReportInstancePage>;
+    /** Atomic append + current-revision advance. Historical revisions must never be overwritten. */
+    compareAndSwap(scope: string, id: string, expectedRevision: number | null, next: ReportInstanceSnapshot, signal?: AbortSignal): Promise<boolean>;
+}
+
+export declare type ReportInstanceSummary = Omit<ReportInstanceSnapshot, "plan" | "artifacts">;
+
+export declare function reportInstanceSummary(snapshot: ReportInstanceSnapshot): ReportInstanceSummary;
+
 export declare class ReportJobError extends Error {
     readonly code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity";
     constructor(code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity", message: string);
@@ -616,13 +778,17 @@ declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+declare interface ReportPageFlow {
+    bands: ReportFlowBand[];
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
     /** select 选项 */
     options?: Array<{
         label: string;
@@ -631,7 +797,7 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    /** 数字上下界；日期/月/年使用对应规范字符串；dateRange 对两端使用 YYYY-MM-DD 边界（含边界）。 */
     min?: number | string;
     max?: number | string;
     minLength?: number;
@@ -968,12 +1134,22 @@ declare interface RichSegment {
 
 export declare function runnableJob(record: ReportJobRecord, now: number): boolean;
 
+/** Browser/Node shared bounded runner. Return small receipts; persist/export large artifacts inside execute. */
+export declare function runReportBatch<T>(input: readonly ReportBatchCase[], execute: (item: ReportBatchCase, context: {
+    index: number;
+    signal: AbortSignal;
+}) => Promise<T>, options?: ReportBatchOptions): Promise<ReportBatchOutcome<T>[]>;
+
 /** Canonical plain JSON rejects getters/scripts and gives stable idempotency without coercion. */
 export declare function serializeJobJson(value: unknown, budget?: {
     maxNodes?: number;
     maxCharacters?: number;
 }): string;
 
+export declare function snapshotReportBatchCases(input: readonly ReportBatchCase[], maximum?: number): ReportBatchCase[];
+
+export declare function snapshotReportInstance(value: ReportInstanceSnapshot, maxBytes?: number): ReportInstanceSnapshot;
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
     when: {
@@ -999,6 +1175,9 @@ declare interface TemplatePage {
     marginLeftMm?: number;
     marginRightMm?: number;
     components: TemplateComponent[];
+    /** Explicit vertical bands preserve source gaps as dynamic regions expand. */
+    flow?: ReportPageFlow;
+    meta?: Record<string, unknown>;
 }
 
 /**
@@ -1021,6 +1200,26 @@ declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** A serialized tree contract. Sibling and root order follow input order. */
+declare interface TreeTableOptions {
+    input: "flat" | "nested";
+    idField: string;
+    /** Flat roots have null/undefined parent values. */
+    parentField?: string;
+    /** Nested child arrays, defaults to children. Every node still needs an ID. */
+    childrenField?: string;
+    labelField: string;
+    indentMm?: number;
+    orphan?: "error" | "root";
+    /** Source preserves parent values; leaf-aggregate derives only parents from descendant leaves. */
+    parentValues?: "source" | "leaf-aggregate";
+    aggregates?: AggregateDefinition[];
+    maxRows?: number;
+    maxDepth?: number;
+    /** Bounded leaf-to-ancestor aggregate work; default one million. */
+    maxAggregationVisits?: number;
+}
+
 export declare function validateJobRecord(record: ReportJobRecord, scope: string, id: string, expectedRevision: number | null): void;
 
 export declare function validateJobTransition(previous: ReportJobRecord | undefined, next: ReportJobRecord): void;