logisheets-core 1.14.0 → 1.15.0

package/dist/field/index.d.ts

@@ -1,5 +1,3 @@
-import type { Value } from 'logisheets-web';
-import type { Violation } from '../validation/index.js';
 export type FieldTypeEnum = 'unspecified' | 'enum' | 'multiSelect' | 'datetime' | 'boolean' | 'string' | 'number' | 'image' | 'fieldRef' | 'multiSelectRef';
 export interface EnumValue {
     id: string;
@@ -25,27 +23,3 @@ export interface FieldSetting {
     refBlockId?: number;
     refFieldName?: string;
 }
-export interface CellRef {
-    sheetIdx: number;
-    row: number;
-    col: number;
-}
-/** A field column: its constraints plus the data cells that belong to it. */
-export interface FieldColumn {
-    field: Pick<FieldSetting, 'name' | 'required' | 'unique'>;
-    cells: readonly CellRef[];
-    /**
-     * Allowed values for membership-constrained fields (enum / multiSelect /
-     * fieldRef / multiSelectRef). When provided, every non-empty cell value
-     * must appear here. The caller resolves the candidate set — for enums it
-     * is the enum labels; for fieldRef it is the referenced field's values.
-     * Leave undefined for fields with no membership constraint.
-     */
-    allowed?: readonly string[];
-}
-/**
- * Check `required` and `unique` across every field column and return all
- * violating cells. Pure: the caller supplies `getValue` (WorkbookOps wraps the
- * engine), so this runs identically in the browser and on Node.
- */
-export declare function checkFieldConstraints(columns: readonly FieldColumn[], getValue: (sheetIdx: number, row: number, col: number) => Value): Violation[];

package/dist/field/index.js

@@ -1,70 +1,25 @@
-// Field model + non-formula field constraints (required / unique).
+// The field AUTHORING model — what a composer UI edits before it becomes a
+// schema field.
 //
-// The field type model is lifted verbatim from the browser's block-composer so
-// the App, the data-gateway craft, and a Node runtime all share one source of
-// truth for what a field is. The constraint *checks* here are pure logic over
-// values read through an injected port — the engine just supplies the values.
+// This is the shape the browser's block-composer works in, shared so the App,
+// the data-gateway craft and a Node runtime agree on what a field is while it
+// is being authored. It is NOT the source of truth for what a field IS: that is
+// the engine schema, which carries the declaration and persists it (see
+// design/block-field-semantics.md). This model is what you fill in to produce
+// one.
 //
-// Formula-based validation lives in ../validation; this module covers the two
-// constraints that aren't formulas: `required` (no empty cells) and `unique`
-// (no duplicate values within a field column).
-import { isValueEmpty } from '../value/index.js';
-const isEmpty = isValueEmpty;
-/** Stable string key for duplicate detection. */
-function valueKey(v) {
-    const x = v;
-    return `${x.type}:${String(x.value)}`;
-}
-/** The cell's value as the plain text used for membership comparison. */
-function valueText(v) {
-    const x = v;
-    return String(x.value);
-}
-/**
- * Check `required` and `unique` across every field column and return all
- * violating cells. Pure: the caller supplies `getValue` (WorkbookOps wraps the
- * engine), so this runs identically in the browser and on Node.
- */
-export function checkFieldConstraints(columns, getValue) {
-    const out = [];
-    for (const { field, cells, allowed } of columns) {
-        const seen = new Map();
-        const allowedSet = allowed ? new Set(allowed) : undefined;
-        for (const cell of cells) {
-            const v = getValue(cell.sheetIdx, cell.row, cell.col);
-            const empty = isEmpty(v);
-            if (field.required && empty) {
-                out.push({
-                    ...cell,
-                    kind: 'required',
-                    message: `Field "${field.name}" is required`,
-                });
-                continue;
-            }
-            if (empty)
-                continue;
-            if (allowedSet && !allowedSet.has(valueText(v))) {
-                out.push({
-                    ...cell,
-                    kind: 'membership',
-                    message: `Value "${valueText(v)}" is not an allowed option for field "${field.name}"`,
-                });
-                continue;
-            }
-            if (field.unique) {
-                const key = valueKey(v);
-                if (seen.has(key)) {
-                    out.push({
-                        ...cell,
-                        kind: 'duplicate',
-                        message: `Duplicate value in unique field "${field.name}"`,
-                    });
-                }
-                else {
-                    seen.set(key, cell);
-                }
-            }
-        }
-    }
-    return out;
-}
+// Formula-based validation lives in ../validation.
+export {};
+// The `required` / `unique` / membership CHECKS used to live here as a second,
+// independent implementation over an injected value port. They are gone: a
+// field that declares `required`, `unique`, `enum`/`multiSelect` or `fieldRef`
+// now has the matching rule generated by the engine from the declaration
+// (crates/controller/src/block_manager/derived_rules.rs), installed as a
+// per-record validation shadow, and reported through the same channel as every
+// other rule — the warning marker, `list_violations`, and the
+// `overrideValidation` write gate.
+//
+// Two implementations of one constraint is how this area went wrong: they did
+// not even agree on what "the same value" meant (`type:value` here,
+// COUNTIF's stringified value in the engine), so the number 1 and the text "1"
+// collided in one and not the other. See design/block-field-semantics.md §2.3.

package/dist/format/index.d.ts

@@ -6,7 +6,7 @@ export interface FontStyle {
     color?: string;
     size?: number;
     strike?: boolean;
-    /** Font family name, e.g. "Arial", "Times New Roman", "微软雅黑". */
+    /** Font family name, e.g. "Arial", "Times New Roman", "Microsoft YaHei". */
     name?: string;
 }
 export declare function generateFontPayload(sheetIdx: number, data: SelectedData, update: FontStyle): readonly Payload[];

package/dist/ops/index.d.ts

@@ -1,7 +1,7 @@
 import type { Payload, ActionEffect, SelectedData, Alignment, StPatternType, Value, SheetCellId } from 'logisheets-web';
 import type { Client } from '../port.js';
 import { type ValidationRule, type Violation } from '../validation/index.js';
-import { type FieldColumn } from '../field/index.js';
+import type { FieldTypeEnum } from '../field/index.js';
 import { type FontStyle, type BorderBatchUpdate } from '../format/index.js';
 /**
  * Tells WorkbookOps whether to mark transactions temp (speculative). The
@@ -17,10 +17,203 @@ export interface FormBlockField {
     renderId: string;
     /** Per-field value-formula template (#FIELD("X") / #KEY); '' if free-form. */
     valueFormula?: string;
+    /**
+     * Per-field validation template (#PLACEHOLDER for the value under test,
+     * #FIELD("X") for a same-row sibling); '' when the field has no rule.
+     *
+     * This goes into the schema rather than staying host-side so the engine
+     * installs the per-record shadow itself — on bind AND on every row added
+     * later — and so one answer serves every reader: the warning marker, the
+     * `overrideValidation` write gate, and any other host.
+     */
+    validationFormula?: string;
+    /**
+     * Per-field editability template — FALSE installs a `UserEditable` lock the
+     * host permission layer reads.
+     *
+     * Carried here because a schema re-bind replaces the field wholesale: the
+     * three bind sites below used to send `editabilityFormulas: []` ("all
+     * None"), so editing a block through this layer silently dropped any
+     * editability template it had.
+     */
+    editabilityFormula?: string;
     /** Whether the field renders via a host-drawn (DIY) overlay. */
     diyRender: boolean;
     /** Number format applied to the field's render info. */
     numFmt?: string;
+    /** Declared type. Omitted reads as unspecified (free-form). */
+    fieldType?: FieldTypeEnum;
+    /** Enum set backing a `fieldType` of 'enum' / 'multiSelect'. */
+    enumSetId?: string;
+    /** Target of a `fieldType` of 'fieldRef' / 'multiSelectRef'. */
+    refTarget?: {
+        sheetId: number;
+        blockId: number;
+        fieldName: string;
+    };
+    /** What the field means, in prose, for whoever reads the block next. */
+    description?: string;
+    /** Every record must carry a value here. */
+    required?: boolean;
+    /** No two records may carry the same value here. */
+    unique?: boolean;
+    /** What a newly-added record starts with. */
+    defaultValue?: string;
+    /**
+     * Who may write to this field's cells: `'inherit'` (the block's own owner
+     * rules) | `'ownerOnly'` | `'anyone'`.
+     *
+     * Declared on the schema so every host reads the same answer — it was the
+     * last field-level rule that lived only in the browser's own field store,
+     * as a tri-state `userEditable` boolean. The engine persists and answers;
+     * it does not enforce, because it does not know who is writing.
+     */
+    writePolicy?: 'inherit' | 'ownerOnly' | 'anyone';
+}
+/**
+ * An option list a field can draw from, as the engine stores it.
+ *
+ * Ids and labels only. A variant's COLOUR is presentation and stays in the
+ * host, keyed by variant id — the engine needs the options in order to judge a
+ * value and needs nothing else.
+ */
+export interface EnumSetDecl {
+    id: string;
+    name?: string;
+    variants: ReadonlyArray<{
+        id: string;
+        label?: string;
+    }>;
+}
+/**
+ * How an analysis field aggregates the field it reads. Every one lowers to
+ * `FUNC(BLOCKREFSB(...))` in the engine, which is why adding one is a one-line
+ * change there and none here.
+ *
+ * `COUNT` counts numbers, `COUNTA` counts values that are simply THERE — over
+ * `10, 20, "n/a", <blank>` they say 2 and 3. In a pivot, COUNT counts matching
+ * records and COUNTA counts the ones whose measure is filled in.
+ */
+export type AggFunc = 'SUM' | 'COUNT' | 'COUNTA' | 'AVERAGE' | 'MIN' | 'MAX';
+/** One field of an analysis block: what it aggregates, and how. */
+export interface AnalysisAggregate {
+    /** Field name of the SOURCE block. */
+    field: string;
+    func: AggFunc;
+}
+/** One column of the block being analysed, as the analysis needs to see it. */
+export interface AnalysisSourceField {
+    name: string;
+    /**
+     * Whether the source DECLARES this field a number. Not whether its cells
+     * currently hold numbers: guessing from the data totals an id column, and
+     * leaves a still-empty column out of a total it belongs in.
+     */
+    isNumber: boolean;
+    /**
+     * The source column's number format, carried onto the total so a sum of
+     * currency reads as currency.
+     */
+    numFmt?: string;
+}
+/**
+ * Whether the result of `func` over a column is still measured in that
+ * column's units, and so should carry its number format.
+ *
+ * A sum, an average, a minimum or a maximum of a currency column is currency.
+ * The counts are not: they answer "how many", so formatting one like the
+ * column it counts would print "$3" for three orders. These are the aggregates
+ * whose result changes what is being measured.
+ */
+export declare function aggregateKeepsFormat(func: AggFunc): boolean;
+/** The block being analysed. */
+export interface AnalysisSource {
+    sheetIdx: number;
+    blockId: number;
+    /** Its ref name — used in the new block's description, not in a formula. */
+    refName: string;
+    rowStart: number;
+    rowCnt: number;
+    colStart: number;
+    /** Fields in COLUMN order, so the analysis's columns line up with them. */
+    fields: readonly AnalysisSourceField[];
+    /** Which column is the key — where the label goes. */
+    keyIdx: number;
+}
+/**
+ * SUM over every field the source declares a number.
+ *
+ * A default is only possible because the declaration exists: this is what the
+ * field-type work in `design/block-field-semantics.md` bought — before it, a
+ * caller could only guess from the data.
+ */
+export declare function defaultAnalysisAggregates(fields: readonly AnalysisSourceField[]): AnalysisAggregate[];
+/**
+ * How a pivot orders the distinct values it turns into rows and columns.
+ *
+ * `custom` takes the sequence from `orderValues`; values it does not mention
+ * follow in ascending order rather than disappearing, because a hidden group
+ * is the failure a pivot must never commit silently.
+ */
+export type DimOrder = 'ascending' | 'firstSeen' | 'custom';
+/** One condition a source record must meet to be counted by a pivot. */
+export interface PivotFilter {
+    field: string;
+    /** Spreadsheet condition syntax: `">100"`, `"East"`, `"<>closed"`. */
+    criteria: string;
+}
+/**
+ * A pivot column that is declared rather than derived.
+ *
+ * A plain cross-tab needs none of these: each column's name IS the dimension
+ * value and the block's recipe supplies the rest. These exist for the two
+ * things that cannot express — a ROW TOTAL (`colValue: null`, spanning every
+ * value) and a SECOND MEASURE (`measure` / `func` of its own).
+ *
+ * A refresh leaves declared columns alone: they were never derived from the
+ * data, so the data cannot justify removing them.
+ */
+export interface PivotColumnSpec {
+    /** Column name in the pivot. */
+    name: string;
+    /** Which column-dimension value it filters on; `null` spans every one. */
+    colValue: string | null;
+    measure?: string;
+    func?: AggFunc;
+}
+/** The block a pivot analyses, as the create needs to see it. */
+export interface PivotSource {
+    sheetIdx: number;
+    blockId: number;
+    /** Its ref name — used in the new block's description, not in a formula. */
+    refName: string;
+    rowStart: number;
+    rowCnt: number;
+    colStart: number;
+    /**
+     * Number format per SOURCE field name, for the pivot to inherit: a cell of
+     * a pivot is an aggregate of one source column, so a SUM of a currency
+     * column should read as currency rather than as a bare number.
+     *
+     * Optional — omit it and the pivot is left unformatted, which is what
+     * every caller got before this existed.
+     */
+    numFmts?: Readonly<Record<string, string | undefined>>;
+}
+/** What a refresh actually changed. */
+export interface PivotRefresh {
+    /** Groups that appeared in the source and now have a row. */
+    addedKeys: string[];
+    /** Rows the source no longer justifies. */
+    removedKeys: string[];
+    addedFields: string[];
+    removedFields: string[];
+    /**
+     * Source records with a blank dimension. They are in NO cell of the pivot,
+     * so its grand total is short by their measure — a refresh cannot fix
+     * that, only report it.
+     */
+    unassignedRecords: number;
 }
 /**
  * High-level workbook operations bound to one engine {@link Client}.
@@ -141,6 +334,8 @@ export declare class WorkbookOps {
         refName: string;
         keyIdx: number;
         fields: readonly FormBlockField[];
+        /** Option lists the fields reference; written in the same transaction. */
+        enumSets?: readonly EnumSetDecl[];
     }): Promise<void>;
     /**
      * Turn an EXISTING cell region into a form-backed block in place: like
@@ -158,6 +353,8 @@ export declare class WorkbookOps {
         refName: string;
         keyIdx: number;
         fields: readonly FormBlockField[];
+        /** Option lists the fields reference; written in the same transaction. */
+        enumSets?: readonly EnumSetDecl[];
     }): Promise<void>;
     /**
      * Edit an EXISTING form-backed block: rename it, re-type / re-formula its
@@ -187,7 +384,284 @@ export declare class WorkbookOps {
         refName: string;
         keyIdx: number;
         fields: readonly FormBlockField[];
+        /** Option lists the fields reference; written in the same transaction. */
+        enumSets?: readonly EnumSetDecl[];
+    }): Promise<void>;
+    /**
+     * Rewrite ONE kind of per-field rule on a block, leaving the others alone.
+     *
+     * `formulas` is one entry per field, in the schema's field order — a rule
+     * or `''` for none. The other two rule kinds are sent empty, which the
+     * engine reads as "don't touch these", so editing a validation rule cannot
+     * clear the value formulas standing next to it.
+     *
+     * Every existing row is re-materialized from the new rule, so this is also
+     * how a rule is removed: pass `''` for that field.
+     */
+    setFieldRules(opts: {
+        sheetIdx: number;
+        blockId: number;
+        kind: 'value' | 'validation' | 'editability';
+        formulas: readonly string[];
     }): Promise<void>;
