Remote adapters, capabilities and security
Integration contract
Section titled “Integration contract”Use a public PivotEngineAdapter or PivotRemoteStore; HttpPivotRemoteStore supplies HTTP transport. Remote API reference documents typed request/response envelopes and constructor options. Bind the engine through runtime configuration, not serialized executable code. Set aggregationSemantics: 'server' to reject accidental local rebinding.
| Surface | SDK responsibility | Host/backend responsibility |
|---|---|---|
| Load | Map/validate query and response, correlate revisions, publish accepted view | Execute complete authorized scope, return windows and truthful counts |
| Members | filterValues(request, signal) posts typed queries | WHERE/search before distinct paging; typed values and matching total count |
| Drillthrough | Typed prefix/ranking lineage and cancellation | Reauthorize fields and original facts; retain duplicates and stable fact order |
| Complete export | Validate complete snapshot/identity/output bounds | Atomic operation-time snapshot, original-fact totals, no truncation |
| Credentials | Runtime authProvider, optional fetch credentials | Session/token validation, CORS/CSRF, tenant and operation policy |
| Capabilities | Preflight unavailable operations | Truthful implementation and independent admission at every endpoint |
HttpPivotRemoteStore routes include /api/pivot/filter-values and /api/pivot/export under baseUrl; advertise them only after implementing the routes. credentials: 'include' explicitly enables required cross-origin cookies; omission keeps fetch’s default policy. Never persist tokens, cookies, headers or transport handles in report JSON. Follow the existing remote store integration for a runnable transport mount.
Advertise only implemented profiles
Section titled “Advertise only implemented profiles”| Capability/profile | Practical boundary |
|---|---|
query | Registered operation subsets, axis membership and depth; depth alone is not hierarchy support |
filterValues | Backend member choices; loaded aggregate rows are not a complete domain |
calculations | Corresponding complete-context backend calculations, not local math over pages |
ranking | Declared contextual ranking/Other/drill contract; root first-row profile in reference |
sort plus summarySort | Version 1 opposite-grand-total prefix ordering; selected tuple sort deferred |
fullExport | Implemented complete atomic bounded export endpoint |
Standard remote summaries are sum, avg, min, max, count, distinct, subject to registry authorization. Local V2 operation descriptors, arbitrary callbacks, derived fields and independent leaf/group/total override semantics are not portable SQL promises. Reject unknown summary properties rather than stripping them and pretending equivalence.
Executable SQLite reference
Section titled “Executable SQLite reference”The repository’s packages/pivot/server-reference/ is not shipped in the npm package. It demonstrates a caller-owned Node DatabaseSync, parameterized values, allowlisted simple identifiers, trusted field registry and tenant-scoped SQL. It is neither a hosted service nor production-driver certification.
| Profile | Opt-in and behavior |
|---|---|
| Flat baseline | Scalar authorized row/column selectors, at most one of each; SQL aggregates, WHERE/HAVING, members, drill and bounded flat complete export |
| Distinct acceptance | Separate duplicate/null/empty/scalar fixture; SQL collation/type semantics |
| Hierarchy | Trusted ordered rowSelectors/columnSelectors, up to eight levels per axis; prefix expansion, subtotals and grand totals; both measure orientations in complete export |
| Analytical | Trusted analytical work limits; contextual calculations/formulas, first-row root ranking/Other and complete-prefix summary sorting |
Baseline load windows are at most 40 rows/16 columns; member and fact pages are at most 200. These are reference limits, not universal SDK capacity. Analytical dense-coordinate and temporary-row counters are separate work units. Date buckets, arbitrary SQL expressions and general custom aggregates require separate implementation/acceptance.
For repository developers, run pnpm --filter @revolist/pivot test:backend on a runtime with node:sqlite, and test:backend:http for loopback HTTP integration. The recorded SQL baseline used Node 26.7.0/SQLite 3.53.4. The HTTP suite is separate from browser rendering. Use backend validation to qualify your own adapters; baseline acceptance does not automatically qualify optional analytical profiles.
Authentication and tenant isolation
Section titled “Authentication and tenant isolation”The authenticated reference handler calls host authenticate and operation/view authorize before consuming its deferred body stream. Its default body bound is 1 MiB; trusted configuration may set maxBodyBytes. Derive tenant, database/table/view, allowed registry fields, exact axes and policy ceilings from trusted host state. Client report metadata cannot choose them. Parameterize values and reject unauthorized selectors before SQL/cache access.
Reference errors retain 401/403/409/400 for known failures and redact unexpected failures to 500. Authentication is supplied by the application; synthetic reference credentials are not a deployable identity system.
An optional bounded load cache requires trusted dataset watermark, authorization scope and policy revision; absent/empty identity inputs bypass caching. Keys separate tenant, view/version, subject and policy/data identity. Every hit still reauthenticates, reauthorizes and validates the current registry. Do not cache denials, drill facts, members or exports using this load-cache contract. Configure entry/byte/TTL limits independently of SQL work budgets.
Deployment acceptance
Section titled “Deployment acceptance”Choose a trusted unique nonnull immutable fact key and explicit ordering. SQL peer ties follow authorized fact-key order; local peers follow source occurrence order. Qualify the real driver’s transaction/snapshot behavior, deadlines, cancellation, query plans, temp storage, concurrency, authorization revocation and data consistency. A per-operation snapshot does not pin data across separate load/export requests.
Synchronous SQLite checks cancellation between statements and cannot preempt an active statement. SDK cancellation can prevent publication while backend work continues. Secure deployment, identity, backups, rate limiting and representative workload/security acceptance remain host work. See compatibility and current evidence.