@agile-team/mach-report 2.9.1 → 2.11.0

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,8 +75,41 @@ 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(): ReportJobStore;
+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,11 +160,15 @@ 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。 */
     editable?: boolean;
     source?: ReportCellSource;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -169,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";
@@ -178,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;
@@ -204,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. */
@@ -217,6 +264,9 @@ declare interface ListDetail {
     parentKey: string;
     foreignKey: string;
     rowKey?: string;
+    /** 子表独立的并发契约；省略时不继承主表字段。 */
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     rowHeightMm?: number;
     header?: boolean;
@@ -267,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";
@@ -335,6 +392,7 @@ declare interface PlanGrid {
 }
 
 declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -375,9 +433,48 @@ export declare interface PreparedReport {
 
 declare interface RenderPlan {
     schemaVersion: string;
+    /** 编辑需要模板重算上下文；跨 Worker/JSON 保留要求，但不声明本地会话可用。 */
+    requiresRecalculation?: boolean;
     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;
@@ -479,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);
@@ -497,6 +666,18 @@ export declare type ReportJobJson = null | boolean | number | string | ReportJob
     [key: string]: ReportJobJson;
 };
 
+export declare interface ReportJobPruneOptions {
+    now: number;
+    terminalBefore: number;
+    tombstoneRetentionMs?: number;
+    limit?: number;
+}
+
+export declare interface ReportJobPruneResult {
+    archived: number;
+    expired: number;
+}
+
 export declare interface ReportJobRecord {
     scope: string;
     id: string;
@@ -516,6 +697,8 @@ export declare interface ReportJobRecord {
         total?: number;
     };
     result?: ReportJobJson;
+    /** Idempotent submit after terminal archival; result/error payloads are no longer retained. */
+    archived?: boolean;
     error?: {
         code: string;
         message: string;
@@ -539,6 +722,8 @@ export declare interface ReportJobService {
     runNext(workerId: string): Promise<ReportJobRecord | undefined>;
     /** Stops new dispatch, signals active handlers and waits until their actual completion. */
     close(): Promise<void>;
+    /** Archive terminal payloads and retain bounded idempotency fingerprints; never removes active work. */
+    prune(options: Omit<ReportJobPruneOptions, "now">): Promise<ReportJobPruneResult>;
     readonly active: number;
 }
 
@@ -549,6 +734,8 @@ export declare interface ReportJobServiceOptions {
     leaseMs?: number;
     heartbeatMs?: number;
     now?: () => number;
+    /** Result references have a separate byte budget; default 256KiB. */
+    maxResultBytes?: number;
 }
 
 export declare type ReportJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
@@ -557,9 +744,33 @@ export declare type ReportJobStatus = "queued" | "running" | "completed" | "fail
 export declare interface ReportJobStore {
     read(scope: string, id: string): Promise<ReportJobRecord | undefined>;
     candidates(now: number, limit: number): Promise<ReportJobRecord[]>;
+    /** Optional bounded retention capability; existing database adapters remain compatible. */
+    readTombstone?(scope: string, id: string): Promise<ReportJobTombstone | undefined>;
+    prune?(options: ReportJobPruneOptions): Promise<ReportJobPruneResult>;
     compareAndSwap(scope: string, id: string, expectedRevision: number | null, next: ReportJobRecord): Promise<boolean>;
 }
 
+export declare interface ReportJobStoreBudgetOptions {
+    maxRecords?: number;
+    maxBytes?: number;
+    maxResultBytes?: number;
+    controlReserveBytes?: number;
+    maxTombstones?: number;
+    maxTombstoneBytes?: number;
+}
+
+export declare interface ReportJobTombstone {
+    scope: string;
+    id: string;
+    revision: number;
+    status: Exclude<ReportJobStatus, "queued" | "running">;
+    createdAt: number;
+    updatedAt: number;
+    attempt: number;
+    requestHash: string;
+    expiresAt: number;
+}
+
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
 declare interface ReportLoadContext {
     reportId: string;
@@ -567,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;
@@ -582,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;
@@ -874,7 +1089,7 @@ declare interface ReportTemplateReview {
 }
 
 declare interface ReportTemplateReviewIssue {
-    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output";
+    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output" | "params";
     severity: "error" | "warning";
     path: string;
     message: string;
@@ -919,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: {
@@ -950,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>;
 }
 
 /**
@@ -972,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;