@agile-team/mach-report 2.14.0 → 2.16.0

package/dist/server.d.cts

@@ -8,8 +8,20 @@ declare interface AggregateDefinition {
     digits?: number;
 }
 
+declare interface AggregateDefinition_2 {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation_2;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+declare type AggregateOperation_2 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+
 declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -21,7 +33,7 @@ declare interface AssetRenderBudget {
     maxDurationMs?: number;
 }
 
-declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
@@ -47,6 +59,18 @@ declare interface CodeOptions {
     showText?: boolean;
 }
 
+/** Serializable symbol settings. Encoders remain in the optional /codes entry. */
+declare interface CodeOptions_2 {
+    /** Explicit content, including an empty value, takes precedence over legacy fallbackText. */
+    value?: string;
+    symbology?: "code128" | "code39" | "ean13" | "ean8";
+    errorCorrection?: "L" | "M" | "Q" | "H";
+    /** White modules around a symbol: QR >=4, linear >=10, EAN >=11. */
+    quietZoneModules?: number;
+    /** Human-readable content below a linear barcode. */
+    showText?: boolean;
+}
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -70,6 +94,29 @@ declare type ColumnFormat = {
     pattern?: string;
 };
 
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat_2 = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 declare interface ComponentBinding {
     field: string;
@@ -79,6 +126,15 @@ declare interface ComponentBinding {
     emptyText?: string;
 }
 
+/** A literal own field of the current label record; expressions and paths are not evaluated. */
+declare interface ComponentBinding_2 {
+    field: string;
+    format?: ValueFormat_2;
+    prefix?: string;
+    suffix?: string;
+    emptyText?: string;
+}
+
 declare interface ComponentImageContext {
     readonly component: Readonly<PlanComponent>;
     readonly pageIndex: number;
@@ -91,6 +147,8 @@ declare type ComponentImageRenderer = (context: ComponentImageContext) => string
 
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
+declare type ComponentKind_2 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
 declare interface ComponentStyle {
     fontSizePx?: number;
     fontSize?: number;
@@ -115,6 +173,30 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+declare interface ComponentStyle_2 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
 declare interface ComputedField extends ExpressionOptions {
     field: string;
     expression: ReportExpression | string;
@@ -125,6 +207,23 @@ declare interface ComputedField extends ExpressionOptions {
     dependsOn?: readonly string[];
 }
 
+declare interface ComputedField_2 extends ExpressionOptions_2 {
+    field: string;
+    expression: ReportExpression_2 | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
+
+export declare function createManagerTemplateCatalog(manager: ReportTemplateManager, metadata?: (document: ReportTemplateDocument) => Pick<LocalTemplateCatalogItem, "category" | "tags">): ReportTemplateCatalogProvider;
+
+/** Session-local intents; durable hosts should supply their own authorized stable IDs. */
+export declare function createMemoryReportInstanceIds(maximum?: number): {
+    forCase(templateId: string, caseId: string): string;
+};
+
 /** Bounded reference store for tests/local sessions. Production hosts implement durable transactional CAS. */
 export declare function createMemoryReportInstanceStore(options?: MemoryReportInstanceStoreOptions): ReportInstanceStore;
 
@@ -180,6 +279,31 @@ export declare function createReportTaskQueue(options?: {
     maxQueued?: number;
 }): ReportTaskQueue;
 
+/** Export explicitly selected metadata/samples; external resource bytes stay in host-managed storage. */
+export declare function createReportTemplatePackage(input: Omit<ReportTemplatePackage, "schemaVersion" | "resources" | "minimumVersion"> & {
+    resources?: ReportPackageResource[];
+    minimumVersion?: string;
+}, options?: ReportTemplatePackageOptions): ReportTemplatePackage;
+
+/** Optional package-owned catalog → draft publication → immutable batch/instance wiring. */
+export declare function createReportWorkflow(options: ReportWorkflowOptions): {
+    catalog: ReportTemplateCatalogProvider;
+    publish: (input: ReportWorkflowPublishInput) => Promise<ReportTemplateRecord_2>;
+    /** Resolve only a manager-owned publication, then keep that exact revision for this batch. */
+    batch(id: string, request?: {
+        expectedRevision?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        document: ReportTemplateDocument;
+        execute(item: ReportBatchCase, { signal }: {
+            signal?: AbortSignal;
+        }): Promise<{
+            instanceId: string;
+            label: string;
+        }>;
+    }>;
+};
+
 declare interface DatasetContract {
     fields: readonly ReportFieldContract[];
     rowKey?: string;
@@ -201,6 +325,13 @@ declare interface ExpressionOptions {
     divisionByZero?: "null" | "error";
 }
 
+declare interface ExpressionOptions_2 {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+
 declare interface FormulaAdapter {
     /** Explicit trusted engine; core never evaluates source code/macros/external workbook references. */
     evaluate(expression: string, context: {
@@ -211,6 +342,8 @@ declare interface FormulaAdapter {
 }
 
 declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -234,8 +367,47 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 
+declare interface GridCell_2 {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph_2[];
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    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。 */
+    editable?: boolean;
+    source?: ReportCellSource_2;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent_2[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle_2;
+}
+
 declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
 
+/** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
+declare interface ImageMediaOptions {
+    maxImageBytes?: number;
+    maxTotalImageBytes?: number;
+    maxImages?: number;
+    /** Decoded pixels per unique image, default 16 million. */
+    maxImagePixels?: number;
+    /** Total decoded pixels for unique media, default 64 million. */
+    maxTotalImagePixels?: number;
+    /** Maximum source dimension, default 16384 pixels. */
+    maxImageDimension?: number;
+}
+
 export declare interface LabelStreamContext {
     index: number;
     rowOffset: number;
@@ -282,6 +454,9 @@ export declare interface LabelStreamReceipt {
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
 declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
 
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment_2 = NonNullable<ComponentStyle_2["align"]> | "auto";
+
 declare interface ListColumn {
     header: string;
     field: string;
@@ -308,6 +483,32 @@ declare interface ListColumn {
     visibleWhen?: StyleRule["when"];
 }
 
+declare interface ListColumn_2 {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle_2;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment_2;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle_2["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle_2;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat_2;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule_2[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell_2["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    hidden?: boolean;
+    /** Condition hides cell content, preserving its physical layout in preview and exports. */
+    visibleWhen?: StyleRule_2["when"];
+}
+
 declare interface ListComponent {
     kind: "list";
     /** Opaque serializable layout annotations; interpreted only by explicit optional adapters. */
@@ -361,6 +562,59 @@ declare interface ListComponent {
     grandTotal?: ListGrandTotal;
 }
 
+declare interface ListComponent_2 {
+    kind: "list";
+    /** Opaque serializable layout annotations; interpreted only by explicit optional adapters. */
+    meta?: Record<string, unknown>;
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    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;
+    sourceTokenField?: string;
+    columns: ListColumn_2[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment_2;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle_2["align"];
+    headerStyle?: ComponentStyle_2;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid_2;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy_2;
+    /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
+    groups?: ListGroupBy_2[];
+    computed?: ComputedField_2[];
+    /** Dynamic pivot of the current source dataset, with read-only derived identities. */
+    matrix?: MatrixTableOptions_2;
+    /** Full ordered hierarchy; source parent values and descendant-leaf rollups are explicit. */
+    tree?: TreeTableOptions_2;
+    /** Explicit row visibility; hidden rows do not participate in summaries. */
+    rowVisibleWhen?: StyleRule_2["when"];
+    /** Master/detail relation is keyed by business identity, never by display row index. */
+    detail?: ListDetail_2;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal_2;
+}
+
 declare interface ListDetail {
     dataset: string;
     parentKey: string;
@@ -377,6 +631,22 @@ declare interface ListDetail {
     unmatched?: "error" | "ignore";
 }
 
+declare interface ListDetail_2 {
+    dataset: string;
+    parentKey: string;
+    foreignKey: string;
+    rowKey?: string;
+    /** 子表独立的并发契约；省略时不继承主表字段。 */
+    revisionField?: string;
+    sourceTokenField?: string;
+    columns: ListColumn_2[];
+    rowHeightMm?: number;
+    header?: boolean;
+    label?: string;
+    /** Unmatched children fail by default; opt-in ignore is explicit. */
+    unmatched?: "error" | "ignore";
+}
+
 declare type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle;
@@ -385,6 +655,14 @@ declare type ListGrandTotal = boolean | {
     aggregates?: AggregateDefinition[];
 };
 
+declare type ListGrandTotal_2 = boolean | {
+    label?: string;
+    style?: ComponentStyle_2;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+    aggregates?: AggregateDefinition_2[];
+};
+
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy {
     /** 分组字段（值变化即切组） */
@@ -403,6 +681,34 @@ declare interface ListGroupBy {
     repeatHeader?: boolean;
 }
 
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy_2 {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle_2;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle_2;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+    aggregates?: AggregateDefinition_2[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
+}
+
+declare interface LocalTemplateCatalogItem {
+    /** Editable document: prefer the latest draft; otherwise use the published document. */
+    document: ReportTemplateDocument;
+    published?: ReportTemplateDocument;
+    draftRevision?: string;
+    publishedRevision?: string;
+    category?: string;
+    tags?: string[];
+}
+
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -419,6 +725,22 @@ declare interface MatrixTableOptions {
     maxCells?: number;
 }
 
+declare interface MatrixTableOptions_2 {
+    rowFields: readonly string[];
+    columnFields: readonly string[];
+    measures: readonly (AggregateDefinition_2 & {
+        label?: string;
+    })[];
+    totals?: boolean;
+    rowHeader?: string;
+    columnWidthMm?: number;
+    rowWidthMm?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    maxInputRows?: number;
+    maxCells?: number;
+}
+
 export declare interface MemoryReportInstanceStoreOptions {
     maxInstances?: number;
     maxRevisions?: number;
@@ -427,7 +749,7 @@ export declare interface MemoryReportInstanceStoreOptions {
 }
 
 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";
+    code: "invalid-image-data" | "image-budget-exceeded" | "component-render-failed" | "unsupported-text" | "output-degraded" | "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";
     format: OutputFormat;
     pageIndex: number;
@@ -471,6 +793,9 @@ declare interface PaginateOptions {
     formula?: FormulaAdapter;
 }
 
+/** Parse a bounded manifest without network access, code execution, registration or publication. */
+export declare function parseReportTemplatePackage(input: unknown, options?: ReportTemplatePackageOptions): ReportTemplatePackage;
+
 declare interface PlanComponent {
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
@@ -500,6 +825,35 @@ declare interface PlanComponent {
     fallbackText?: string;
 }
 
+declare interface PlanComponent_2 {
+    /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
+    code?: CodeOptions_2;
+    /** Template-only binding; resolved and removed before constructing the output plan. */
+    binding?: ComponentBinding_2;
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
+    kind: ComponentKind_2;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph_2[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid_2;
+    table?: PlanTableFragment_2;
+    style?: ComponentStyle_2;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
 declare interface PlanGrid {
     /** 行内允许 null 空位；渲染器按空单元格处理 */
     cells: (GridCell | null)[][];
@@ -510,6 +864,16 @@ declare interface PlanGrid {
     paddingMm?: number;
 }
 
+declare interface PlanGrid_2 {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell_2 | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
 declare interface PlanPage {
     meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
@@ -540,6 +904,23 @@ declare interface PlanTableFragment {
     };
 }
 
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment_2 {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_2, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+
 export declare interface PreparedReport {
     plan: RenderPlan;
     diagnostics: ReportDiagnostic[];
@@ -548,6 +929,8 @@ export declare interface PreparedReport {
         revision?: string;
         sourceToken?: string;
     }>;
+    /** Ordered occurrences; legacy revisions remains last-value-by-ID for compatibility. */
+    sources?: ReportRuntimeSource[];
     /** Captured metrics identity; absence on old saved instances remains supported with diagnostics. */
     layout?: {
         textMetrics: "heuristic" | "provided" | "font-bytes";
@@ -621,6 +1004,19 @@ declare interface ReportCellEdit {
 
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource_2 {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -644,9 +1040,13 @@ declare interface ReportDataTarget {
     rowKey?: string | number;
     /** Use table identity when the same dataset appears in several tables. */
     tableId?: string;
+    /** Assigned by the source/runtime when several reports share dataset names. */
+    reportScope?: string;
 }
 
 declare interface ReportDefinition {
+    /** Explicitly shared editable data identity. Omit to isolate each report occurrence. */
+    sourceScope?: string;
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
     /** 静态数据；load 存在时优先使用 load 的结果。 */
@@ -698,6 +1098,19 @@ declare type ReportExpression = {
     args: readonly ReportExpression[];
 };
 
+declare type ReportExpression_2 = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation_2;
+    field?: string;
+    weightField?: string;
+} | {
+    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    args: readonly ReportExpression_2[];
+};
+
 declare interface ReportFieldContract {
     field: string;
     label?: string;
@@ -721,6 +1134,14 @@ declare interface ReportFlowBand {
     heightMm: number;
 }
 
+declare interface ReportFlowBand_2 {
+    /** 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;
@@ -771,7 +1192,9 @@ export declare interface ReportInstanceSnapshot {
     sourceRevisions: Record<string, string>;
     plan: RenderPlan;
     /** Exact generation diagnostics, row statistics and font metrics; optional for legacy instances. */
-    output?: Omit<PreparedReport, "plan" | "revisions">;
+    output?: Omit<PreparedReport, "plan" | "revisions" | "sources"> & {
+        sources?: Array<Omit<ReportRuntimeSource, "sourceToken">>;
+    };
     /** Private storage keys; signed download URLs must be generated by the host after authorization. */
     artifacts?: ReportInstanceArtifact[];
 }
@@ -795,6 +1218,10 @@ export declare class ReportJobError extends Error {
 export declare interface ReportJobExecutionContext {
     scope: string;
     taskId: string;
+    /** Immutable claim generation; compare atomically at the host artifact commit boundary. */
+    readonly attempt: number;
+    /** Opaque tuple identity, scoped to this claim; never a credential. */
+    readonly executionToken: string;
     signal: AbortSignal;
     reportProgress(completed: number, total?: number): Promise<void>;
 }
@@ -917,10 +1344,53 @@ declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+export declare interface ReportPackageFixture {
+    name: string;
+    /** Explicit host confirmation; the SDK does not infer that business values are anonymous. */
+    deidentified: true;
+    datasets: DatasetRows;
+    params?: Record<string, string>;
+}
+
+export declare interface ReportPackageImageTarget {
+    pageIndex: number;
+    /** Top component index, then optional repeated grid-row / cell / child triplets. */
+    componentPath: number[];
+}
+
+export declare interface ReportPackageResource {
+    id: string;
+    kind: "font" | "image";
+    mediaType: "font/ttf" | "font/otf" | "image/png" | "image/jpeg";
+    bytes: number;
+    sha256: string;
+    license?: string;
+    font?: {
+        family: string;
+        face: "regular" | "bold" | "italic" | "boldItalic";
+    };
+    targets?: ReportPackageImageTarget[];
+}
+
+export declare interface ReportPackageResourceBytes {
+    bytes: Uint8Array;
+    mediaType: ReportPackageResource["mediaType"];
+}
+
+export declare function reportPackageResourceDigest(bytes: Uint8Array): string;
+
+export declare type ReportPackageResourceResolver = (resource: Readonly<ReportPackageResource>, context: {
+    signal: AbortSignal;
+}) => ReportPackageResourceBytes | Promise<ReportPackageResourceBytes>;
+
 declare interface ReportPageFlow {
     bands: ReportFlowBand[];
 }
 
+declare interface ReportPageFlow_2 {
+    bands: ReportFlowBand_2[];
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -933,6 +1403,36 @@ declare interface ReportParamDef {
         label: string;
         value: string;
     }>;
+    /** 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. */
+    dependsOn?: string[];
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+    /** 数字上下界；日期/月/年使用对应规范字符串；dateRange 对两端使用 YYYY-MM-DD 边界（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef_2 {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** 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. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -950,7 +1450,7 @@ declare interface ReportParamIssue {
     message: string;
 }
 
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
 
 declare interface ReportParamValidation {
     ok: boolean;
@@ -1064,10 +1564,11 @@ export declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
     format: "pdf" | "xlsx";
     /** strict 在编码前拒绝已识别的输出降级；默认保留诊断并继续。 */
     fidelity?: "warn" | "strict";
-    xlsx?: {
+    xlsx?: ImageMediaOptions & {
         sheetMode?: "auto" | "pages" | "continuous";
         valueMode?: "text" | "raw";
         paperSize?: "auto" | "a3" | "a4" | "a5";
+        sheetName?: (sheetIndex: number) => string;
     };
 }
 
@@ -1098,6 +1599,8 @@ export declare interface ReportRuntimeOptions {
 /** Encode an existing plan without querying providers or repaginating. */
 export declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring {
     prepared: PreparedReport;
+    /** verify checks font metric identity; preserve explicitly keeps existing geometry, with a diagnostic. Encoding fidelity is unchanged. */
+    layoutPolicy?: "verify" | "preserve";
     format: ReportRuntimeExportInput["format"];
     fidelity?: ReportRuntimeExportInput["fidelity"];
     pdf?: ReportPdfFontOptions;
@@ -1105,6 +1608,15 @@ export declare interface ReportRuntimePreparedExportInput extends ReportTaskMoni
     signal?: AbortSignal;
 }
 
+/** One query occurrence; repeated report IDs retain independent provenance. */
+export declare interface ReportRuntimeSource {
+    reportId: string;
+    reportIndex: number;
+    reportScope: string;
+    revision?: string;
+    sourceToken?: string;
+}
+
 export declare interface ReportRuntimeStats {
     rows: number;
     pages: number;
@@ -1195,6 +1707,55 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare interface ReportTemplate_2 {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef_2[];
+    /** Fixed label pages repeat in record → copy → template-page order. */
+    repeat?: ReportTemplateRepeat_2;
+    pages: TemplatePage_2[];
+}
+
+declare interface ReportTemplateCatalogEntry extends ReportTemplateSummary {
+    category?: string;
+    tags?: string[];
+    updatedAt?: string;
+    /** Optional lifecycle metadata. revision continues to identify the editable document. */
+    draftRevision?: string;
+    publishedRevision?: string;
+}
+
+declare interface ReportTemplateCatalogOpenContext {
+    mode: "edit" | "published";
+}
+
+declare interface ReportTemplateCatalogPage {
+    items: ReportTemplateCatalogEntry[];
+    next?: string;
+    categories?: Array<{
+        id: string;
+        label: string;
+        count?: number;
+    }>;
+}
+
+/** Discovery metadata is separate from executable templates and from enterprise account authorization. */
+declare interface ReportTemplateCatalogProvider {
+    search(request: ReportTemplateCatalogQuery): Promise<ReportTemplateCatalogPage>;
+    get(id: string, context: {
+        signal?: AbortSignal;
+        mode?: ReportTemplateCatalogOpenContext["mode"];
+    }): Promise<ReportTemplateDocument | undefined>;
+}
+
+declare interface ReportTemplateCatalogQuery {
+    query?: string;
+    category?: string;
+    cursor?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+
 declare interface ReportTemplateChange {
     kind: "added" | "removed" | "modified" | "moved";
     category: "metadata" | "structure" | "binding" | "calculation" | "format";
@@ -1222,6 +1783,17 @@ declare interface ReportTemplateDocument {
     template: ReportTemplate;
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument_2 {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate_2;
+}
+
 declare interface ReportTemplateFixture {
     name: string;
     datasets: DatasetRows;
@@ -1230,6 +1802,35 @@ declare interface ReportTemplateFixture {
 
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
+declare interface ReportTemplateManager {
+    list(signal?: AbortSignal): ReturnType<ReportTemplateStore["list"]>;
+    get(id: string, options?: {
+        draft?: boolean;
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+    history(id: string, signal?: AbortSignal): Promise<readonly ReportTemplateVersion[]>;
+    saveDraft(input: unknown, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+    publish(id: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+    rollback(id: string, revision: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+}
+
+export declare interface ReportTemplatePackage {
+    schemaVersion: "1.0";
+    minimumVersion: string;
+    document: ReportTemplateDocument;
+    contracts?: Record<string, DatasetContract>;
+    resources: ReportPackageResource[];
+    fixtures?: ReportPackageFixture[];
+}
+
+export declare interface ReportTemplatePackageOptions {
+    /** Installed SDK version, compared before any resolver or persistence is called. */
+    runtimeVersion?: string;
+    maxBytes?: number;
+    maxResourceBytes?: number;
+    signal?: AbortSignal;
+}
+
 declare interface ReportTemplateProvider {
     list(context: {
         signal?: AbortSignal;
@@ -1239,6 +1840,22 @@ declare interface ReportTemplateProvider {
     }): Promise<ReportTemplateDocument | undefined>;
 }
 
+declare interface ReportTemplateRecord {
+    id: string;
+    revision: string;
+    draft?: ReportTemplateDocument;
+    publishedRevision?: string;
+    published?: ReportTemplateDocument;
+}
+
+declare interface ReportTemplateRecord_2 {
+    id: string;
+    revision: string;
+    draft?: ReportTemplateDocument_2;
+    publishedRevision?: string;
+    published?: ReportTemplateDocument_2;
+}
+
 /** Every record emits its copies, each containing all template pages in their original order. */
 declare interface ReportTemplateRepeat {
     dataset: string;
@@ -1249,6 +1866,16 @@ declare interface ReportTemplateRepeat {
     };
 }
 
+/** Every record emits its copies, each containing all template pages in their original order. */
+declare interface ReportTemplateRepeat_2 {
+    dataset: string;
+    rowKey?: string;
+    /** Whole copies per record, 1..1000. The field value must be a number, never a numeric string. */
+    copies?: number | {
+        field: string;
+    };
+}
+
 declare interface ReportTemplateReview {
     ok: boolean;
     changes?: ReportTemplateDiff;
@@ -1286,11 +1913,78 @@ declare interface ReportTemplateReviewOptions {
     strictOutputs?: boolean;
 }
 
+/** compareAndSwap 必须由宿主数据库/文件适配器保证原子性，不能用先读再无条件写替代。 */
+declare interface ReportTemplateStore {
+    read(id: string, signal?: AbortSignal): Promise<ReportTemplateRecord | undefined>;
+    list(signal?: AbortSignal): Promise<Array<{
+        id: string;
+        revision: string;
+        publishedRevision?: string;
+    }>>;
+    history(id: string, signal?: AbortSignal): Promise<ReportTemplateVersion[]>;
+    getVersion(id: string, revision: string, signal?: AbortSignal): Promise<ReportTemplateVersion | undefined>;
+    /** 状态更新和 publication 的不可变追加必须处于同一原子事务；草稿写入不读取历史。 */
+    compareAndSwap(id: string, expectedRevision: string | null, next: ReportTemplateRecord, options: TemplateStoreWriteOptions): Promise<boolean>;
+}
+
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
 
+declare interface ReportTemplateVersion {
+    revision: string;
+    publishedAt: string;
+    document: ReportTemplateDocument;
+    restoredFrom?: string;
+}
+
 /** Optional business explanations never replace raw data or schema validation. */
 declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 
+/** Structural bridge: no Vue/designer dependency is loaded by the workflow. */
+export declare interface ReportWorkflowEditor {
+    readonly saving?: boolean;
+    readonly blocked?: boolean;
+    readonly pendingLocalChanges: boolean;
+    save(): void | Promise<void>;
+}
+
+export declare interface ReportWorkflowOptions {
+    templates: ReportTemplateManager;
+    instances: ReportInstanceStore;
+    scope: string;
+    data: Omit<ReportDefinition, "template"> | ((document: ReportTemplateDocument) => Omit<ReportDefinition, "template">);
+    runtime?: Omit<ReportRuntimeOptions, "reports">;
+    pdf?: ReportPdfFontOptions;
+    instanceId?(templateId: string, caseId: string): string;
+    title?(document: ReportTemplateDocument, item: ReportBatchCase, params: Record<string, string>): string;
+    catalog?: ReportTemplateCatalogProvider;
+    catalogMetadata?(document: ReportTemplateDocument): Pick<LocalTemplateCatalogItem, "category" | "tags">;
+}
+
+export declare interface ReportWorkflowPublishInput {
+    editor: ReportWorkflowEditor;
+    document(): ReportTemplateDocument;
+    successfulSaves(): number;
+    afterSave(): Promise<unknown>;
+}
+
+export declare interface ResolvedReportPackageFont {
+    id: string;
+    family: string;
+    face: NonNullable<ReportPackageResource["font"]>["face"];
+    bytes: Uint8Array;
+}
+
+/** Verify all host-resolved bytes before returning a hydrated independent document. No implicit save. */
+export declare function resolveReportTemplatePackage(input: unknown, options: ReportTemplatePackageOptions & {
+    resolve: ReportPackageResourceResolver;
+    maxDurationMs?: number;
+}): Promise<{
+    document: ReportTemplateDocument;
+    fonts: ResolvedReportPackageFont[];
+    contracts: Record<string, DatasetContract> | undefined;
+    fixtures: ReportPackageFixture[];
+}>;
+
 /** Publication gate with actual sequential PDF/XLSX encoding, no business query or implicit save. */
 export declare function reviewReportPublication(input: unknown, options?: ReportPublicationOptions): Promise<ReportPublicationReview>;
 
@@ -1303,6 +1997,15 @@ declare interface RichParagraph {
     indentMm?: number;
 }
 
+declare interface RichParagraph_2 {
+    segments: RichSegment_2[];
+    align?: ComponentStyle_2["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
 declare interface RichSegment {
     kind?: "text" | "field";
     text?: string;
@@ -1310,6 +2013,13 @@ declare interface RichSegment {
     style?: ComponentStyle;
 }
 
+declare interface RichSegment_2 {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle_2;
+}
+
 /** Bounded fixed-label consumption, not cross-chunk aggregation or a new durable task queue.
  * The next source chunk is pulled only after execute + onReceipt complete. Earlier receipts
  * remain committed if a later chunk fails; use onReceipt for a durable incremental manifest.
@@ -1324,6 +2034,8 @@ export declare function runReportBatch<T>(input: readonly ReportBatchCase[], exe
     signal: AbortSignal;
 }) => Promise<T>, options?: ReportBatchOptions): Promise<ReportBatchOutcome<T>[]>;
 
+export declare function saveAndPublishReportTemplate(manager: ReportTemplateManager, options: ReportWorkflowPublishInput): Promise<ReportTemplateRecord_2>;
+
 /** Canonical plain JSON rejects getters/scripts and gives stable idempotency without coercion. */
 export declare function serializeJobJson(value: unknown, budget?: {
     maxNodes?: number;
@@ -1347,8 +2059,28 @@ declare interface StyleRule {
     style: Record<string, unknown>;
 }
 
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule_2 {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+        /** Explicit decimal comparisons retain decimal thresholds as text. */
+        numeric?: "number" | "decimal";
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+
 declare type TemplateComponent = PlanComponent | ListComponent;
 
+declare type TemplateComponent_2 = PlanComponent_2 | ListComponent_2;
+
+declare interface TemplateMutationOptions {
+    expectedRevision: string | null;
+    signal?: AbortSignal;
+}
+
 declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
@@ -1364,6 +2096,26 @@ declare interface TemplatePage {
     meta?: Record<string, unknown>;
 }
 
+declare interface TemplatePage_2 {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent_2[];
+    /** Explicit vertical bands preserve source gaps as dynamic regions expand. */
+    flow?: ReportPageFlow_2;
+    meta?: Record<string, unknown>;
+}
+
+declare interface TemplateStoreWriteOptions {
+    publication?: ReportTemplateVersion;
+    signal?: AbortSignal;
+}
+
 /**
  * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
  *
@@ -1404,6 +2156,26 @@ declare interface TreeTableOptions {
     maxAggregationVisits?: number;
 }
 
+/** A serialized tree contract. Sibling and root order follow input order. */
+declare interface TreeTableOptions_2 {
+    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_2[];
+    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;
@@ -1411,4 +2183,7 @@ export declare function validateJobTransition(previous: ReportJobRecord | undefi
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 
+/** The same declarative formatting used by list columns, before any output backend. */
+declare type ValueFormat_2 = ColumnFormat_2;
+
 export { }