Execution, limits and recovery

Local execution

Use localExecution on createPivotController, or grid.pivot.engine.localExecution for the attached plugin. Keep a single analytical owner per grid.

let sourceRevision = 0;
const localExecution = {
  mode: 'cooperative' as const, budgetMs: 8,
  sourceRevision: () => sourceRevision,
};
// Supply localExecution to createPivotController({ report, source, localExecution }).
// Before changing accepted facts: sourceRevision++; then mutate; then refresh().

API	Type/default/units	Behavior
localExecution.mode	'cooperative'; runtime opt-in	Default omission retains synchronous timing
budgetMs	Number, default 8; milliseconds, greater than 0 and at most 50	Target between yields, not a deadline
sourceRevision	Required callback returning a stable value	Compared with Object.is; change before source mutation
autoLoad	Boolean, false	Start execution on controller creation
historyLimit	Nonnegative integer, 100	Zero disables undo history
Query axis offsets/limits	Nonnegative safe integers; omitted means complete local window	Zero limit means empty window
cancel()	No arguments	Settles pending work; prevents stale publication
dispose()	No arguments	Cancels work and releases subscriptions

Keep source membership, order and values stable until an operation settles. Source revision is a lease, not a deep snapshot; unannounced nested mutations cannot be reliably detected. Metadata admission is still synchronous. Opaque callbacks/getters/Proxy traps and atomic JavaScript operations can exceed the cooperative target. Remote scheduling, deadlines and database cancellation belong to the adapter/host.

Runtime resource API

PivotResourceLimits is runtime-only: pass resourceLimits to the standalone controller or engine.resourceLimits in native config. Each omitted metric is unbounded. Supplied values must be nonnegative safe integers; zero is valid. Unknown metrics, accessors or invalid policy shapes throw TypeError. Application/controller and selected engine policies intersect using the lower per-metric ceiling; reports cannot raise application ceilings.

Metric	Exact accounting unit	Example ceiling	What it does not measure
maxSourceSlots	Original selected array length, including holes	10000	Eligible facts, fields or heap
maxModelStateEntries	Cumulative entries created in instrumented model Map/Set/dictionary owners: group/aggregate buckets, hierarchies, collision/subtotal/calculation/semantic indexes, ranked provenance and remote materialization, including replicated indexes	200000	Unique members alone, all JS objects or bytes
maxRetainedAggregateValues	Cumulative raw aggregate input slots retained per destination occurrence	500000	Source length alone; one fact can contribute at several grains
maxModelRecords	Cumulative generated/owned record creations, including raw dictionaries and publication copies	50000	Nested objects or current live-record count
maxModelProperties	Cumulative first own top-level property creations on those records, including string/symbol metadata references	500000	Recursive payload size or subsequent overwrites
maxExportDataCells	Body plus pinned indexed row spans × exported leaf columns, labels/blanks included	100000	Only nonempty numeric cells
maxExportHeaderNodes	Header object occurrences, shared subtrees counted per occurrence	2000	Unique header identities
maxExportUtf8Bytes	Final escaped CSV/print HTML UTF-8 bytes, BOM/delimiters/markup included	2000000	Workbook ZIP size or heap
maxWorkbookXmlBytes	Sum of uncompressed XLSX XML part UTF-8 bytes	4000000	ZIP/container overhead or memory

Model counters are deterministic accounting in named SDK owners, not a global allocation interceptor. Nested application payloads and custom callback allocations stay outside them. Cumulative work is not refunded merely because temporary state is released. These example ceilings are application choices, not tested capacity promises.

Intent and contribution limits

PivotIntentLimits belongs to controller intentLimits or runtime engine.intentLimits. All metrics default to unbounded, use nonnegative safe integers and accept zero. Invalid policies throw; excess admitted intent raises WINDOW_LIMIT_EXCEEDED.

Metric	Unit
maxMetadataNodes	JSON container/scalar occurrences including root, excluding property keys
maxMetadataBytes	Canonical admitted projection JSON UTF-8 bytes, not heap
maxFilterNodes	Explicit WHERE/HAVING conditions, connectives, negations and HAVING list containers
maxMembershipValues	Membership operand occurrences, including report/native selections

engine.memberFilterLimits independently bounds transient contribution maxOwners, maxTuplesPerOwner, maxPredicates and maxBytes. Bytes count serialized intent: a complete request envelope or ordered active-owner [[ownerId, tuples], ...]; repeated references count per occurrence. Omitted metrics are unbounded and zero is valid. These limits do not establish tenant authorization.

SQL reference work limits

The optional SQLite analytical profile requires trusted workLimits:

Metric	Unit/default	Exclusions
maxDenseCoordinates	Each cube’s row-prefix × column-prefix product, including roots; required nonnegative safe integer	Scans, SQL workspace, heap
maxMaterializedRows	Cumulative rows written to operation-owned SQL temporary tables; copies count again; required nonnegative safe integer	Internal indexes, temp bytes, CPU
maxRankingMembers	Positive ranking-member ceiling, default 1000	All-purpose memory bound

These are reference/backend policies, not fields of PivotResourceLimits. An authorized cache hit performs zero new temporary work; tightening a work ceiling to zero does not invalidate an otherwise authorized cached response. Bound cache entries/bytes/TTL and reauthorize separately. Synchronous SQLite cannot interrupt an executing statement with AbortSignal.

Errors and recovery

Execution operations return committed, noop, prevented, superseded, cancelled or failed; only a commit publishes a new revision. Validate exceptions separately from asynchronous outcomes.

try {
  const outcome = await controller.refresh();
  if (outcome.status === 'failed') {
    console.error(outcome.error.message, outcome.error.code, outcome.error.details);
    // Keep controller.getSnapshot().view visible. Offer fewer facts/measures,
    // a smaller export, or a host-approved revised policy, then retry.
  }
} catch (error) {
  console.error('Invalid input or policy', error);
}

For resource refusals, bounded controller details contain stage, metric, limit, observed. observed: null means unavailable/not representable, not zero. Arbitrary provider payloads are excluded. Last committed view/revision remain usable after execution failure; source intent and retained view can have different sourceRevision/viewSourceRevision.

The runnable example commits six facts under a six-slot ceiling, refuses seven facts with WINDOW_LIMIT_EXCEEDED, checks unchanged revision, and successfully recovers with six facts. It also refuses an oversized CSV before retrying a smaller output.

Error/situation	Customer action
WINDOW_LIMIT_EXCEEDED	Reduce source/cardinality/export or obtain a host-approved limit change; retry
REVISION_MISMATCH	Refresh current registry/report/snapshot; never download stale output
INVALID_SELECTOR / INVALID_SUMMARY_TYPE	Select authorized fields/operations advertised by this engine
HIERARCHY_UNAVAILABLE / INVALID_HIERARCHY_PATH	Use a supported hierarchy/profile and valid typed paths
AUTH_REQUIRED / FORBIDDEN	Reauthenticate or request access; do not retry with client-supplied tenant metadata
Missing runtime binding / invalid report	Restore the named host binding or repair the document; preserve the accepted report

See exports and deployment acceptance. No logical counter promises hard heap, CPU, SQL preemption, latency or concurrency guarantees.