@altertable/data-app 0.66.0 → 0.68.0

package/dist/server.js

@@ -1,19 +1,6 @@
 // @bun
 // src/core/contract.ts
 import { parseDate, today } from "@internationalized/date";
-
-// src/core/invariant.ts
-function invariant(condition, message) {
-  if (!condition)
-    throw new Error(`Invariant failed: ${message}`);
-}
-
-// src/core/contract.ts
-function defineQueryNames(names) {
-  const values = Object.values(names);
-  invariant(values.every((name) => !!name.trim()) && new Set(values).size === values.length, "Query names must be nonempty and unique.");
-  return names;
-}
 var sourceErrorBrand = Symbol.for("@altertable/data-app/DataSourceError");
 
 class DataSourceError extends Error {
@@ -31,17 +18,14 @@ class DataSourceError extends Error {
     this.name = "DataSourceError";
   }
 }
-var connectionQueryNames = defineQueryNames({
-  connection: "connection-check"
-});
 
 // src/core/operation.ts
 async function executeDataOperation(operation, value, {
   operationName,
   lakehouse,
   signal: requestSignal,
-  includeSql,
-  requestId
+  requestId,
+  queryParams
 }) {
   requestSignal.throwIfAborted();
   let input;
@@ -58,14 +42,15 @@ async function executeDataOperation(operation, value, {
   try {
     const output = await runOperation(operation, input, {
       lakehouse: execution.lakehouse,
-      signal
+      signal,
+      queryParams
     });
     const body = {
       data: operation.output(output),
       requestId,
       queriedAt: new Date().toISOString(),
       queryIds: execution.queryIds,
-      ...operation.policy.exposeSql && includeSql ? { queries: execution.queries } : {}
+      queries: execution.queries
     };
     const serializedBody = JSON.stringify(body);
     const responseBytes = new TextEncoder().encode(serializedBody).byteLength;
@@ -89,7 +74,8 @@ function createOperationLakehouse(operation, source, signal, operationName) {
         throw new Error(`Query name is not registered for operation ${operationName}.`);
       const query = {
         name: options.name ?? `Query ${queries.length + 1}`,
-        statement
+        statement,
+        ...options.params === undefined ? {} : { params: options.params }
       };
       queries.push(query);
       const limit = Math.min(options.limit, operation.policy.maxQueryRows);
@@ -97,6 +83,7 @@ function createOperationLakehouse(operation, source, signal, operationName) {
       try {
         result = await source.queryAll(statement, {
           limit,
+          ...options.params === undefined ? {} : { params: options.params },
           signal: AbortSignal.any([signal, options.signal])
         });
       } catch (error) {
@@ -115,7 +102,7 @@ function createOperationLakehouse(operation, source, signal, operationName) {
   };
   return { lakehouse, queries, queryIds };
 }
-async function runOperation(operation, input, { lakehouse, signal }) {
+async function runOperation(operation, input, { lakehouse, signal, queryParams }) {
   let abort;
   try {
     signal.throwIfAborted();
@@ -132,7 +119,7 @@ async function runOperation(operation, input, { lakehouse, signal }) {
       cancelled,
       Promise.resolve().then(() => {
         signal.throwIfAborted();
-        return operation.run({ lakehouse, signal }, input);
+        return operation.run({ lakehouse, signal, queryParams }, input);
       })
     ]);
   } finally {
@@ -223,10 +210,10 @@ function createDataHandler(operations, authorize) {
     try {
       const { serializedBody } = await executeDataOperation(operation, input, {
         lakehouse: access.lakehouse,
-        includeSql: access.canDiscloseSql,
         signal,
         requestId,
-        operationName: name
+        operationName: name,
+        queryParams: access.queryParams
       });
       return new Response(serializedBody, {
         headers: {
@@ -300,4 +287,4 @@ export {
   createDataHandler
 };
 
-//# debugId=97D671C00924C2DF64756E2164756E21
+//# debugId=A8B5257A307F4C0764756E2164756E21

package/dist/server.js.map

@@ -1,13 +1,12 @@
 {
   "version": 3,
-  "sources": ["../src/core/contract.ts", "../src/core/invariant.ts", "../src/core/operation.ts", "../src/server/handler.ts"],
+  "sources": ["../src/core/contract.ts", "../src/core/operation.ts", "../src/server/handler.ts"],
   "sourcesContent": [
-    "/**\n * Shared operation contracts and input/output validation for browser and server.\n * @module @altertable/data-app/contract\n * @see https://github.com/altertable-ai/data-app/blob/main/docs/contract.md\n */\nimport { parseDate, today } from '@internationalized/date';\nimport { formatDateRange } from '@/src/core/format';\nimport { invariant } from '@/src/core/invariant';\nimport type { DateRange as DateRangeInput } from '@/src/core/date-range';\nimport type {\n  QueryResult,\n  DataOperation,\n  OperationContext,\n} from '@/src/core/operation-types';\nexport type {\n  QueryResult,\n  DisclosedQuery,\n  Lakehouse,\n  OperationContext,\n  DataOperation,\n  DataOperations,\n} from '@/src/core/operation-types';\n\nexport function parseEmptyInput(value: unknown): Record<string, never> {\n  invariant(\n    typeof value === 'object' &&\n      value !== null &&\n      !Array.isArray(value) &&\n      Object.keys(value).length === 0,\n    'This operation takes no inputs.'\n  );\n\n  return {};\n}\n\nexport function parseTrue(value: unknown): true {\n  invariant(value === true, 'Expected a successful check.');\n\n  return true;\n}\n\nexport type { DateRange as DateRangeInput } from '@/src/core/date-range';\nexport type DateRangeRequest = {\n  range: DateRangeInput;\n  comparison: DateRangeInput | null;\n};\n\n/** The immediately preceding, equally long set of calendar days. */\nexport function previousDateRange({\n  start,\n  end,\n}: DateRangeInput): DateRangeInput {\n  const first = parseDate(start);\n  const last = parseDate(end);\n  const days =\n    (last.toDate('UTC').getTime() - first.toDate('UTC').getTime()) /\n      86_400_000 +\n    1;\n  invariant(days >= 1, 'Date range must start before it ends.');\n  const previousEnd = first.subtract({ days: 1 });\n\n  return {\n    start: previousEnd.subtract({ days: days - 1 }).toString(),\n    end: previousEnd.toString(),\n  };\n}\n\nexport type ReportingPeriod =\n  | { kind: 'rolling'; amount: number; unit: 'hour' | 'day'; end: string }\n  | { kind: 'calendar'; start: string; end: string; timeZone: string };\n\nexport type DateRangeContractOptions = {\n  minDate?: string;\n  maxDate?: string | (() => string);\n  maxRangeDays: number;\n  timeZone: string;\n  completeDays?: boolean;\n};\n\n/** One source policy for the server parser, URL variable, and displayed reporting period. */\nexport function defineDateRangeContract(options: DateRangeContractOptions) {\n  invariant(\n    Number.isInteger(options.maxRangeDays) && options.maxRangeDays > 0,\n    'Date range needs a positive maxRangeDays.'\n  );\n  if (options.minDate) parseDate(options.minDate);\n  if (typeof options.maxDate === 'string') parseDate(options.maxDate);\n  today(options.timeZone);\n\n  function bounds() {\n    const latest = today(options.timeZone).subtract({\n      days: options.completeDays === false ? 0 : 1,\n    });\n    const sourceMax =\n      typeof options.maxDate === 'function'\n        ? options.maxDate()\n        : options.maxDate;\n    const maxDate =\n      sourceMax && parseDate(sourceMax).compare(latest) < 0\n        ? parseDate(sourceMax).toString()\n        : latest.toString();\n\n    return {\n      minDate: options.minDate,\n      maxDate,\n      maxRangeDays: options.maxRangeDays,\n      timeZone: options.timeZone,\n    };\n  }\n\n  function period({ start, end }: DateRangeInput): ReportingPeriod {\n    return {\n      kind: 'calendar',\n      start,\n      end,\n      timeZone: options.timeZone,\n    };\n  }\n\n  function describeInput(input: DateRangeInput) {\n    return `${formatDateRange(input)} ${options.timeZone}`;\n  }\n\n  function comparison(input: DateRangeInput): DateRangeInput | null {\n    const previous = previousDateRange(input);\n\n    return options.minDate && previous.start < options.minDate\n      ? null\n      : previous;\n  }\n\n  function request(value: unknown, compare = false): DateRangeRequest {\n    const range = parseDateRangeInput(value, bounds());\n    const previous = compare ? comparison(range) : null;\n    invariant(\n      !compare || previous,\n      'Comparison is outside available source coverage.'\n    );\n\n    return { range, comparison: previous };\n  }\n\n  function parseRequest(value: unknown): DateRangeRequest {\n    invariant(value && typeof value === 'object', 'Choose a date range.');\n    const input = value as Record<string, unknown>;\n    const parsed = request(input.range, input.comparison != null);\n    if (input.comparison != null) {\n      const supplied = parseDateRangeInput(input.comparison, bounds());\n      invariant(\n        supplied.start === parsed.comparison?.start &&\n          supplied.end === parsed.comparison?.end,\n        'Comparison must be the preceding equal-length range.'\n      );\n    }\n\n    return parsed;\n  }\n\n  return {\n    request,\n    parseRequest,\n    bounds,\n    parse(value: unknown) {\n      return parseDateRangeInput(value, bounds());\n    },\n    period,\n    comparison,\n    describeInput,\n    view: { period, describeInput },\n  };\n}\n\nexport type DateRangeContract = ReturnType<typeof defineDateRangeContract>;\n\n/** Validate calendar dates and a bounded inclusive range on the server. */\nexport function parseDateRangeInput(\n  value: unknown,\n  {\n    minDate,\n    maxDate,\n    maxRangeDays,\n  }: { minDate?: string; maxDate?: string; maxRangeDays: number }\n): DateRangeInput {\n  invariant(\n    value && typeof value === 'object' && !Array.isArray(value),\n    'Choose a date range.'\n  );\n  const { start, end } = value as Record<string, unknown>;\n\n  function day(input: unknown): number {\n    invariant(\n      typeof input === 'string' && /^\\d{4}-\\d{2}-\\d{2}$/.test(input),\n      'Dates must be YYYY-MM-DD.'\n    );\n    const timestamp = Date.parse(`${input}T00:00:00Z`);\n    invariant(\n      Number.isFinite(timestamp) &&\n        new Date(timestamp).toISOString().slice(0, 10) === input,\n      'Choose valid calendar dates.'\n    );\n\n    return timestamp;\n  }\n  const first = day(start);\n  const last = day(end);\n  invariant(\n    Number.isInteger(maxRangeDays) && maxRangeDays > 0,\n    'Maximum range days must be positive.'\n  );\n  invariant(\n    first <= last &&\n      (last - first) / 86_400_000 < maxRangeDays &&\n      (minDate === undefined || first >= day(minDate)) &&\n      (maxDate === undefined || last <= day(maxDate)),\n    `Choose up to ${maxRangeDays} days within the available range.`\n  );\n\n  return { start: start as string, end: end as string };\n}\n\n/** Accepts numeric strings from DuckDB; rejects negative, fractional, and unsafe integers. */\nexport function parseCount(value: unknown): number {\n  const number =\n    typeof value === 'number' || typeof value === 'string'\n      ? Number(value)\n      : NaN;\n  invariant(\n    Number.isSafeInteger(number) &&\n      number >= 0 &&\n      (typeof value !== 'string' || !!value.trim()),\n    'Invalid count in query result.'\n  );\n\n  return number;\n}\n\nexport function parseLabel(value: unknown, maxLength = 100): string {\n  invariant(\n    typeof value === 'string' && !!value && value.length <= maxLength,\n    'Invalid label in query result.'\n  );\n\n  return value;\n}\n\n/** Rejects missing or duplicate columns and rows whose width differs from the column list. */\nexport function rowsAsRecords(\n  result: QueryResult,\n  requiredColumns: readonly string[]\n): Record<string, unknown>[] {\n  const names = result.columns.map(column => column.name);\n  invariant(\n    new Set(names).size === names.length &&\n      requiredColumns.every(name => names.includes(name)),\n    'Query result columns do not match the expected shape.'\n  );\n\n  return result.rows.map(row => {\n    invariant(\n      row.length === names.length,\n      'Query result row has the wrong width.'\n    );\n\n    return Object.fromEntries(names.map((name, index) => [name, row[index]]));\n  });\n}\n\nexport function defineQueryNames<const Names extends Record<string, string>>(\n  names: Names\n): Names {\n  const values = Object.values(names);\n  invariant(\n    values.every(name => !!name.trim()) &&\n      new Set(values).size === values.length,\n    'Query names must be nonempty and unique.'\n  );\n\n  return names;\n}\n\nconst sourceErrorBrand = Symbol.for('@altertable/data-app/DataSourceError');\n\nexport class DataSourceError extends Error {\n  readonly [sourceErrorBrand] = true;\n  queryName?: string;\n\n  static [Symbol.hasInstance](value: unknown): boolean {\n    return (\n      value instanceof Error &&\n      (value as { [sourceErrorBrand]?: unknown })[sourceErrorBrand] === true\n    );\n  }\n\n  constructor(\n    public readonly reason:\n      | 'unauthorized'\n      | 'forbidden'\n      | 'rate_limited'\n      | 'query_rejected'\n      | 'unavailable',\n    public readonly status?: number\n  ) {\n    super(`Data source ${reason}${status ? ` (${status})` : ''}.`);\n    this.name = 'DataSourceError';\n  }\n}\n\nexport type OperationQuery<Names extends Readonly<Record<string, string>>> = (\n  name: Names[keyof Names],\n  statement: string,\n  options?: { limit?: number }\n) => Promise<QueryResult>;\n\nexport function defineOperation<\n  Input,\n  Output,\n  const Names extends Readonly<Record<string, string>> = Record<string, never>,\n>(\n  operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {\n    queryNames?: Names;\n    run: (\n      context: OperationContext & { query: OperationQuery<NoInfer<Names>> },\n      input: Input\n    ) => Promise<Output>;\n  }\n): DataOperation<Input, Output> & { queryNames?: Names } {\n  invariant(\n    Array.isArray(operation.checks) &&\n      operation.checks.length > 0 &&\n      Number.isInteger(operation.policy.maxQueryRows) &&\n      operation.policy.maxQueryRows > 0 &&\n      Number.isInteger(operation.policy.maxDurationMs) &&\n      operation.policy.maxDurationMs > 0 &&\n      (operation.policy.maxResponseBytes === undefined ||\n        (Number.isInteger(operation.policy.maxResponseBytes) &&\n          operation.policy.maxResponseBytes > 0)),\n    'Each data operation needs check inputs and positive row and duration limits.'\n  );\n  if (operation.queryNames) defineQueryNames(operation.queryNames);\n  for (const input of operation.checks) operation.input(input);\n\n  return {\n    ...operation,\n    run(context, input) {\n      function query(\n        name: Names[keyof Names],\n        statement: string,\n        options?: { limit?: number }\n      ): Promise<QueryResult> {\n        invariant(\n          operation.queryNames &&\n            Object.values(operation.queryNames).includes(name),\n          `Unknown query name: ${name}.`\n        );\n\n        return context.lakehouse.queryAll(statement, {\n          name,\n          limit: options?.limit ?? operation.policy.maxQueryRows,\n          signal: context.signal,\n        });\n      }\n\n      return operation.run({ ...context, query }, input);\n    },\n  };\n}\n\nexport const connectionQueryNames = defineQueryNames({\n  connection: 'connection-check',\n});\n\n/** Success requires a bounded SQL query; it does not establish access to a particular dataset. */\nexport function connectionCheck(): DataOperation<Record<string, never>, true> {\n  return defineOperation({\n    input: parseEmptyInput,\n    output: parseTrue,\n    checks: [{}],\n    queryNames: connectionQueryNames,\n    policy: { maxQueryRows: 1, maxDurationMs: 15_000, exposeSql: true },\n    async run({ query }): Promise<true> {\n      await query(\n        connectionQueryNames.connection,\n        'SELECT 1 AS connection_check'\n      );\n\n      return true;\n    },\n  });\n}\n\nexport {\n  dimensionFilter,\n  parseDimensionSelection,\n  parseFacetOptions,\n  dimensionPredicate,\n} from '@/src/core/dimension';\nexport type {\n  DimensionSelection,\n  DimensionMember,\n  DimensionOption,\n  DimensionVariable,\n  DimensionFilterOptions,\n} from '@/src/core/dimension';\n\nexport {\n  createMessageRouter,\n  defineMessageRoute,\n  defineDataQueryRoute,\n  MessageRoutingError,\n  dataAppRoutes,\n  navigationUpdateRoute,\n  sqlQueryRoute,\n} from '@/src/core/messages';\nexport type {\n  MessageContext,\n  RoutedMessage,\n  MessageDispatcher,\n  MessageTransport,\n  MessageRoute,\n  MessageRoutes,\n  MessageInput,\n  MessageHandlers,\n  MessageOutput,\n  OperationContracts,\n  DataQueryInput,\n  DataQueryBody,\n  DataQueryRoute,\n  NavigationUpdate,\n  SqlQueryInput,\n} from '@/src/core/messages';\nexport type { TransportResponse } from '@/src/core/bridge';\n\nexport {\n  annotationDraftRoute,\n  annotationModeRoute,\n  annotationEditorStateRoute,\n  annotationUpdateRoute,\n  parseDataAppAnnotationDraft,\n} from '@/src/core/annotations';\nexport type {\n  DataAppAnnotationDraft,\n  DataAppAnnotationPresentation,\n} from '@/src/core/annotations';\n",
-    "/** Assert an author or data contract while preserving a useful failure message. */\nexport function invariant(\n  condition: unknown,\n  message: string\n): asserts condition {\n  if (!condition) throw new Error(`Invariant failed: ${message}`);\n}\n",
-    "import { DataSourceError } from '@/src/core/contract';\nimport type {\n  DataOperations,\n  DisclosedQuery,\n  Lakehouse,\n  OperationContext,\n  DataQueryBody,\n} from '@/src/core/operation-types';\n\ntype Operation = DataOperations[string];\ntype OperationExecutionOptions = {\n  operationName: string;\n  lakehouse: Lakehouse;\n  signal: AbortSignal;\n  /** Include query evidence in the response; this does not keep browser-owned SQL private. */\n  includeSql: boolean;\n  requestId: string;\n};\n\n/** Shared operation execution. Adapters own authorization, delivery, and public errors. */\nexport async function executeDataOperation(\n  operation: Operation,\n  value: unknown,\n  {\n    operationName,\n    lakehouse,\n    signal: requestSignal,\n    includeSql,\n    requestId,\n  }: OperationExecutionOptions\n) {\n  requestSignal.throwIfAborted();\n  let input: unknown;\n  try {\n    input = operation.input(value);\n  } catch {\n    throw new OperationInputError();\n  }\n\n  const signal = AbortSignal.any([\n    requestSignal,\n    AbortSignal.timeout(operation.policy.maxDurationMs),\n  ]);\n  const execution = createOperationLakehouse(\n    operation,\n    lakehouse,\n    signal,\n    operationName\n  );\n  try {\n    const output = await runOperation(operation, input, {\n      lakehouse: execution.lakehouse,\n      signal,\n    });\n    const body: DataQueryBody<unknown> = {\n      data: operation.output(output),\n      requestId,\n      queriedAt: new Date().toISOString(),\n      queryIds: execution.queryIds,\n      ...(operation.policy.exposeSql && includeSql\n        ? { queries: execution.queries }\n        : {}),\n    };\n    const serializedBody = JSON.stringify(body);\n    const responseBytes = new TextEncoder().encode(serializedBody).byteLength;\n    if (responseBytes > (operation.policy.maxResponseBytes ?? 1_000_000))\n      throw new Error('Response exceeds byte limit.');\n\n    return { body, serializedBody };\n  } catch (error) {\n    if (signal.aborted && !(error instanceof DataSourceError))\n      throw new OperationTimeoutError();\n    throw error;\n  }\n}\n\n/** Query evidence follows statement invocation order; query IDs retain completion order. */\nfunction createOperationLakehouse(\n  operation: Operation,\n  source: Lakehouse,\n  signal: AbortSignal,\n  operationName: string\n) {\n  const queryIds: string[] = [];\n  const queries: DisclosedQuery[] = [];\n  const lakehouse: Lakehouse = {\n    async queryAll(statement, options) {\n      if (!Number.isInteger(options.limit) || options.limit < 1)\n        throw new Error('Query needs a positive row limit.');\n      if (\n        operation.queryNames &&\n        !Object.values(operation.queryNames).includes(options.name ?? '')\n      )\n        throw new Error(\n          `Query name is not registered for operation ${operationName}.`\n        );\n      const query: DisclosedQuery = {\n        name: options.name ?? `Query ${queries.length + 1}`,\n        statement,\n      };\n      queries.push(query);\n      const limit = Math.min(options.limit, operation.policy.maxQueryRows);\n      let result;\n      try {\n        result = await source.queryAll(statement, {\n          limit,\n          signal: AbortSignal.any([signal, options.signal]),\n        });\n      } catch (error) {\n        if (error instanceof DataSourceError) error.queryName = query.name;\n        throw error;\n      }\n      if (result.rows.length > limit)\n        throw new Error('Result exceeds row limit.');\n      if (result.queryId) {\n        query.queryId = result.queryId;\n        queryIds.push(result.queryId);\n      }\n\n      return result;\n    },\n  };\n\n  return { lakehouse, queries, queryIds };\n}\n\n/** Settle cancellation even when operation code or its lakehouse ignores the signal. */\nasync function runOperation(\n  operation: Operation,\n  input: unknown,\n  { lakehouse, signal }: OperationContext\n) {\n  let abort: (() => void) | undefined;\n  try {\n    signal.throwIfAborted();\n    const cancelled = new Promise<never>((_, reject) => {\n      function rejectAborted() {\n        reject(new Error('Request aborted.'));\n      }\n      abort = rejectAborted;\n      signal.addEventListener('abort', rejectAborted, { once: true });\n      if (signal.aborted) rejectAborted();\n    });\n\n    return await Promise.race([\n      cancelled,\n      Promise.resolve().then(() => {\n        signal.throwIfAborted();\n\n        return operation.run({ lakehouse, signal }, input as never);\n      }),\n    ]);\n  } finally {\n    if (abort) signal.removeEventListener('abort', abort);\n  }\n}\n\nclass OperationTimeoutError extends Error {}\n\nclass OperationInputError extends Error {}\n\nconst sourceErrorMessages = {\n  unauthorized:\n    'This app could not authenticate its data connection. Contact the app owner.',\n  forbidden:\n    'This app cannot access the requested data. Contact the app owner.',\n  rate_limited: 'The lakehouse is busy. Wait a moment and retry.',\n  query_rejected:\n    \"A lakehouse query was rejected. Check the app's data operation.\",\n  unavailable: 'The lakehouse is unavailable. Check the connection and retry.',\n};\n\nexport function toDataOperationFailure(error: unknown, aborted = false) {\n  if (error instanceof OperationInputError)\n    return {\n      status: 400,\n      code: 'invalid_input',\n      message: \"Check this operation's inputs.\",\n    };\n  if (error instanceof DataSourceError)\n    return {\n      status: error.reason === 'rate_limited' ? 429 : 502,\n      code: `source_${error.reason}`,\n      message: sourceErrorMessages[error.reason],\n    };\n  const timedOut = aborted || error instanceof OperationTimeoutError;\n  return {\n    status: timedOut ? 504 : 502,\n    code: timedOut ? 'timeout' : 'query_failed',\n    message: timedOut\n      ? 'The data request timed out.'\n      : 'The data request failed.',\n  };\n}\n",
-    "import {\n  executeDataOperation,\n  toDataOperationFailure,\n} from '@/src/core/operation';\nimport {\n  DataSourceError,\n  type DataOperations,\n  type Lakehouse,\n} from '@/src/core/contract';\n\n/** Authorization result for one viewer request. A hosted adapter must scope its lakehouse client. */\nexport type RequestAccess = { lakehouse: Lakehouse; canDiscloseSql: boolean };\n\n/**\n * Execute named operations on the server. The app supplies operations and viewer authorization.\n * JSON, Origin, and Fetch Metadata checks reject cross-site browser POSTs; they do not\n * authenticate another local process. SQL is returned only when both the operation and\n * authorization result permit disclosure.\n */\nexport function createDataHandler(\n  operations: DataOperations,\n  authorize: (request: Request, operation: string) => Promise<RequestAccess>\n) {\n  async function handleDataRequest(request: Request): Promise<Response> {\n    const requestId = crypto.randomUUID();\n    const url = new URL(request.url);\n    if (!url.pathname.startsWith('/api/data/'))\n      return new Response('Not found', { status: 404 });\n    const encodedName = url.pathname.slice('/api/data/'.length);\n    if (!encodedName || encodedName.includes('/'))\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    let name: string;\n    try {\n      name = decodeURIComponent(encodedName);\n    } catch {\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    }\n    if (!Object.hasOwn(operations, name))\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    if (request.method !== 'POST')\n      return problem(405, 'method_not_allowed', 'Use POST.', requestId);\n    if (\n      request.headers\n        .get('content-type')\n        ?.split(';')[0]\n        ?.trim()\n        .toLowerCase() !== 'application/json'\n    )\n      return problem(\n        415,\n        'unsupported_media_type',\n        'Use application/json.',\n        requestId\n      );\n    const origin = request.headers.get('origin');\n    const fetchSite = request.headers.get('sec-fetch-site');\n    const fetchMode = request.headers.get('sec-fetch-mode');\n    if (\n      (origin !== null && origin !== url.origin) ||\n      (fetchSite !== null && fetchSite !== 'same-origin') ||\n      (fetchSite !== null && origin === null) ||\n      (fetchMode !== null &&\n        fetchMode !== 'cors' &&\n        fetchMode !== 'same-origin')\n    )\n      return problem(\n        403,\n        'cross_origin_request',\n        'The data request must come from this app.',\n        requestId\n      );\n    let access: RequestAccess;\n    try {\n      access = await authorize(request, name);\n    } catch {\n      return problem(\n        403,\n        'forbidden',\n        'You cannot run this data operation.',\n        requestId\n      );\n    }\n    const operation = operations[name]!;\n    let input: unknown;\n    if (request.signal.aborted)\n      return problem(504, 'timeout', 'The data request timed out.', requestId);\n    try {\n      const body = await readInput(request);\n      input = JSON.parse(body);\n    } catch (error) {\n      if (error instanceof InputTooLargeError)\n        return problem(\n          413,\n          'input_too_large',\n          'Input is too large.',\n          requestId\n        );\n\n      return problem(\n        400,\n        'invalid_input',\n        \"Check this operation's inputs.\",\n        requestId\n      );\n    }\n    const signal = request.signal;\n    try {\n      const { serializedBody } = await executeDataOperation(operation, input, {\n        lakehouse: access.lakehouse,\n        includeSql: access.canDiscloseSql,\n        signal,\n        requestId,\n        operationName: name,\n      });\n      return new Response(serializedBody, {\n        headers: {\n          'cache-control': 'no-store',\n          'content-type': 'application/json',\n        },\n      });\n    } catch (error) {\n      const source = error instanceof DataSourceError ? error : null;\n      console.error(\n        `Data operation ${name} failed (${requestId}): ${source ? `${source.reason}${source.status ? ` (${source.status})` : ''}${source.queryName ? ` in ${source.queryName}` : ''}` : error instanceof Error ? error.name : 'unknown'}`\n      );\n      const failure = toDataOperationFailure(error, signal.aborted);\n\n      return problem(failure.status, failure.code, failure.message, requestId);\n    }\n  }\n\n  return handleDataRequest;\n}\n\nfunction problem(\n  status: number,\n  code: string,\n  message: string,\n  requestId: string\n): Response {\n  return Response.json(\n    { error: { code, message, requestId } },\n    { status, headers: { 'cache-control': 'no-store' } }\n  );\n}\n\nconst MAX_INPUT_BYTES = 16_384;\nclass InputTooLargeError extends Error {}\n\n/** Count encoded bytes before retaining chunks; cancellation also interrupts waiting reads. */\nasync function readInput(request: Request): Promise<string> {\n  const reader = request.body?.getReader();\n  if (!reader) return '';\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n  let abort: (() => void) | undefined;\n\n  function cancelReader() {\n    // The source's cancel algorithm may never settle; the handler must still respond.\n    void reader!.cancel().catch(() => {});\n  }\n\n  try {\n    request.signal.throwIfAborted();\n    const cancelled = new Promise<never>((_, reject) => {\n      function rejectAborted() {\n        reject(new Error('Request aborted.'));\n        cancelReader();\n      }\n      abort = rejectAborted;\n      request.signal.addEventListener('abort', rejectAborted, { once: true });\n      if (request.signal.aborted) rejectAborted();\n    });\n    while (true) {\n      const { done, value } = await Promise.race([reader.read(), cancelled]);\n      if (done) break;\n      size += value.byteLength;\n      if (size > MAX_INPUT_BYTES) {\n        cancelReader();\n        throw new InputTooLargeError();\n      }\n      chunks.push(value);\n    }\n    const bytes = new Uint8Array(size);\n    let offset = 0;\n    for (const chunk of chunks) {\n      bytes.set(chunk, offset);\n      offset += chunk.byteLength;\n    }\n\n    return new TextDecoder().decode(bytes);\n  } finally {\n    if (abort) request.signal.removeEventListener('abort', abort);\n    reader.releaseLock();\n  }\n}\n"
+    "/**\n * Shared operation contracts and input/output validation for browser and server.\n * @module @altertable/data-app/contract\n * @see https://github.com/altertable-ai/data-app/blob/main/docs/contract.md\n */\nimport { parseDate, today } from '@internationalized/date';\nimport { formatDateRange } from '@/src/core/format';\nimport { invariant } from '@/src/core/invariant';\nimport {\n  snapshotQueries,\n  resolveQueryParameters,\n  type QueryDefinitions,\n  type QueryParameters,\n  type QueryParameterValue,\n} from '@/src/core/queries';\nexport type {\n  QueryDefinitions,\n  QueryParameters,\n  QueryParameterValue,\n} from '@/src/core/queries';\nimport type { DateRange as DateRangeInput } from '@/src/core/date-range';\nimport type {\n  QueryResult,\n  DataOperation,\n  OperationContext,\n} from '@/src/core/operation-types';\nexport type {\n  QueryResult,\n  DisclosedQuery,\n  Lakehouse,\n  OperationContext,\n  DataOperation,\n  DataOperations,\n} from '@/src/core/operation-types';\n\nexport function parseEmptyInput(value: unknown): Record<string, never> {\n  invariant(\n    typeof value === 'object' &&\n      value !== null &&\n      !Array.isArray(value) &&\n      Object.keys(value).length === 0,\n    'This operation takes no inputs.'\n  );\n\n  return {};\n}\n\nexport function parseTrue(value: unknown): true {\n  invariant(value === true, 'Expected a successful check.');\n\n  return true;\n}\n\nexport type { DateRange as DateRangeInput } from '@/src/core/date-range';\nexport type DateRangeRequest = {\n  range: DateRangeInput;\n  comparison: DateRangeInput | null;\n};\n\n/** The immediately preceding, equally long set of calendar days. */\nexport function previousDateRange({\n  start,\n  end,\n}: DateRangeInput): DateRangeInput {\n  const first = parseDate(start);\n  const last = parseDate(end);\n  const days =\n    (last.toDate('UTC').getTime() - first.toDate('UTC').getTime()) /\n      86_400_000 +\n    1;\n  invariant(days >= 1, 'Date range must start before it ends.');\n  const previousEnd = first.subtract({ days: 1 });\n\n  return {\n    start: previousEnd.subtract({ days: days - 1 }).toString(),\n    end: previousEnd.toString(),\n  };\n}\n\nexport type ReportingPeriod =\n  | { kind: 'rolling'; amount: number; unit: 'hour' | 'day'; end: string }\n  | { kind: 'calendar'; start: string; end: string; timeZone: string };\n\nexport type DateRangeContractOptions = {\n  minDate?: string;\n  maxDate?: string | (() => string);\n  maxRangeDays: number;\n  timeZone: string;\n  completeDays?: boolean;\n};\n\n/** One source policy for the server parser, URL variable, and displayed reporting period. */\nexport function defineDateRangeContract(options: DateRangeContractOptions) {\n  invariant(\n    Number.isInteger(options.maxRangeDays) && options.maxRangeDays > 0,\n    'Date range needs a positive maxRangeDays.'\n  );\n  if (options.minDate) parseDate(options.minDate);\n  if (typeof options.maxDate === 'string') parseDate(options.maxDate);\n  today(options.timeZone);\n\n  function bounds() {\n    const latest = today(options.timeZone).subtract({\n      days: options.completeDays === false ? 0 : 1,\n    });\n    const sourceMax =\n      typeof options.maxDate === 'function'\n        ? options.maxDate()\n        : options.maxDate;\n    const maxDate =\n      sourceMax && parseDate(sourceMax).compare(latest) < 0\n        ? parseDate(sourceMax).toString()\n        : latest.toString();\n\n    return {\n      minDate: options.minDate,\n      maxDate,\n      maxRangeDays: options.maxRangeDays,\n      timeZone: options.timeZone,\n    };\n  }\n\n  function period({ start, end }: DateRangeInput): ReportingPeriod {\n    return {\n      kind: 'calendar',\n      start,\n      end,\n      timeZone: options.timeZone,\n    };\n  }\n\n  function describeInput(input: DateRangeInput) {\n    return `${formatDateRange(input)} ${options.timeZone}`;\n  }\n\n  function comparison(input: DateRangeInput): DateRangeInput | null {\n    const previous = previousDateRange(input);\n\n    return options.minDate && previous.start < options.minDate\n      ? null\n      : previous;\n  }\n\n  function request(value: unknown, compare = false): DateRangeRequest {\n    const range = parseDateRangeInput(value, bounds());\n    const previous = compare ? comparison(range) : null;\n    invariant(\n      !compare || previous,\n      'Comparison is outside available source coverage.'\n    );\n\n    return { range, comparison: previous };\n  }\n\n  function parseRequest(value: unknown): DateRangeRequest {\n    invariant(value && typeof value === 'object', 'Choose a date range.');\n    const input = value as Record<string, unknown>;\n    const parsed = request(input.range, input.comparison != null);\n    if (input.comparison != null) {\n      const supplied = parseDateRangeInput(input.comparison, bounds());\n      invariant(\n        supplied.start === parsed.comparison?.start &&\n          supplied.end === parsed.comparison?.end,\n        'Comparison must be the preceding equal-length range.'\n      );\n    }\n\n    return parsed;\n  }\n\n  return {\n    request,\n    parseRequest,\n    bounds,\n    parse(value: unknown) {\n      return parseDateRangeInput(value, bounds());\n    },\n    period,\n    comparison,\n    describeInput,\n    view: { period, describeInput },\n  };\n}\n\nexport type DateRangeContract = ReturnType<typeof defineDateRangeContract>;\n\n/** Validate calendar dates and a bounded inclusive range on the server. */\nexport function parseDateRangeInput(\n  value: unknown,\n  {\n    minDate,\n    maxDate,\n    maxRangeDays,\n  }: { minDate?: string; maxDate?: string; maxRangeDays: number }\n): DateRangeInput {\n  invariant(\n    value && typeof value === 'object' && !Array.isArray(value),\n    'Choose a date range.'\n  );\n  const { start, end } = value as Record<string, unknown>;\n\n  function day(input: unknown): number {\n    invariant(\n      typeof input === 'string' && /^\\d{4}-\\d{2}-\\d{2}$/.test(input),\n      'Dates must be YYYY-MM-DD.'\n    );\n    const timestamp = Date.parse(`${input}T00:00:00Z`);\n    invariant(\n      Number.isFinite(timestamp) &&\n        new Date(timestamp).toISOString().slice(0, 10) === input,\n      'Choose valid calendar dates.'\n    );\n\n    return timestamp;\n  }\n  const first = day(start);\n  const last = day(end);\n  invariant(\n    Number.isInteger(maxRangeDays) && maxRangeDays > 0,\n    'Maximum range days must be positive.'\n  );\n  invariant(\n    first <= last &&\n      (last - first) / 86_400_000 < maxRangeDays &&\n      (minDate === undefined || first >= day(minDate)) &&\n      (maxDate === undefined || last <= day(maxDate)),\n    `Choose up to ${maxRangeDays} days within the available range.`\n  );\n\n  return { start: start as string, end: end as string };\n}\n\n/** Accepts numeric strings from DuckDB; rejects negative, fractional, and unsafe integers. */\nexport function parseCount(value: unknown): number {\n  const number =\n    typeof value === 'number' || typeof value === 'string'\n      ? Number(value)\n      : NaN;\n  invariant(\n    Number.isSafeInteger(number) &&\n      number >= 0 &&\n      (typeof value !== 'string' || !!value.trim()),\n    'Invalid count in query result.'\n  );\n\n  return number;\n}\n\nexport function parseLabel(value: unknown, maxLength = 100): string {\n  invariant(\n    typeof value === 'string' && !!value && value.length <= maxLength,\n    'Invalid label in query result.'\n  );\n\n  return value;\n}\n\n/** Rejects missing or duplicate columns and rows whose width differs from the column list. */\nexport function rowsAsRecords(\n  result: QueryResult,\n  requiredColumns: readonly string[]\n): Record<string, unknown>[] {\n  const names = result.columns.map(column => column.name);\n  invariant(\n    new Set(names).size === names.length &&\n      requiredColumns.every(name => names.includes(name)),\n    'Query result columns do not match the expected shape.'\n  );\n\n  return result.rows.map(row => {\n    invariant(\n      row.length === names.length,\n      'Query result row has the wrong width.'\n    );\n\n    return Object.fromEntries(names.map((name, index) => [name, row[index]]));\n  });\n}\n\nexport function defineQueryNames<const Names extends Record<string, string>>(\n  names: Names\n): Names {\n  const values = Object.values(names);\n  invariant(\n    values.every(name => !!name.trim()) &&\n      new Set(values).size === values.length,\n    'Query names must be nonempty and unique.'\n  );\n\n  return names;\n}\n\nconst sourceErrorBrand = Symbol.for('@altertable/data-app/DataSourceError');\n\nexport class DataSourceError extends Error {\n  readonly [sourceErrorBrand] = true;\n  queryName?: string;\n\n  static [Symbol.hasInstance](value: unknown): boolean {\n    return (\n      value instanceof Error &&\n      (value as { [sourceErrorBrand]?: unknown })[sourceErrorBrand] === true\n    );\n  }\n\n  constructor(\n    public readonly reason:\n      | 'unauthorized'\n      | 'forbidden'\n      | 'rate_limited'\n      | 'query_rejected'\n      | 'unavailable',\n    public readonly status?: number\n  ) {\n    super(`Data source ${reason}${status ? ` (${status})` : ''}.`);\n    this.name = 'DataSourceError';\n  }\n}\n\ntype RegisteredQueryParameters<\n  Queries extends QueryDefinitions,\n  Name extends keyof Queries,\n> = keyof Queries[Name]['params'] extends never\n  ? Record<string, never>\n  : Partial<Record<keyof Queries[Name]['params'], QueryParameterValue>>;\n\nexport type RegisteredQuery<Queries extends QueryDefinitions> = <\n  Name extends keyof Queries & string,\n  const Params extends object = {},\n>(\n  name: Name,\n  params?: Params &\n    NoInfer<RegisteredQueryParameters<Queries, Name>> &\n    NoInfer<\n      Record<Exclude<keyof Params, keyof Queries[Name]['params']>, never>\n    > &\n    NoInfer<Params extends (...args: never[]) => unknown ? never : object>,\n  options?: { limit?: number }\n) => Promise<QueryResult>;\n\nexport function defineOperation<\n  Input,\n  Output,\n  const Queries extends QueryDefinitions,\n>(\n  operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {\n    queries: Queries;\n    run: (\n      context: Pick<OperationContext, 'signal'> & {\n        query: RegisteredQuery<NoInfer<Queries>>;\n      },\n      input: Input\n    ) => Promise<Output>;\n  }\n): Omit<DataOperation<Input, Output>, 'queryNames'> & {\n  queryNames: { readonly [Name in keyof Queries & string]: Name };\n} {\n  invariant(\n    Array.isArray(operation.checks) &&\n      operation.checks.length > 0 &&\n      Number.isInteger(operation.policy.maxQueryRows) &&\n      operation.policy.maxQueryRows > 0 &&\n      Number.isInteger(operation.policy.maxDurationMs) &&\n      operation.policy.maxDurationMs > 0 &&\n      (operation.policy.maxResponseBytes === undefined ||\n        (Number.isInteger(operation.policy.maxResponseBytes) &&\n          operation.policy.maxResponseBytes > 0)),\n    'Each data operation needs check inputs and positive row and duration limits.'\n  );\n  const queries = snapshotQueries(operation.queries);\n  const queryNames = Object.fromEntries(\n    Object.keys(queries).map(name => [name, name])\n  ) as { readonly [Name in keyof Queries & string]: Name };\n  for (const input of operation.checks) operation.input(input);\n\n  return {\n    ...operation,\n    queryNames,\n    run(context, input) {\n      function query(\n        name: keyof Queries & string,\n        values: Partial<QueryParameters> = {},\n        options?: { limit?: number }\n      ) {\n        invariant(Object.hasOwn(queries, name), `Unknown query name: ${name}.`);\n        const definition = queries[name]!;\n        const params = resolveQueryParameters(\n          definition.params,\n          values,\n          context.queryParams ?? {}\n        );\n        return context.lakehouse.queryAll(definition.statement, {\n          name,\n          params,\n          limit: options?.limit ?? operation.policy.maxQueryRows,\n          signal: context.signal,\n        });\n      }\n      return operation.run({ signal: context.signal, query }, input);\n    },\n  };\n}\n\n/** A connectivity probe uses the app's registered connection query. */\nexport function connectionCheck<\n  const Queries extends QueryDefinitions & {\n    connection: QueryDefinitions[string];\n  },\n>(queries: Queries) {\n  return defineOperation({\n    queries,\n    input: parseEmptyInput,\n    output: parseTrue,\n    checks: [{}],\n    policy: { maxQueryRows: 1, maxDurationMs: 15_000 },\n    async run({ query }): Promise<true> {\n      await query('connection');\n      return true;\n    },\n  });\n}\n\nexport {\n  dimensionFilter,\n  parseDimensionSelection,\n  parseFacetOptions,\n  dimensionPredicate,\n} from '@/src/core/dimension';\nexport type {\n  DimensionSelection,\n  DimensionMember,\n  DimensionOption,\n  DimensionVariable,\n  DimensionFilterOptions,\n} from '@/src/core/dimension';\n\nexport {\n  createMessageRouter,\n  defineMessageRoute,\n  defineDataQueryRoute,\n  MessageRoutingError,\n  dataAppRoutes,\n  navigationUpdateRoute,\n  sqlQueryRoute,\n} from '@/src/core/messages';\nexport type {\n  MessageContext,\n  RoutedMessage,\n  MessageDispatcher,\n  MessageTransport,\n  MessageRoute,\n  MessageRoutes,\n  MessageInput,\n  MessageHandlers,\n  MessageOutput,\n  OperationContracts,\n  DataQueryInput,\n  DataQueryBody,\n  DataQueryRoute,\n  NavigationUpdate,\n  SqlQueryInput,\n} from '@/src/core/messages';\nexport type { TransportResponse } from '@/src/core/bridge';\n\nexport {\n  annotationDraftRoute,\n  annotationModeRoute,\n  annotationEditorStateRoute,\n  annotationSendRoute,\n  annotationUpdateRoute,\n  parseDataAppAnnotationDraft,\n} from '@/src/core/annotations';\nexport type {\n  DataAppAnnotationDraft,\n  DataAppAnnotationPresentation,\n} from '@/src/core/annotations';\n\nexport {\n  numberFilter,\n  booleanFilter,\n  parseNumberSelection,\n  parseBooleanSelection,\n} from '@/src/core/filters';\nexport type {\n  NumberSelection,\n  NumberOperator,\n  NumberFilter,\n  BooleanSelection,\n  BooleanFilter,\n} from '@/src/core/filters';\n",
+    "import { DataSourceError } from '@/src/core/contract';\nimport type {\n  DataOperations,\n  DisclosedQuery,\n  Lakehouse,\n  OperationContext,\n  DataQueryBody,\n} from '@/src/core/operation-types';\n\ntype Operation = DataOperations[string];\ntype OperationExecutionOptions = {\n  operationName: string;\n  lakehouse: Lakehouse;\n  signal: AbortSignal;\n  requestId: string;\n  queryParams?: OperationContext['queryParams'];\n};\n\n/** Shared operation execution. Adapters own authorization, delivery, and public errors. */\nexport async function executeDataOperation(\n  operation: Operation,\n  value: unknown,\n  {\n    operationName,\n    lakehouse,\n    signal: requestSignal,\n    requestId,\n    queryParams,\n  }: OperationExecutionOptions\n) {\n  requestSignal.throwIfAborted();\n  let input: unknown;\n  try {\n    input = operation.input(value);\n  } catch {\n    throw new OperationInputError();\n  }\n\n  const signal = AbortSignal.any([\n    requestSignal,\n    AbortSignal.timeout(operation.policy.maxDurationMs),\n  ]);\n  const execution = createOperationLakehouse(\n    operation,\n    lakehouse,\n    signal,\n    operationName\n  );\n  try {\n    const output = await runOperation(operation, input, {\n      lakehouse: execution.lakehouse,\n      signal,\n      queryParams,\n    });\n    const body: DataQueryBody<unknown> = {\n      data: operation.output(output),\n      requestId,\n      queriedAt: new Date().toISOString(),\n      queryIds: execution.queryIds,\n      queries: execution.queries,\n    };\n    const serializedBody = JSON.stringify(body);\n    const responseBytes = new TextEncoder().encode(serializedBody).byteLength;\n    if (responseBytes > (operation.policy.maxResponseBytes ?? 1_000_000))\n      throw new Error('Response exceeds byte limit.');\n\n    return { body, serializedBody };\n  } catch (error) {\n    if (signal.aborted && !(error instanceof DataSourceError))\n      throw new OperationTimeoutError();\n    throw error;\n  }\n}\n\n/** Query evidence follows statement invocation order; query IDs retain completion order. */\nfunction createOperationLakehouse(\n  operation: Operation,\n  source: Lakehouse,\n  signal: AbortSignal,\n  operationName: string\n) {\n  const queryIds: string[] = [];\n  const queries: DisclosedQuery[] = [];\n  const lakehouse: Lakehouse = {\n    async queryAll(statement, options) {\n      if (!Number.isInteger(options.limit) || options.limit < 1)\n        throw new Error('Query needs a positive row limit.');\n      if (\n        operation.queryNames &&\n        !Object.values(operation.queryNames).includes(options.name ?? '')\n      )\n        throw new Error(\n          `Query name is not registered for operation ${operationName}.`\n        );\n      const query: DisclosedQuery = {\n        name: options.name ?? `Query ${queries.length + 1}`,\n        statement,\n        ...(options.params === undefined ? {} : { params: options.params }),\n      };\n      queries.push(query);\n      const limit = Math.min(options.limit, operation.policy.maxQueryRows);\n      let result;\n      try {\n        result = await source.queryAll(statement, {\n          limit,\n          ...(options.params === undefined ? {} : { params: options.params }),\n          signal: AbortSignal.any([signal, options.signal]),\n        });\n      } catch (error) {\n        if (error instanceof DataSourceError) error.queryName = query.name;\n        throw error;\n      }\n      if (result.rows.length > limit)\n        throw new Error('Result exceeds row limit.');\n      if (result.queryId) {\n        query.queryId = result.queryId;\n        queryIds.push(result.queryId);\n      }\n\n      return result;\n    },\n  };\n\n  return { lakehouse, queries, queryIds };\n}\n\n/** Settle cancellation even when operation code or its lakehouse ignores the signal. */\nasync function runOperation(\n  operation: Operation,\n  input: unknown,\n  { lakehouse, signal, queryParams }: OperationContext\n) {\n  let abort: (() => void) | undefined;\n  try {\n    signal.throwIfAborted();\n    const cancelled = new Promise<never>((_, reject) => {\n      function rejectAborted() {\n        reject(new Error('Request aborted.'));\n      }\n      abort = rejectAborted;\n      signal.addEventListener('abort', rejectAborted, { once: true });\n      if (signal.aborted) rejectAborted();\n    });\n\n    return await Promise.race([\n      cancelled,\n      Promise.resolve().then(() => {\n        signal.throwIfAborted();\n\n        return operation.run(\n          { lakehouse, signal, queryParams },\n          input as never\n        );\n      }),\n    ]);\n  } finally {\n    if (abort) signal.removeEventListener('abort', abort);\n  }\n}\n\nclass OperationTimeoutError extends Error {}\n\nclass OperationInputError extends Error {}\n\nconst sourceErrorMessages = {\n  unauthorized:\n    'This app could not authenticate its data connection. Contact the app owner.',\n  forbidden:\n    'This app cannot access the requested data. Contact the app owner.',\n  rate_limited: 'The lakehouse is busy. Wait a moment and retry.',\n  query_rejected:\n    \"A lakehouse query was rejected. Check the app's data operation.\",\n  unavailable: 'The lakehouse is unavailable. Check the connection and retry.',\n};\n\nexport function toDataOperationFailure(error: unknown, aborted = false) {\n  if (error instanceof OperationInputError)\n    return {\n      status: 400,\n      code: 'invalid_input',\n      message: \"Check this operation's inputs.\",\n    };\n  if (error instanceof DataSourceError)\n    return {\n      status: error.reason === 'rate_limited' ? 429 : 502,\n      code: `source_${error.reason}`,\n      message: sourceErrorMessages[error.reason],\n    };\n  const timedOut = aborted || error instanceof OperationTimeoutError;\n  return {\n    status: timedOut ? 504 : 502,\n    code: timedOut ? 'timeout' : 'query_failed',\n    message: timedOut\n      ? 'The data request timed out.'\n      : 'The data request failed.',\n  };\n}\n",
+    "import {\n  executeDataOperation,\n  toDataOperationFailure,\n} from '@/src/core/operation';\nimport {\n  DataSourceError,\n  type DataOperations,\n  type Lakehouse,\n  type QueryParameters,\n} from '@/src/core/contract';\n\n/** Authorization result for one viewer request. A hosted adapter must scope its lakehouse client. */\nexport type RequestAccess = {\n  lakehouse: Lakehouse;\n  /** Trusted values shared across queries; each query uses only its declared keys. */\n  queryParams?: QueryParameters;\n};\n\n/**\n * Execute named operations on the server. The app supplies operations and viewer authorization.\n * JSON, Origin, and Fetch Metadata checks reject cross-site browser POSTs; they do not\n * authenticate another local process. Query evidence accompanies every result.\n */\nexport function createDataHandler(\n  operations: DataOperations,\n  authorize: (request: Request, operation: string) => Promise<RequestAccess>\n) {\n  async function handleDataRequest(request: Request): Promise<Response> {\n    const requestId = crypto.randomUUID();\n    const url = new URL(request.url);\n    if (!url.pathname.startsWith('/api/data/'))\n      return new Response('Not found', { status: 404 });\n    const encodedName = url.pathname.slice('/api/data/'.length);\n    if (!encodedName || encodedName.includes('/'))\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    let name: string;\n    try {\n      name = decodeURIComponent(encodedName);\n    } catch {\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    }\n    if (!Object.hasOwn(operations, name))\n      return problem(404, 'not_found', 'Unknown data operation.', requestId);\n    if (request.method !== 'POST')\n      return problem(405, 'method_not_allowed', 'Use POST.', requestId);\n    if (\n      request.headers\n        .get('content-type')\n        ?.split(';')[0]\n        ?.trim()\n        .toLowerCase() !== 'application/json'\n    )\n      return problem(\n        415,\n        'unsupported_media_type',\n        'Use application/json.',\n        requestId\n      );\n    const origin = request.headers.get('origin');\n    const fetchSite = request.headers.get('sec-fetch-site');\n    const fetchMode = request.headers.get('sec-fetch-mode');\n    if (\n      (origin !== null && origin !== url.origin) ||\n      (fetchSite !== null && fetchSite !== 'same-origin') ||\n      (fetchSite !== null && origin === null) ||\n      (fetchMode !== null &&\n        fetchMode !== 'cors' &&\n        fetchMode !== 'same-origin')\n    )\n      return problem(\n        403,\n        'cross_origin_request',\n        'The data request must come from this app.',\n        requestId\n      );\n    let access: RequestAccess;\n    try {\n      access = await authorize(request, name);\n    } catch {\n      return problem(\n        403,\n        'forbidden',\n        'You cannot run this data operation.',\n        requestId\n      );\n    }\n    const operation = operations[name]!;\n    let input: unknown;\n    if (request.signal.aborted)\n      return problem(504, 'timeout', 'The data request timed out.', requestId);\n    try {\n      const body = await readInput(request);\n      input = JSON.parse(body);\n    } catch (error) {\n      if (error instanceof InputTooLargeError)\n        return problem(\n          413,\n          'input_too_large',\n          'Input is too large.',\n          requestId\n        );\n\n      return problem(\n        400,\n        'invalid_input',\n        \"Check this operation's inputs.\",\n        requestId\n      );\n    }\n    const signal = request.signal;\n    try {\n      const { serializedBody } = await executeDataOperation(operation, input, {\n        lakehouse: access.lakehouse,\n        signal,\n        requestId,\n        operationName: name,\n        queryParams: access.queryParams,\n      });\n      return new Response(serializedBody, {\n        headers: {\n          'cache-control': 'no-store',\n          'content-type': 'application/json',\n        },\n      });\n    } catch (error) {\n      const source = error instanceof DataSourceError ? error : null;\n      console.error(\n        `Data operation ${name} failed (${requestId}): ${source ? `${source.reason}${source.status ? ` (${source.status})` : ''}${source.queryName ? ` in ${source.queryName}` : ''}` : error instanceof Error ? error.name : 'unknown'}`\n      );\n      const failure = toDataOperationFailure(error, signal.aborted);\n\n      return problem(failure.status, failure.code, failure.message, requestId);\n    }\n  }\n\n  return handleDataRequest;\n}\n\nfunction problem(\n  status: number,\n  code: string,\n  message: string,\n  requestId: string\n): Response {\n  return Response.json(\n    { error: { code, message, requestId } },\n    { status, headers: { 'cache-control': 'no-store' } }\n  );\n}\n\nconst MAX_INPUT_BYTES = 16_384;\nclass InputTooLargeError extends Error {}\n\n/** Count encoded bytes before retaining chunks; cancellation also interrupts waiting reads. */\nasync function readInput(request: Request): Promise<string> {\n  const reader = request.body?.getReader();\n  if (!reader) return '';\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n  let abort: (() => void) | undefined;\n\n  function cancelReader() {\n    // The source's cancel algorithm may never settle; the handler must still respond.\n    void reader!.cancel().catch(() => {});\n  }\n\n  try {\n    request.signal.throwIfAborted();\n    const cancelled = new Promise<never>((_, reject) => {\n      function rejectAborted() {\n        reject(new Error('Request aborted.'));\n        cancelReader();\n      }\n      abort = rejectAborted;\n      request.signal.addEventListener('abort', rejectAborted, { once: true });\n      if (request.signal.aborted) rejectAborted();\n    });\n    while (true) {\n      const { done, value } = await Promise.race([reader.read(), cancelled]);\n      if (done) break;\n      size += value.byteLength;\n      if (size > MAX_INPUT_BYTES) {\n        cancelReader();\n        throw new InputTooLargeError();\n      }\n      chunks.push(value);\n    }\n    const bytes = new Uint8Array(size);\n    let offset = 0;\n    for (const chunk of chunks) {\n      bytes.set(chunk, offset);\n      offset += chunk.byteLength;\n    }\n\n    return new TextDecoder().decode(bytes);\n  } finally {\n    if (abort) request.signal.removeEventListener('abort', abort);\n    reader.releaseLock();\n  }\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "97D671C00924C2DF64756E2164756E21",
+  "mappings": "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",
+  "debugId": "A8B5257A307F4C0764756E2164756E21",
   "names": []
 }

package/dist/types/client/annotations.d.ts

@@ -2,6 +2,10 @@ import { type DataAppAnnotationDraft } from '../core/annotations.js';
 import type { MessageTransport } from '../core/messages.js';
 /** Deliver annotations to the authenticated host. Acknowledgement means retained, not sent to an agent. */
 export declare function createAnnotationClient(transport: MessageTransport): {
+    /** Ask the host to submit its saved annotations using its existing send guards. */
+    requestSendAnnotations(options?: {
+        signal?: AbortSignal;
+    }): Promise<null>;
     /** Report the iframe editor's status so the host can guard batch submission. */
     reportAnnotationEditorState(state: {
         hasUnsavedChanges: boolean;

package/dist/types/client/data-client.d.ts

@@ -3,8 +3,7 @@ import type { DataTransport } from './transport.js';
 import type { DataQueryBody, InputOf, OutputOf } from '../core/operation-types.js';
 export type { InputOf, OutputOf } from '../core/operation-types.js';
 /**
- * Parsed operation data and query evidence. `queries` is present only when SQL disclosure is
- * allowed.
+ * Parsed operation data and query evidence.
  */
 export type DataResponse<Output, Input = unknown> = DataQueryBody<Output> & {
     /** The exact browser input that produced this response. */

package/dist/types/client/iframe.d.ts

@@ -12,10 +12,11 @@ export declare function createIframeTransport({ parentOrigin, window: frame, tim
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {
-        queryAll(statement: string, { limit, signal }: {
+        queryAll(statement: string, { limit, signal, params }: {
             limit: number;
             signal: AbortSignal;
             name?: string;
+            params?: import("../core/contract.js").QueryParameters;
         }): Promise<import("../core/contract.js").QueryResult>;
     };
     dispose: () => void;
@@ -39,10 +40,11 @@ export declare function getDataAppTransport(frame?: Window): {
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {
-        queryAll(statement: string, { limit, signal }: {
+        queryAll(statement: string, { limit, signal, params }: {
             limit: number;
             signal: AbortSignal;
             name?: string;
+            params?: import("../core/contract.js").QueryParameters;
         }): Promise<import("../core/contract.js").QueryResult>;
     };
     dispose: () => void;

package/dist/types/core/annotations.d.ts

@@ -81,6 +81,8 @@ export declare const annotationDraftRoute: import("./messages.js").MessageRoute<
 export declare const annotationEditorStateRoute: import("./messages.js").MessageRoute<{
     hasUnsavedChanges: boolean;
 }, null>;
+/** Request host-owned batch submission without transferring ownership of drafts. */
+export declare const annotationSendRoute: import("./messages.js").MessageRoute<null, null>;
 export declare const annotationUpdateRoute: import("./messages.js").MessageRoute<{
     id: string;
     comment: string;

package/dist/types/core/config.d.ts

@@ -1,15 +1,59 @@
 /**
- * App identity and display scope shared by browser and server.
- * @module @altertable/data-app/config
+ * App configuration shared by browser and server.
+ * @module @altertable/data-app
  */
+import { defineOperation } from './contract.js';
 import type { AppearanceOptions } from './appearance.js';
-export type DataAppConfig = {
+import { type QueryDefinitions } from './queries.js';
+export type { QueryDefinitions, QueryParameterValue } from './queries.js';
+export type DataAppConfig<Queries extends QueryDefinitions = QueryDefinitions> = {
     title: string;
     /** Display labels; scope does not grant data access. */
     scope: {
         organization: string;
         environment: string;
     };
-    appearance: AppearanceOptions;
+    /** Explain what the app helps readers explore. */
+    description: string;
+    /** Omit to use the standard appearance. */
+    appearance?: AppearanceOptions;
+    /** Named SQL statements and parameter defaults used by app operations. */
+    queries: Queries;
 };
+type ImmutableQueries<Queries extends QueryDefinitions> = {
+    readonly [Name in keyof Queries]: {
+        readonly statement: Queries[Name]['statement'];
+        readonly params: {
+            readonly [Param in keyof Queries[Name]['params']]: Readonly<Queries[Name]['params'][Param]>;
+        };
+    };
+};
+/** An app declaration with operations bound to its query registry. */
+export type DataAppDefinition<Queries extends QueryDefinitions = QueryDefinitions> = Readonly<Omit<DataAppConfig<Queries>, 'queries'>> & {
+    readonly queries: ImmutableQueries<Queries>;
+    defineOperation<Input, Output>(operation: Omit<Parameters<typeof defineOperation<Input, Output, Queries>>[0], 'queries'>): ReturnType<typeof defineOperation<Input, Output, Queries>>;
+};
+/**
+ * Define the app's query source of truth while preserving exact query and parameter names.
+ * Use `app.defineOperation()` to bind operations to these queries. Pass the app once
+ * to `mountDataApp({ app, component })` or `<DataAppProvider app={app}>`.
+ * The app owns an immutable snapshot of its registry; later input mutations do not change it.
+ * This declaration does not execute queries or mount UI. Static apps use `queries: {}`.
+ *
+ * Declare exactly one module-level const initialized with `defineDataApp({ ... })` in the app's
+ * declaration source. For the future backend extractor, the argument is read before bundling
+ * by resolving the named `defineDataApp` import from `@altertable/data-app`, including aliases.
+ * Variable name is arbitrary;
+ * export only for imports by other modules. The argument must be a direct object literal
+ * containing schema-valid objects, arrays, strings (including templates without interpolation),
+ * finite signed numbers, booleans, and null. No spreads, computed keys, references, calls,
+ * or callbacks inside it. Extraction must validate data without evaluating app code.
+ * TypeScript checks the shape, not AST syntax. Keep executable composition outside the call.
+ *
+ * SQL passes unchanged to the backend, which interprets placeholders such as `$orgId`.
+ * Declare every parameter with `{ defaultValue: value }` or `{}` for a required value.
+ * Values are finite numbers, strings, booleans, or null, never SQL fragments or identifiers.
+ * Caller values override defaults; trusted server `queryParams` cannot be overridden.
+ */
+export declare function defineDataApp<const Queries extends QueryDefinitions>(config: DataAppConfig<Queries>): DataAppDefinition<Queries>;
 export declare function dataAppTitle(config: Pick<DataAppConfig, 'title' | 'scope'>): string;

package/dist/types/core/contract.d.ts

@@ -1,3 +1,5 @@
+import { type QueryDefinitions, type QueryParameterValue } from './queries.js';
+export type { QueryDefinitions, QueryParameters, QueryParameterValue, } from './queries.js';
 import type { DateRange as DateRangeInput } from './date-range.js';
 import type { QueryResult, DataOperation, OperationContext } from './operation-types.js';
 export type { QueryResult, DisclosedQuery, Lakehouse, OperationContext, DataOperation, DataOperations, } from './operation-types.js';
@@ -69,26 +71,32 @@ export declare class DataSourceError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(reason: 'unauthorized' | 'forbidden' | 'rate_limited' | 'query_rejected' | 'unavailable', status?: number | undefined);
 }
-export type OperationQuery<Names extends Readonly<Record<string, string>>> = (name: Names[keyof Names], statement: string, options?: {
+type RegisteredQueryParameters<Queries extends QueryDefinitions, Name extends keyof Queries> = keyof Queries[Name]['params'] extends never ? Record<string, never> : Partial<Record<keyof Queries[Name]['params'], QueryParameterValue>>;
+export type RegisteredQuery<Queries extends QueryDefinitions> = <Name extends keyof Queries & string, const Params extends object = {}>(name: Name, params?: Params & NoInfer<RegisteredQueryParameters<Queries, Name>> & NoInfer<Record<Exclude<keyof Params, keyof Queries[Name]['params']>, never>> & NoInfer<Params extends (...args: never[]) => unknown ? never : object>, options?: {
     limit?: number;
 }) => Promise<QueryResult>;
-export declare function defineOperation<Input, Output, const Names extends Readonly<Record<string, string>> = Record<string, never>>(operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {
-    queryNames?: Names;
-    run: (context: OperationContext & {
-        query: OperationQuery<NoInfer<Names>>;
+export declare function defineOperation<Input, Output, const Queries extends QueryDefinitions>(operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {
+    queries: Queries;
+    run: (context: Pick<OperationContext, 'signal'> & {
+        query: RegisteredQuery<NoInfer<Queries>>;
     }, input: Input) => Promise<Output>;
-}): DataOperation<Input, Output> & {
-    queryNames?: Names;
+}): Omit<DataOperation<Input, Output>, 'queryNames'> & {
+    queryNames: {
+        readonly [Name in keyof Queries & string]: Name;
+    };
 };
-export declare const connectionQueryNames: {
-    readonly connection: "connection-check";
+/** A connectivity probe uses the app's registered connection query. */
+export declare function connectionCheck<const Queries extends QueryDefinitions & {
+    connection: QueryDefinitions[string];
+}>(queries: Queries): Omit<DataOperation<Record<string, never>, true>, "queryNames"> & {
+    queryNames: { readonly [Name in keyof Queries & string]: Name; };
 };
-/** Success requires a bounded SQL query; it does not establish access to a particular dataset. */
-export declare function connectionCheck(): DataOperation<Record<string, never>, true>;
 export { dimensionFilter, parseDimensionSelection, parseFacetOptions, dimensionPredicate, } from './dimension.js';
 export type { DimensionSelection, DimensionMember, DimensionOption, DimensionVariable, DimensionFilterOptions, } from './dimension.js';
 export { createMessageRouter, defineMessageRoute, defineDataQueryRoute, MessageRoutingError, dataAppRoutes, navigationUpdateRoute, sqlQueryRoute, } from './messages.js';
 export type { MessageContext, RoutedMessage, MessageDispatcher, MessageTransport, MessageRoute, MessageRoutes, MessageInput, MessageHandlers, MessageOutput, OperationContracts, DataQueryInput, DataQueryBody, DataQueryRoute, NavigationUpdate, SqlQueryInput, } from './messages.js';
 export type { TransportResponse } from './bridge.js';
-export { annotationDraftRoute, annotationModeRoute, annotationEditorStateRoute, annotationUpdateRoute, parseDataAppAnnotationDraft, } from './annotations.js';
+export { annotationDraftRoute, annotationModeRoute, annotationEditorStateRoute, annotationSendRoute, annotationUpdateRoute, parseDataAppAnnotationDraft, } from './annotations.js';
 export type { DataAppAnnotationDraft, DataAppAnnotationPresentation, } from './annotations.js';
+export { numberFilter, booleanFilter, parseNumberSelection, parseBooleanSelection, } from './filters.js';
+export type { NumberSelection, NumberOperator, NumberFilter, BooleanSelection, BooleanFilter, } from './filters.js';

package/dist/types/core/dimension.d.ts

@@ -9,7 +9,7 @@ export type DimensionMember<T extends DimensionValue = DimensionValue> = {
 export type DimensionSelection<T extends DimensionValue = DimensionValue> = {
     kind: 'all';
 } | {
-    kind: 'include';
+    kind: 'include' | 'exclude';
     members: readonly DimensionMember<T>[];
 };
 export type DimensionOption<T extends DimensionValue = DimensionValue> = {
@@ -17,11 +17,12 @@ export type DimensionOption<T extends DimensionValue = DimensionValue> = {
     label: string;
     count?: number;
 };
-export type DimensionVariable<T extends DimensionValue = DimensionValue> = Omit<AppVariable<DimensionSelection<T>, 'dimension'>, 'options'> & {
+export type DimensionVariable<T extends DimensionValue = DimensionValue> = AppVariable<DimensionSelection<T>, 'dimension'> & {
     label: string;
-    selection: 'single' | 'multiple';
+    selectionMode: 'single' | 'multiple';
     valueType: 'string' | 'number';
     allowMissing: boolean;
+    allowExclusion: boolean;
     maxSelected: number;
     options: readonly DimensionOption<T>[];
     facet?: {
@@ -35,8 +36,9 @@ export type DimensionFilterOptions<T extends DimensionValue> = {
     key: string;
     label: string;
     valueType: T extends number ? 'number' : 'string';
-    selection: 'single' | 'multiple';
+    selectionMode: 'single' | 'multiple';
     allowMissing?: boolean;
+    allowExclusion?: boolean;
     maxSelected?: number;
     history?: HistoryMode;
 } & ({

package/dist/types/core/filters.d.ts

@@ -0,0 +1,44 @@
+import type { AppVariable, HistoryMode } from './variables.js';
+export type NumberOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+export type NumberSelection = {
+    kind: 'all';
+} | {
+    kind: 'comparison';
+    operator: NumberOperator;
+    value: number;
+} | {
+    kind: 'range';
+    min?: number;
+    max?: number;
+};
+export type BooleanSelection = {
+    kind: 'all';
+} | {
+    kind: 'is';
+    value: boolean;
+};
+export type NumberFilter = AppVariable<NumberSelection, 'numberFilter'> & {
+    label: string;
+    min?: number;
+    max?: number;
+};
+export type BooleanFilter = AppVariable<BooleanSelection, 'booleanFilter'> & {
+    label: string;
+};
+type FilterOptions<Value> = {
+    key: string;
+    label: string;
+    defaultValue?: Value;
+    history?: HistoryMode;
+};
+export declare const numberOperatorLabels: Record<NumberOperator, string>;
+/** Exact numeric predicates; range bounds are inclusive and may be open-ended. */
+export declare function numberFilter({ key, label, min, max, defaultValue, history, }: FilterOptions<NumberSelection> & {
+    min?: number;
+    max?: number;
+}): NumberFilter;
+/** Boolean predicate with a distinct unrestricted state. */
+export declare function booleanFilter({ key, label, defaultValue, history, }: FilterOptions<BooleanSelection>): BooleanFilter;
+export declare function parseNumberSelection(value: unknown, filter: NumberFilter): NumberSelection;
+export declare function parseBooleanSelection(value: unknown, filter: BooleanFilter): BooleanSelection;
+export {};

package/dist/types/core/messages.d.ts

@@ -1,3 +1,4 @@
+import { type QueryParameters } from './queries.js';
 import type { TransportResponse, QueryResult, OperationContracts, DataQueryInput, DataQueryBody, OutputOf } from './operation-types.js';
 export type { OperationContracts, DataQueryInput, DataQueryBody, } from './operation-types.js';
 import { type NavigationUpdate } from './navigation.js';
@@ -49,6 +50,7 @@ export declare const navigationUpdateRoute: MessageRoute<NavigationUpdate, null>
 export type SqlQueryInput = {
     statement: string;
     limit: number;
+    params?: QueryParameters;
 };
 /** SQL delivery for browser-owned operations. Hosts must enforce backend access and resource limits. */
 export declare const sqlQueryRoute: MessageRoute<SqlQueryInput, QueryResult>;

package/dist/types/core/operation-types.d.ts

@@ -1,4 +1,5 @@
 /** Shared operation, query, and response contracts; independent of delivery adapters. */
+import type { QueryParameters } from './queries.js';
 export type OperationContracts = Record<string, {
     input: (value: unknown) => unknown;
     output: (value: unknown) => unknown;
@@ -17,10 +18,11 @@ export type QueryResult = {
     rows: unknown[][];
     queryId?: string;
 };
-/** One named statement an operation ran. Returned only when SQL disclosure is allowed. */
+/** One registered statement an operation ran, with its parameter values. */
 export type DisclosedQuery = {
     name: string;
     statement: string;
+    params?: QueryParameters;
     queryId?: string;
 };
 /** Query interface supplied by a server adapter or an authorized iframe bridge. */
@@ -29,11 +31,13 @@ export type Lakehouse = {
         limit: number;
         signal: AbortSignal;
         name?: string;
+        params?: QueryParameters;
     }): Promise<QueryResult>;
 };
 export type OperationContext = {
     lakehouse: Lakehouse;
     signal: AbortSignal;
+    queryParams?: QueryParameters;
 };
 /**
  * Parsers run in the operation executor's runtime: server for HTTP apps, browser for bundle apps.
@@ -49,7 +53,6 @@ export type DataOperation<Input, Output> = {
         maxQueryRows: number;
         maxDurationMs: number;
         maxResponseBytes?: number;
-        exposeSql?: boolean;
     };
 };
 /** Heterogeneous registry: inputs vary per operation, so checks retain unknown values. */