+    /**
+     * Create the block that analyses `source`: a totals row placed directly
+     * below it, declaring what it analyses and how each of its fields
+     * aggregates. See `design/block-analysis.md`.
+     *
+     * **No formula is sent.** The engine generates each aggregate field's
+     * formula from the declaration, which is what makes renaming a source
+     * field rebuild the total instead of silently zeroing it. A field with no
+     * aggregate stays an ordinary cell — that is the label column, and the
+     * label is also the key the result is addressed by
+     * (`BLOCKREF(refName, label, field)`).
+     *
+     * One transaction, so it is one undo, and so a reader between two payloads
+     * never sees a one-row table it would mistake for a record.
+     *
+     * Returns what it aggregated, in column order, for the caller to report.
+     */
+    createAnalysisBlock(opts: {
+        source: AnalysisSource;
+        blockId: number;
+        refName: string;
+        label: string;
+        /**
+         * Which source fields to aggregate and how. Omit for
+         * {@link defaultAnalysisAggregates} — SUM over every field the source
+         * DECLARES as a number.
+         */
+        aggregates?: readonly AnalysisAggregate[];
+    }): Promise<readonly AnalysisAggregate[]>;
+    /**
+     * Change WHAT an existing analysis block computes — which source fields it
+     * aggregates, with which function, and the label its row is addressed by.
+     *
+     * The shape never changes: an analysis block is one row with one column
+     * per source field, so an edit is a re-bind and nothing else. That is the
+     * whole difference from {@link editPivot}, where changing the recipe
+     * changes how many rows and columns there are.
+     *
+     * Exists so an analysis can be arrived at in STEPS. The first guess (sum
+     * every number) is often nearly right and occasionally wrong in one
+     * column, and without this the only remedy was to delete the block and
+     * build it again — losing its ref name, and with it every formula pointing
+     * at it.
+     */
+    editAnalysisBlock(opts: {
+        sheetIdx: number;
+        /** The analysis block being edited. */
+        blockId: number;
+        /** Its ref name, which the re-bind has to restate. */
+        refName: string;
+        /** The block it analyses, for its field list and number formats. */
+        source: AnalysisSource;
+        aggregates: readonly AnalysisAggregate[];
+        /**
+         * A new row label, or omit to leave it alone. Rewriting it re-aims
+         * nothing — unlike a pivot key, an analysis block's label is just the
+         * name its single row is addressed by.
+         */
+        label?: string;
+        /** Where the block sits, needed only when `label` is given. */
+        rowStart?: number;
+        colStart?: number;
+    }): Promise<readonly AnalysisAggregate[]>;
+    /**
+     * The label row a pivot carries directly above itself, as `cellInput`
+     * payloads.
+     *
+     * A pivot's column names are DATA — they are the column dimension's own
+     * values — but they live on the schema, which means the raw sheet shows a
+     * grid of numbers with nothing to say what the columns are. Everything
+     * that is not our own UI sees it that way: another tool, a person reading
+     * the file, and Excel, whose pivot tables require the labels to be in
+     * cells. So the pivot writes them there.
+     *
+     * The row sits OUTSIDE the block, immediately above it. Inside would break
+     * what a block is: every row of a block is a record addressed by its key,
+     * so a header row would become a record keyed "region" — captured by
+     * `#KEY`, counted by the key-uniqueness guard, and aggregated by anything
+     * reading the block.
+     *
+     * Rewritten in full whenever the column set can have changed, because a
+     * label left behind from a previous shape is worse than no label: it names
+     * a column that is now something else.
+     */
+    private pivotHeaderRow;
+    /**
+     * The number format each of a pivot's columns should carry, in the order
+     * the columns are declared (`[key, ...value columns]`).
+     *
+     * Every column of a pivot aggregates ONE source column, so it is formatted
+     * like that column. Which source column differs per kind:
+     *
+     * - the key column holds the row dimension's own values;
+     * - a derived column is `func(measure)` from the recipe;
+     * - a declared column (a row total, a second measure) names its own, and
+     *   falls back to the recipe's for whatever it leaves out.
+     *
+     * A COUNT column is deliberately plain — see {@link aggregateKeepsFormat}.
+     *
+     * Returned as `''` rather than `undefined` for "no format", because the
+     * payload is also how a format is CLEARED, and a refresh re-states every
+     * column: `refreshPivot` reassigns render ids by position, so a column
+     * that appears shifts the ids after it, and only restating all of them
+     * keeps each format on the column it belongs to.
+     */
+    private pivotColumnFormats;
+    /**
+     * Create a pivot of `source`: a cross-tab whose rows are the distinct
+     * values of `rowDim`, whose columns are the distinct values of `colDim`,
+     * and whose cells are `func` over `measure`.
+     *
+     * **One transaction**, so it is one undo — which is why it asks the engine
+     * for the shape BEFORE creating the block (`pivotPlanFor`). Creating first
+     * and reshaping after would leave an empty declared pivot as an
+     * intermediate state and take two undos to remove.
+     *
+     * No formula is sent. The engine generates every cell from the recipe plus
+     * the cell's own row key and field name, which is what makes renaming a
+     * source field rebuild the pivot instead of breaking it.
+     *
+     * Returns the shape it created, for the caller to report.
+     */
+    createPivot(opts: {
+        source: PivotSource;
+        blockId: number;
+        refName: string;
+        rowDim: string;
+        /** Omit for a grouped pivot: one value column, no cross-tab. */
+        colDim?: string;
+        measure: string;
+        func: AggFunc;
+        order?: DimOrder;
+        /** The sequence for `order: 'custom'`. */
+        orderValues?: readonly string[];
+        /** Which source records to count at all. Omit to count every one. */
+        filters?: readonly PivotFilter[];
+        /**
+         * Columns beyond the derived ones — a row total, a second measure.
+         * Appended after the cross-tab's own columns.
+         */
+        extraColumns?: readonly PivotColumnSpec[];
+        /**
+         * Name of the pivot's single value column when `colDim` is omitted.
+         * Ignored for a real cross-tab, whose column names ARE the dimension's
+         * values.
+         */
+        valueColumn?: string;
+    }): Promise<{
+        keys: string[];
+        fields: string[];
+        unassignedRecords: number;
+    }>;
+    /**
+     * Bring a pivot's SHAPE back in line with its source: add rows for groups
+     * that appeared, drop rows for groups that are gone, same for columns.
+     *
+     * Its numbers were never stale — they are live formulas. Only the set of
+     * rows and columns needs this, because no formula can add a row.
+     *
+     * One transaction, and the payload order is not negotiable
+     * (`design/block-pivot.md` §6): grow, write the keys, bind, shrink. Keys
+     * before the bind because `#KEY` is captured at materialization; grow
+     * before the bind because a field cannot bind to a column that does not
+     * exist; shrink after, so nothing is left bound to a vanishing column.
+     *
+     * Returns what changed, or `null` when the pivot was already current — so
+     * a caller can say "nothing to do" instead of reporting an empty refresh.
+     */
+    refreshPivot(opts: {
+        sheetIdx: number;
+        blockId: number;
+        /** The pivot's ref name, which the re-bind has to restate. */
+        refName: string;
+        /** Its key field's name — the column holding the row dimension. */
+        keyField: string;
+        /**
+         * The pivot's CURRENT schema fields, so a re-bind can restate any
+         * column that was declared by hand.
+         *
+         * Without them the re-bind would rewrite every column as a derived
+         * one, silently turning a row total into a column filtering on the
+         * literal value "Total" — which matches nothing and reads 0.
+         */
+        currentFields?: ReadonlyArray<{
+            field: string;
+            pivotColValue?: string;
+            pivotMeasure?: string;
+            pivotFunc?: string;
+        }>;
+        /**
+         * Number format per SOURCE field name, and the recipe the pivot runs,
+         * so a column the refresh ADDS is formatted like the columns beside it
+         * instead of arriving as a bare number.
+         *
+         * Both or neither: without the recipe there is no way to know which
+         * source column a derived column aggregates. Omit to leave every
+         * format alone.
+         */
+        formats?: {
+            numFmts: Readonly<Record<string, string | undefined>>;
+            measure: string;
+            func: AggFunc;
+        };
+    }): Promise<PivotRefresh | null>;
+    /**
+     * Change a pivot's RECIPE — what it groups by, what it measures, how, in
+     * what order, over which records — and reshape it to match, in one
+     * transaction.
+     *
+     * A recipe is not editable in place by hand: a pivot's numbers are
+     * generated from it, its column names ARE the column dimension's values,
+     * and its key column holds the row dimension's. Changing any of those by
+     * typing produces a table that says one thing and computes another —
+     * editing a row label does not re-aim the row, it relabels a group.
+     *
+     * Deliberately does NOT ask for the current plan. The commonest reason to
+     * edit is that the recipe has stopped resolving (a source field renamed
+     * out from under it, say), and planning the OLD recipe would fail exactly
+     * then. The caller states the block's present size instead, which it can
+     * always see.
+     *
+     * Payload order, for the same reasons as §6 with one addition: the RECIPE
+     * goes before the bind, because the bind is what regenerates every cell
+     * from it — set it after and the block re-materializes from the old one.
+     *
+     *   grow (if growing) → recipe → keys → bind → shrink (only if shrinking)
+     *
+     * Returns the shape it produced.
+     */
+    editPivot(opts: {
+        sheetIdx: number;
+        /** The pivot being edited. */
+        blockId: number;
+        /** Its ref name, which the re-bind has to restate. */
+        refName: string;
+        /** The block it analyses: what the new recipe is planned against. */
+        source: PivotSource;
+        /**
+         * Its present size, so the reshape knows whether it grows or shrinks.
+         * Asked for rather than planned, so a broken recipe can still be
+         * fixed — which is most of the point of this method.
+         */
+        currentRowCnt: number;
+        currentColCnt: number;
+        rowDim: string;
+        colDim?: string;
+        measure: string;
+        func: AggFunc;
+        order?: DimOrder;
+        orderValues?: readonly string[];
+        filters?: readonly PivotFilter[];
+        extraColumns?: readonly PivotColumnSpec[];
+        valueColumn?: string;
+    }): Promise<{
+        keys: string[];
+        fields: string[];
+        unassignedRecords: number;
+    }>;
     /**
      * Apply a caller-built payload list as one transaction (at the host's
      * temp-mode). Escape hatch for operations whose payload construction still
@@ -242,6 +716,4 @@ export declare class WorkbookOps {
      * interpretValidation instead.
      */
     checkValidations(rules: readonly ValidationRule[]): Promise<Violation[]>;
-    /** Check required / unique / membership field constraints. */
-    checkFieldConstraints(columns: readonly FieldColumn[]): Promise<Violation[]>;
 }