@cyanheads/brapi-mcp-server 0.4.14 → 0.5.0

package/dist/mcp-server/tools/shared/find-helpers.d.ts

@@ -2,8 +2,8 @@
  * @fileoverview Shared building blocks for `find_*` tools — Zod fragments for
  * common inputs (alias, loadLimit, extraFilters), utilities to merge named
  * filters with the passthrough map, a generic distribution aggregator, and
- * the dataset-spillover handler that turns a "too many rows" result into a
- * DatasetStore handle.
+ * the spillover handler that turns a "too many rows" result into a canvas
+ * dataframe handle.
  *
  * @module mcp-server/tools/shared/find-helpers
  */
@@ -11,14 +11,14 @@ import { type Context, type HandlerContext, z } from '@cyanheads/mcp-ts-core';
 import type { ServerConfig } from '../../../config/server-config.js';
 import type { BrapiClient, BrapiEnvelope, BrapiPagination, BrapiRequestOptions, ResolvedAuth } from '../../../services/brapi-client/index.js';
 import type { BrapiDialect } from '../../../services/brapi-dialect/index.js';
+import type { CanvasBridge, RegisterDataframeResult } from '../../../services/canvas-bridge/index.js';
 import type { CapabilityProfile } from '../../../services/capability-registry/types.js';
-import type { DatasetMetadata, DatasetStore } from '../../../services/dataset-store/index.js';
 import type { RegisteredServer } from '../../../services/server-registry/index.js';
 /** True when the thrown value is an upstream 404 surfaced by the BrAPI client. */
 export declare function isUpstreamNotFound(err: unknown): boolean;
-/** Upper cap on how many rows we'll pull for DatasetStore spillover per call. */
+/** Upper cap on how many rows we'll pull for canvas dataframe spillover per call. */
 export declare const MAX_SPILLOVER_ROWS = 50000;
-/** Hard cap on how many BrAPI pages we'll traverse when building a dataset. */
+/** Hard cap on how many BrAPI pages we'll traverse when building a dataframe. */
 export declare const MAX_SPILLOVER_PAGES = 50;
 export declare const AliasInput: z.ZodOptional<z.ZodString>;
 export declare const LoadLimitInput: z.ZodOptional<z.ZodNumber>;
