Repository navigation
Conversation
POST /api/v1/sources/records answers the rows of one source to a person whose profile names the source in records: only fields at show, in the columnar shape encode() reads, written in pieces by the compute worker that holds the data. Off by default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and a measurement Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… answer; accept record 0015 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ot send Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…read Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…onfig, privacy and host docs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… route does; docs and tests from the reviews Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 19, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #615
This adds the first piece of shared live reports:
POST /api/v1/sources/recordshands the rows of one source to a person who signed in, so a host application's backend can show a live report over a source only pivotkit-server reaches. It stores nothing and it is off by default. Record 0015 is set to accepted.What changes
"records": ["sales"]. The server's policy, a source's policy andfiles.policyrefuse the key.NOT_ALLOWED. A source the profile does not name answers the same, whether it exists or not.showleave. A field atvaluesorsummaryanswers 403NOT_ALLOWEDwithnotShown. A hidden field answers 400INVALID_INPUTexactly as a field that does not exist, and no answer names it. A view only says which fields are needed; its filters are not applied.{ columns, types, rowCount, dataAsOf, withheld, requestId, data }, the columnar shapeencodereads. Dates are ISO text without an offset (wall clock).records-writer.js). The main thread holds at most one piece.rest.records.maxRows(50,000),.maxCells(1,000,000),.concurrency(1, one per person),.idleMs(30 s) andsources.<id>.records.maxRows, which cannot be higher than the server's. 413LIMIT_EXCEEDEDcomes before the first byte, 503BUSYwithRetry-Afterbeyond the places. The defaults are a first guess, as the issue says.GET /sourcesadds"records": trueper source the caller may read. MCP gets no tool.check-configgets aRows (REST)section: per profile the sources and the fields that leave or stay; a problem for an unknown source id and for a static or signed token whose profile reads rows; warnings for a source without ashowfield, a profile whose default isshow, andrest.records.concurrencynot belowcompute.workers.recordslog line per answer: source, rows, columns, profile, the person asaudit.subjectsays. A cut answer is a warning withreason(idle,client,timeout,error).Measurement
npm run bench:records -w pivotkit-server, Node 26, Apple M4, 10 cores. One process per row, the REST handler in process, each answer read to its end. Cold: a fresh server reads the CSV. Warm: the worker kept the data.The issue expected a rows request to cost less CPU than a render. Cold, both cost about the same, since reading the source dominates. Warm, a rows request costs more CPU in pivotkit-server than a render of the same source (61 ms against 7 ms at 50,000 rows). The pivoting then moves to the browser, which this does not measure. 100,000 rows needed raised limits.
Tests
test/records.test.js(26 tests), each item of "Done when" on its own: show fields only and theencoderound trip; values/summary/hide never in an answer or error, also viafieldsand a view;NOT_ALLOWEDfor every caller without a person and without the right; a claim-bound parameter; the threeLIMIT_EXCEEDEDcases with their messages; a source limit above the server's;BUSYbeyond the cap and per person; a stalled reader losing its place; pieces; one piece per read; two people with different rights; the base headers on the answer and every error, andVary: Origin; theGET /sourcesflag; the log line; the four check-config items; the writer against pivotkit-core's data export; spellings of a hidden field, a view as JSON text, a reader that leaves, and a column without a header in check-config.npm test -w pivotkit-server,npm test -w pivotkit-mcp, the repository tests,npm run lint,npm run types,npm run pack:checkandzensical build --strictpass locally on macOS. Linux, Windows and the container image only run in CI.Open points
concurrencyof 1, one person who loads or reads slowly keeps others at 503BUSYfor up tocompute.timeMs. The docs say so. A shorter write limit or a short wait for a place would help; I left that for a follow-up.auth.toolScopescannot name the route, since it is no operation.rest.requiredScopesand the source's scopes apply.Docs checked
REST reference (route table, profile keys,
#recordswith setup, who, fields, limits, the host recipe, log and sizing; the new#headers; limits and errors), OpenAPI, sources, security, privacy (overview row and the "leaves or stays" table), upgrading, features, what reaches an AI model, embed recipes, the package README, CHANGELOG, the package AGENTS.md, record 0015 and its index. I searcheddocs/forrest.concurrency,results: trueand the REST route list.The upgrading section and the CHANGELOG entry sit where the release PR #634 also writes, so one of the two needs a merge of main.
🤖 Generated with Claude Code