@@ -90,18 +90,18 @@ export declare function companionRequestOptions(connection: RegisteredServer, di
  */
 export declare function computeDistribution<T>(rows: readonly T[], accessor: (row: T) => string | readonly string[] | undefined | null): Record<string, number>;
 /**
- * Render the standardized header line for `find_*` tools. When a dataset
- * spillover is present, surfaces the dataset row count alongside the
+ * Render the standardized header line for `find_*` tools. When a dataframe
+ * spillover is present, surfaces the dataframe row count alongside the
  * in-context count and the upstream total — `{returned} of {total}` alone
  * hides the middle number and confuses readers when filters miss server-
- * side and the dataset row count diverges from both.
+ * side and the dataframe row count diverges from both.
  */
 export declare function renderFindHeader(opts: {
     noun: string;
     alias: string;
     returnedCount: number;
     totalCount: number;
-    dataset?: {
+    dataframe?: {
         rowCount: number;
         expiresAt?: string;
     } | undefined;
@@ -127,12 +127,13 @@ export interface LoadedRows<T> {
 /**
  * Pull rows up to `loadLimit` on a single page. If the server reports more
  * rows than the limit, leave the rest behind — callers decide whether to
- * spill via `spillToDataset`.
+ * spill via `spillToCanvas`.
  */
 export declare function loadInitialPage<T>(client: BrapiClient, connection: RegisteredServer, path: string, filters: Record<string, unknown>, loadLimit: number, ctx: Context): Promise<LoadedRows<T>>;
 /** Pull the first page for either a GET list endpoint or POST /search route. */
 export declare function loadInitialFindPage<T>(client: BrapiClient, connection: RegisteredServer, route: FindRoute, loadLimit: number, ctx: Context): Promise<LoadedRows<T>>;
 export interface SpillInput<T> {
+    bridge: CanvasBridge;
     client: BrapiClient;
     connection: RegisteredServer;
     ctx: Context;
@@ -147,8 +148,8 @@ export interface SpillInput<T> {
     route?: FindRoute;
     /**
      * Optional client-side predicate applied to every row (first-page + spilled)
-     * before persistence. When present, only rows that pass are persisted to
-     * DatasetStore and returned in `fullRows`. The unfiltered upstream total is
+     * before persistence. When present, only rows that pass are registered on
+     * the canvas and returned in `fullRows`. The unfiltered upstream total is
      * preserved separately on the LoadedRows envelope so distributions and
      * headers can still report the true upstream size.
      */
@@ -157,54 +158,53 @@ export interface SpillInput<T> {
      * Optional client-side transform applied to every row (first-page + spilled)
      * before any predicate filter runs. Used to normalize sparse / duplicated
      * upstream payloads (e.g. dedup'ing CassavaBase's 11×-repeated synonym
-     * arrays) so the in-context view, the persisted dataset, and the canvas
-     * dataframe all see the same cleaned shape. Runs before `rowFilter`.
+     * arrays) so the in-context view and the canvas dataframe see the same
+     * cleaned shape. Runs before `rowFilter`.
      */
     rowMapper?: (row: T) => T;
     source: string;
-    store: DatasetStore;
     /** Total reported by the server on the first page. */
     totalCount: number;
 }
 export interface SpillResult<T> {
-    dataset: DatasetMetadata;
-    /** Rows that were persisted (post-filter when `rowFilter` was supplied). */
+    dataframe: RegisterDataframeResult;
+    /** Rows that were registered (post-filter when `rowFilter` was supplied). */
     fullRows: T[];
     pagesFetched: number;
 }
 /**
- * Shape of the dataset handle returned inline by `find_*` tools. Drops the
- * provenance fields (source/baseUrl/query) since those are internal and
- * available via `brapi_manage_dataset summary`.
+ * Shape of the dataframe handle returned inline by `find_*` tools. The
+ * dataframe is the canvas table holding every row beyond `loadLimit`; query
+ * it with `brapi_dataframe_query` for SQL access or describe it with
+ * `brapi_dataframe_describe` for schema + provenance.
  */
-export declare const DatasetHandleSchema: z.ZodObject<{
-    datasetId: z.ZodString;
+export declare const DataframeHandleSchema: z.ZodObject<{
+    tableName: z.ZodString;
     rowCount: z.ZodNumber;
-    sizeBytes: z.ZodNumber;
     columns: z.ZodArray<z.ZodString>;
     createdAt: z.ZodString;
     expiresAt: z.ZodString;
     truncated: z.ZodOptional<z.ZodBoolean>;
     maxRows: z.ZodOptional<z.ZodNumber>;
-    dataframe: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type DatasetHandle = z.infer<typeof DatasetHandleSchema>;
+export type DataframeHandle = z.infer<typeof DataframeHandleSchema>;
 /**
- * Render a DatasetHandle as bullet lines, matching the existing find_* tool
+ * Render a DataframeHandle as bullet lines, matching the existing find_* tool
  * format. Centralized so the truncated/maxRows fields surface consistently.
  * `expiresAt` is paired with a human-readable `expires in Xh / Xd` so the
  * agent doesn't have to subtract dates to know when the handle goes stale.
  */
-export declare function renderDatasetHandle(handle: DatasetHandle): string[];
+export declare function renderDataframeHandle(handle: DataframeHandle): string[];
 /**
  * Render an absolute `expiresAt` timestamp as a relative human label
  * (`expires in 24h`, `expires in 30m`, `expired 5m ago`). Coarsens to the
  * most useful unit so the value reads at a glance.
  */
 export declare function formatExpiresIn(expiresAt: string, now?: Date): string;
-/** Project a `DatasetMetadata` to the in-context handle shape. */
-export declare function toDatasetHandle(metadata: DatasetMetadata): DatasetHandle;
+/** Project a `RegisterDataframeResult` to the inline handle shape. */
+export declare function toDataframeHandle(result: RegisterDataframeResult): DataframeHandle;
 export interface MaybeSpillInput<T> {
+    bridge: CanvasBridge;
     client: BrapiClient;
     connection: RegisteredServer;
     ctx: Context;
@@ -215,7 +215,7 @@ export interface MaybeSpillInput<T> {
     route?: FindRoute;
     /**
      * Optional client-side predicate applied to every row before persistence.
-     * Forwarded to `spillToDataset`. When present and no spillover happens, the
+     * Forwarded to `spillToCanvas`. When present and no spillover happens, the
      * first-page rows are also filtered before being returned.
      */
     rowFilter?: (row: T) => boolean;
@@ -227,38 +227,49 @@ export interface MaybeSpillInput<T> {
     source: string;
     /**
      * Optional request overrides for spillover page pulls. Useful when a tool
-     * wants dataset persistence to be best-effort under a tighter latency
-     * budget than the first page.
+     * wants dataframe materialization to run under a tighter latency budget
+     * than the first page.
      */
     spillRequestOptions?: BrapiRequestOptions;
-    store: DatasetStore;
     /** Optional warning sink. When supplied, spillover failures degrade to rows-only output. */
     warnings?: string[];
 }
 export interface MaybeSpillResult<T> {
-    dataset?: DatasetHandle;
+    dataframe?: DataframeHandle;
     /** Row set after `rowFilter` (when supplied), spilled or first-page only. */
     fullRows: T[];
 }
 /**
- * Wrap `spillToDataset` with the "only spill when hasMore and totalCount >
+ * Wrap `spillToCanvas` with the "only spill when hasMore and totalCount >
  * loadLimit" guard that every `find_*` tool replicates. When no spillover is
- * needed, returns the first-page rows untouched. When it is, persists the
- * union to DatasetStore and returns both the full set and the handle.
+ * needed, returns the first-page rows untouched. When it is, materializes
+ * the union as a canvas dataframe and returns both the full set and the
+ * handle.
  */
 export declare function maybeSpill<T extends Record<string, unknown>>(input: MaybeSpillInput<T>): Promise<MaybeSpillResult<T>>;
 /**
- * Pull every remaining page up to MAX_SPILLOVER_* caps, then persist the
- * union to DatasetStore. Returns the dataset metadata plus the full row set
- * (so callers can compute honest distributions from the whole result).
+ * Pull every remaining page up to MAX_SPILLOVER_* caps, then materialize the
+ * union as a canvas dataframe. Returns the dataframe metadata plus the full
+ * row set (so callers can compute honest distributions from the whole result).
  */
-export declare function spillToDataset<T extends Record<string, unknown>>(input: SpillInput<T>): Promise<SpillResult<T>>;
+export declare function spillToCanvas<T extends Record<string, unknown>>(input: SpillInput<T>): Promise<SpillResult<T>>;
 /** BrAPI list endpoints return `{data: T[], ...}`. Some omit the wrapper. */
 export interface BrapiListResult<T> {
     data?: T[];
     [key: string]: unknown;
 }
 export declare function extractRows<T>(result: BrapiListResult<T> | T[]): T[];
+/**
+ * Extract a homogeneous record-row set from a raw BrAPI envelope `result`.
+ * Returns the array when `result` is itself a list of objects, or when
+ * `result.data` is — covering both bare-array and BrAPI-list-envelope shapes.
+ * Returns `null` for non-list shapes (single object, scalar, primitive
+ * arrays) so callers — notably `raw_get` / `raw_search` — can skip spillover
+ * and pass the upstream payload through unchanged. Empty arrays are list-
+ * shaped but carry no rows; the caller uses `length === 0` to decide whether
+ * to register a dataframe.
+ */
+export declare function extractListRows<T extends Record<string, unknown>>(result: unknown): T[] | null;
 /** Return the input as a non-empty string, or undefined. Used in distribution accessors. */
 export declare function asString(value: unknown): string | undefined;
 /**

package/dist/mcp-server/tools/shared/find-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-helpers.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/shared/find-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"find-helpers.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/shared/find-helpers.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/shared/find-helpers.js

@@ -2,8 +2,8 @@
  * @fileoverview Shared building blocks for `find_*` tools — Zod fragments for
  * common inputs (alias, loadLimit, extraFilters), utilities to merge named
  * filters with the passthrough map, a generic distribution aggregator, and
- * the dataset-spillover handler that turns a "too many rows" result into a
- * DatasetStore handle.
+ * the spillover handler that turns a "too many rows" result into a canvas
+ * dataframe handle.
  *
  * @module mcp-server/tools/shared/find-helpers
  */
@@ -13,9 +13,9 @@ import { JsonRpcErrorCode, McpError, validationError } from '@cyanheads/mcp-ts-c
 export function isUpstreamNotFound(err) {
     return err instanceof McpError && err.code === JsonRpcErrorCode.NotFound;
 }
-/** Upper cap on how many rows we'll pull for DatasetStore spillover per call. */
+/** Upper cap on how many rows we'll pull for canvas dataframe spillover per call. */
 export const MAX_SPILLOVER_ROWS = 50_000;
-/** Hard cap on how many BrAPI pages we'll traverse when building a dataset. */
+/** Hard cap on how many BrAPI pages we'll traverse when building a dataframe. */
 export const MAX_SPILLOVER_PAGES = 50;
 export const AliasInput = z
     .string()
@@ -27,7 +27,7 @@ export const LoadLimitInput = z
     .int()
     .positive()
     .optional()
-    .describe('Override the in-context row cap. Rows beyond the cap return as a dataset handle for paged follow-up.');
+    .describe('Cap on rows returned inline. Omit for the deployment default — sized so spillover reaches its full row-count ceiling. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row. Heads-up: this same value drives the upstream pageSize during spillover walks, so lowering it to "preview a smaller sample" also shrinks the dataframe ceiling proportionally — prefer SQL `LIMIT` on the dataframe for sampling instead.');
 export const ExtraFiltersInput = z
     .record(z.string(), z.unknown())
     .optional()
@@ -199,16 +199,18 @@ export function computeDistribution(rows, accessor) {
     return Object.fromEntries([...counts.entries()].sort(([, a], [, b]) => b - a));
 }
 /**
- * Render the standardized header line for `find_*` tools. When a dataset
- * spillover is present, surfaces the dataset row count alongside the
+ * Render the standardized header line for `find_*` tools. When a dataframe
+ * spillover is present, surfaces the dataframe row count alongside the
  * in-context count and the upstream total — `{returned} of {total}` alone
  * hides the middle number and confuses readers when filters miss server-
- * side and the dataset row count diverges from both.
+ * side and the dataframe row count diverges from both.
  */
 export function renderFindHeader(opts) {
-    if (opts.dataset) {
-        const expiry = opts.dataset.expiresAt ? ` (${formatExpiresIn(opts.dataset.expiresAt)})` : '';
-        return `# ${opts.returnedCount} returned · ${opts.dataset.rowCount} in dataset${expiry} · ${opts.totalCount} total ${opts.noun} — \`${opts.alias}\``;
+    if (opts.dataframe) {
+        const expiry = opts.dataframe.expiresAt
+            ? ` (${formatExpiresIn(opts.dataframe.expiresAt)})`
+            : '';
+        return `# ${opts.returnedCount} returned · ${opts.dataframe.rowCount} in dataframe${expiry} · ${opts.totalCount} total ${opts.noun} — \`${opts.alias}\``;
     }
     return `# ${opts.returnedCount} of ${opts.totalCount} ${opts.noun} — \`${opts.alias}\``;
 }
@@ -249,7 +251,7 @@ export function renderDistributions(distributions) {
 /**
  * Pull rows up to `loadLimit` on a single page. If the server reports more
  * rows than the limit, leave the rest behind — callers decide whether to
- * spill via `spillToDataset`.
+ * spill via `spillToCanvas`.
  */
 export async function loadInitialPage(client, connection, path, filters, loadLimit, ctx) {
     return await loadInitialFindPage(client, connection, getRouteForPath(path, filters), loadLimit, ctx);
@@ -283,45 +285,48 @@ async function fetchFindRoutePage(client, connection, route, pageSize, page, ctx
     return await client.getSearchResults(connection.baseUrl, route.noun, response.searchResultsDbId, ctx, buildRequestOptions(connection, { pageSize, page }, requestOptions));
 }
 /**
- * Shape of the dataset handle returned inline by `find_*` tools. Drops the
- * provenance fields (source/baseUrl/query) since those are internal and
- * available via `brapi_manage_dataset summary`.
+ * Shape of the dataframe handle returned inline by `find_*` tools. The
+ * dataframe is the canvas table holding every row beyond `loadLimit`; query
+ * it with `brapi_dataframe_query` for SQL access or describe it with
+ * `brapi_dataframe_describe` for schema + provenance.
  */
-export const DatasetHandleSchema = z.object({
-    datasetId: z.string().describe('Use with brapi_manage_dataset to page or export.'),
-    rowCount: z.number().int().nonnegative().describe('Number of rows persisted in the dataset.'),
-    sizeBytes: z.number().int().nonnegative().describe('Serialized size of the dataset in bytes.'),
+export const DataframeHandleSchema = z.object({
+    tableName: z
+        .string()
+        .describe('Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).'),
+    rowCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Number of rows materialized in the dataframe.'),
     columns: z
-        .array(z.string().describe('Column name from the persisted rows.'))
-        .describe('Full column list of the persisted rows.'),
-    createdAt: z.string().describe('ISO 8601 timestamp the dataset was created.'),
-    expiresAt: z.string().describe('ISO 8601 timestamp after which the dataset will be purged.'),
+        .array(z.string().describe('Column name from the materialized rows.'))
+        .describe('Full column list of the dataframe.'),
+    createdAt: z.string().describe('ISO 8601 timestamp the dataframe was created.'),
+    expiresAt: z
+        .string()
+        .describe('ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.'),
     truncated: z
         .boolean()
         .optional()
-        .describe('True when the dataset hit a row cap before exhausting upstream.'),
+        .describe('True when the dataframe hit a row cap before exhausting upstream.'),
     maxRows: z
         .number()
         .int()
         .positive()
         .optional()
         .describe('Cap that was applied at create time, when truncation occurred.'),
-    dataframe: z
-        .string()
-        .optional()
-        .describe('Dataframe name when this dataset was auto-registered as a SQL-queryable dataframe. Use with brapi_dataframe_query to run SQL across the rows.'),
 });
 /**
- * Render a DatasetHandle as bullet lines, matching the existing find_* tool
+ * Render a DataframeHandle as bullet lines, matching the existing find_* tool
  * format. Centralized so the truncated/maxRows fields surface consistently.
  * `expiresAt` is paired with a human-readable `expires in Xh / Xd` so the
  * agent doesn't have to subtract dates to know when the handle goes stale.
  */
-export function renderDatasetHandle(handle) {
+export function renderDataframeHandle(handle) {
     const lines = [
-        `- datasetId: \`${handle.datasetId}\``,
+        `- tableName: \`${handle.tableName}\` (query via brapi_dataframe_query)`,
         `- rowCount: ${handle.rowCount}`,
-        `- sizeBytes: ${handle.sizeBytes}`,
         `- columns: ${handle.columns.join(', ')}`,
         `- createdAt: ${handle.createdAt}`,
         `- expiresAt: ${handle.expiresAt} (${formatExpiresIn(handle.expiresAt)})`,
@@ -330,9 +335,6 @@ export function renderDatasetHandle(handle) {
         lines.push(`- truncated: true`);
     if (typeof handle.maxRows === 'number')
         lines.push(`- maxRows: ${handle.maxRows}`);
-    if (handle.dataframe) {
-        lines.push(`- dataframe: \`${handle.dataframe}\` (queryable via brapi_dataframe_query)`);
-    }
     return lines;
 }
 /**
@@ -360,29 +362,27 @@ export function formatExpiresIn(expiresAt, now = new Date()) {
         label = `${days}d`;
     return deltaMs >= 0 ? `expires in ${label}` : `expired ${label} ago`;
 }
-/** Project a `DatasetMetadata` to the in-context handle shape. */
-export function toDatasetHandle(metadata) {
+/** Project a `RegisterDataframeResult` to the inline handle shape. */
+export function toDataframeHandle(result) {
     const handle = {
-        datasetId: metadata.datasetId,
-        rowCount: metadata.rowCount,
-        sizeBytes: metadata.sizeBytes,
-        columns: metadata.columns,
-        createdAt: metadata.createdAt,
-        expiresAt: metadata.expiresAt,
+        tableName: result.tableName,
+        rowCount: result.rowCount,
+        columns: result.columns,
+        createdAt: result.createdAt,
+        expiresAt: result.expiresAt,
     };
-    if (metadata.truncated)
+    if (result.truncated)
         handle.truncated = true;
-    if (typeof metadata.maxRows === 'number')
-        handle.maxRows = metadata.maxRows;
-    if (metadata.dataframe)
-        handle.dataframe = metadata.dataframe;
+    if (typeof result.maxRows === 'number')
+        handle.maxRows = result.maxRows;
     return handle;
 }
 /**
- * Wrap `spillToDataset` with the "only spill when hasMore and totalCount >
+ * Wrap `spillToCanvas` with the "only spill when hasMore and totalCount >
  * loadLimit" guard that every `find_*` tool replicates. When no spillover is
- * needed, returns the first-page rows untouched. When it is, persists the
- * union to DatasetStore and returns both the full set and the handle.
+ * needed, returns the first-page rows untouched. When it is, materializes
+ * the union as a canvas dataframe and returns both the full set and the
+ * handle.
  */
 export async function maybeSpill(input) {
     const { firstPage, rowMapper, rowFilter } = input;
@@ -392,7 +392,7 @@ export async function maybeSpill(input) {
         return { fullRows: applyRowTransforms(firstPage.rows, rowMapper, rowFilter) };
     }
     const spillInput = {
-        store: input.store,
+        bridge: input.bridge,
         client: input.client,
         connection: input.connection,
         path: input.path,
@@ -412,16 +412,16 @@ export async function maybeSpill(input) {
     if (input.spillRequestOptions)
         spillInput.pageRequestOptions = input.spillRequestOptions;
     try {
-        const spill = await spillToDataset(spillInput);
+        const spill = await spillToCanvas(spillInput);
         return {
             fullRows: spill.fullRows,
-            dataset: toDatasetHandle(spill.dataset),
+            dataframe: toDataframeHandle(spill.dataframe),
         };
     }
     catch (err) {
         if (!input.warnings || !(err instanceof SpillPageFetchError))
             throw err;
-        input.warnings.push(`Dataset spillover skipped after returning the first ${firstPage.rows.length} row(s): ${formatSpillError(err)}. Narrow filters, raise loadLimit enough to fit the result in one page, or retry when the upstream server is responsive.`);
+        input.warnings.push(`Dataframe spillover skipped after returning the first ${firstPage.rows.length} row(s): ${formatSpillError(err)}. Narrow filters, raise loadLimit enough to fit the result in one page, or retry when the upstream server is responsive.`);
         return { fullRows: applyRowTransforms(firstPage.rows, rowMapper, rowFilter) };
     }
 }
@@ -429,18 +429,18 @@ export async function maybeSpill(input) {
  * Apply mapper before filter on a row set. Centralizes the order constraint
  * across the three spillover sites — early-exit, error fallback, and persist
  * — so they can't drift apart and accidentally filter raw rows the spilled
- * dataset has already normalized.
+ * dataframe has already normalized.
  */
 function applyRowTransforms(rows, mapper, filter) {
     const mapped = mapper ? rows.map(mapper) : rows;
     return filter ? mapped.filter(filter) : mapped;
 }
 /**
- * Pull every remaining page up to MAX_SPILLOVER_* caps, then persist the
- * union to DatasetStore. Returns the dataset metadata plus the full row set
- * (so callers can compute honest distributions from the whole result).
+ * Pull every remaining page up to MAX_SPILLOVER_* caps, then materialize the
+ * union as a canvas dataframe. Returns the dataframe metadata plus the full
+ * row set (so callers can compute honest distributions from the whole result).
  */
-export async function spillToDataset(input) {
+export async function spillToCanvas(input) {
     const remainingTarget = Math.min(input.totalCount, MAX_SPILLOVER_ROWS);
     const pageSize = input.loadLimit;
     const totalPages = Math.min(Math.ceil(remainingTarget / pageSize), MAX_SPILLOVER_PAGES);
@@ -470,23 +470,23 @@ export async function spillToDataset(input) {
     const reachedPageCap = pagesFetched >= MAX_SPILLOVER_PAGES && input.totalCount > rows.length;
     const truncated = reachedRowCap || reachedPageCap;
     const persistedRows = applyRowTransforms(rows, input.rowMapper, input.rowFilter);
-    const createInput = {
+    const registerInput = {
         source: input.source,
         baseUrl: input.connection.baseUrl,
         query: input.filters,
         rows: persistedRows,
     };
     if (truncated) {
-        createInput.truncated = true;
+        registerInput.truncated = true;
         // `maxRows` only carries meaning when the row cap fired — it's the upper
         // bound the spillover honored. When the page cap fired first (small
         // `loadLimit` × `MAX_SPILLOVER_PAGES` < upstream total), reporting
-        // `maxRows = MAX_SPILLOVER_ROWS` is misleading: the dataset stopped at
+        // `maxRows = MAX_SPILLOVER_ROWS` is misleading: the dataframe stopped at
         // `loadLimit × MAX_SPILLOVER_PAGES`, well below the row cap. Log the
         // page-cap event for operators; the agent sees only `truncated: true`
         // without the false 50k bound and can raise `loadLimit` to push past it.
         if (reachedRowCap) {
-            createInput.maxRows = MAX_SPILLOVER_ROWS;
+            registerInput.maxRows = MAX_SPILLOVER_ROWS;
         }
         else if (reachedPageCap) {
             input.ctx.log.warning('Spillover hit page cap before exhausting upstream', {
@@ -498,8 +498,8 @@ export async function spillToDataset(input) {
             });
         }
     }
-    const dataset = await input.store.create(input.ctx, createInput);
-    return { dataset, fullRows: persistedRows, pagesFetched };
+    const dataframe = await input.bridge.registerDataframe(input.ctx, registerInput);
+    return { dataframe, fullRows: persistedRows, pagesFetched };
 }
 class SpillPageFetchError extends Error {
     name = 'SpillPageFetchError';
@@ -526,6 +526,29 @@ export function extractRows(result) {
         return result.data;
     return [];
 }
+/**
+ * Extract a homogeneous record-row set from a raw BrAPI envelope `result`.
+ * Returns the array when `result` is itself a list of objects, or when
+ * `result.data` is — covering both bare-array and BrAPI-list-envelope shapes.
+ * Returns `null` for non-list shapes (single object, scalar, primitive
+ * arrays) so callers — notably `raw_get` / `raw_search` — can skip spillover
+ * and pass the upstream payload through unchanged. Empty arrays are list-
+ * shaped but carry no rows; the caller uses `length === 0` to decide whether
+ * to register a dataframe.
+ */
+export function extractListRows(result) {
+    const candidate = Array.isArray(result)
+        ? result
+        : result && typeof result === 'object' && Array.isArray(result.data)
+            ? result.data
+            : null;
+    if (candidate === null)
+        return null;
+    if (candidate.length === 0)
+        return [];
+    const allObjects = candidate.every((row) => typeof row === 'object' && row !== null && !Array.isArray(row));
+    return allObjects ? candidate : null;
+}
 /** Return the input as a non-empty string, or undefined. Used in distribution accessors. */
 export function asString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;