@ultimat3/query 29.3.1 → 29.4.0

package/src/query.ts

@@ -15,6 +15,8 @@ import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryCacheScope } from './cache';
 import type { QueryClientMethodOf, QueryClientOptions } from './client';
+import type { DownloadQuery, DownloadQueryDef, QueryDownload } from './download';
+import { assertDownloadDef, buildDownloadQuery } from './download';
 import { QueryCacheTtlInvalidError, QuerySingleInvalidError } from './errors';
 import { facadeFor } from './facade';
 import { assertEncodableInput } from './input-shape';
@@ -118,6 +120,11 @@ export interface QueryDef<
    * `X_QUERY_AUDIT_SINK_MISSING` before the input is parsed.
    */
   readonly audit?: boolean;
+  /**
+   * Absent on a rows read, by type: a declaration holding `sql` AND `download` — a variable, where
+   * no excess-property check reaches — must match neither `query()` overload. `download.ts`.
+   */
+  readonly download?: never;
 }
 
 export interface QueryOptions {
@@ -190,6 +197,8 @@ export interface QueryDescriptor {
   readonly ttlMs: number | null;
   readonly rateLimit: QueryRateLimit | null;
   readonly deprecated: Deprecation | null;
+  /** Declared `download:` — the read answers a file at a signed URL, never rows. */
+  readonly download: boolean;
 }
 
 /**
@@ -210,6 +219,8 @@ export interface AnyQueryDef {
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
   readonly audit?: boolean;
+  /** A download's handler. Private like `sql`: `download.ts` reaches it through `defOf`. */
+  readonly download?: QueryDownload<StandardSchemaV1>;
 }
 
 export interface AnyQuery {
@@ -231,6 +242,8 @@ export interface AnyQuery {
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
+  /** `true` on a `query({ download })` — the route mints a URL or serves a file. Absent otherwise. */
+  readonly download?: true;
   describe(): QueryDescriptor;
   /** A twin under another name. Registration names through `named`. */
   named(name: string): AnyQuery;
@@ -288,15 +301,33 @@ export type QueryFacade<
   | 'client'
 >;
 
+/**
+ * A read whose answer is a FILE at a short-lived signed URL — `download.ts`. Same primitive: one
+ * policy, one name, one route; `sql` and every rows option are refused beside it.
+ */
+export function query<TInput extends StandardSchemaV1>(
+  def: DownloadQueryDef<TInput>,
+): DownloadQuery<TInput>;
 export function query<
   TInput extends StandardSchemaV1,
   TRow extends object,
   TSingle extends boolean = false,
->(def: QueryDef<TInput, TRow, TSingle>): Query<TInput, TRow, TSingle> {
+>(def: QueryDef<TInput, TRow, TSingle>): Query<TInput, TRow, TSingle>;
+export function query<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean = false,
+>(
+  def: QueryDef<TInput, TRow, TSingle> | DownloadQueryDef<TInput>,
+): Query<TInput, TRow, TSingle> | DownloadQuery<TInput> {
   // Here and not in `toQueryRoute`: a read is projected to `GET /_x/query/<kebab>` whether or not
   // anyone mounts it, and the typed client derives that same URL — so an input a query string
   // cannot carry is wrong for every call, and the file that declared it is where it is repaired.
   assertEncodableInput(def.input);
+  if (isDownloadDef(def)) {
+    assertDownloadDef(def);
+    return buildDownloadQuery(def, '', describeQuery);
+  }
   assertCacheTtl(def.cache);
   assertSubscribes(def.subscribes, def.live);
   // A JS caller or generated code can write `single: 'yes'`; truthiness would read it as `true`
@@ -312,6 +343,12 @@ export function query<
   return build(subscribes === undefined ? def : { ...def, subscribes }, '');
 }
 
+function isDownloadDef<TInput extends StandardSchemaV1>(
+  def: QueryDef<TInput, object, boolean> | DownloadQueryDef<TInput>,
+): def is DownloadQueryDef<TInput> {
+  return 'download' in def && def.download !== undefined;
+}
+
 /**
  * The same rule, for the same reason: a lease every `CacheTier` refuses is wrong for every read of
  * this query, so it fails on the line that wrote it rather than on the first request. Positive and
@@ -384,6 +421,7 @@ export function describeQuery(target: AnyQuery): QueryDescriptor {
     ttlMs: target.cache?.ttlMs ?? null,
     rateLimit: target.rateLimit ?? null,
     deprecated: target.deprecated ?? null,
+    download: target.download === true,
   };
 }
 

package/src/read.ts

@@ -258,6 +258,45 @@ async function buildSource(
   options: SourceOptions,
   trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
+  const input = await admit(target, raw, ctx, options, trace);
+  const source = defOf(target).sql(input, ctx);
+  // A live window is served in the order its patches are placed in. The matcher breaks a tie on
+  // the declared keys with `id` (`totalOrder`) and so does the keyset re-read a reconnect resumes
+  // with, so an initial window served in the declared keys alone puts tied rows where neither of
+  // them would: the client renders one order and the next read answers another. A source that
+  // cannot say (`total` absent) already serves one order it can be resumed in.
+  return options.surface === 'live' && source.total !== undefined ? source.total() : source;
+}
+
+/**
+ * One whole call for a read that is ANSWERED by something other than `sql` — a download's file,
+ * or the URL minted for it. The same front half every surface shares (actor, audit, the declared
+ * limit, the parse, the policy), so a download is not a second read path: only what is done with
+ * the admitted input differs. `options.unenforced` is honoured exactly as `sourceFor` honours it.
+ */
+export function admittedCall<T>(
+  target: AnyQuery,
+  raw: unknown,
+  options: SourceOptions,
+  use: (input: unknown, ctx: Ctx) => Promise<T>,
+): Promise<T> {
+  return asActor(options, async (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    if (audit === null) return use(await admit(target, raw, ctx, options, null), ctx);
+    return audited(audit, async () =>
+      use(await admit(target, raw, ctx, options, audit.trace), ctx),
+    );
+  });
+}
+
+/** Everything before `sql()`: the actor half, the declared limit, the parse, the policy. */
+async function admit(
+  target: AnyQuery,
+  raw: unknown,
+  ctx: Ctx,
+  options: SourceOptions,
+  trace: ReadTrace | null,
+): Promise<unknown> {
   const def = defOf(target);
   const name = queryName(target);
   const unenforced = options.unenforced;
@@ -312,13 +351,7 @@ async function buildSource(
     // comparison when nothing is listening.
     logger.debug('query.policy.unenforced', { query: name, reason: unenforced });
   }
-  const source = def.sql(input, ctx);
-  // A live window is served in the order its patches are placed in. The matcher breaks a tie on
-  // the declared keys with `id` (`totalOrder`) and so does the keyset re-read a reconnect resumes
-  // with, so an initial window served in the declared keys alone puts tied rows where neither of
-  // them would: the client renders one order and the next read answers another. A source that
-  // cannot say (`total` absent) already serves one order it can be resumed in.
-  return options.surface === 'live' && source.total !== undefined ? source.total() : source;
+  return input;
 }
 
 /** The parse without the refusal — only for the record of a read already refused on other grounds. */

package/src/search-string.ts

@@ -0,0 +1,47 @@
+// The read's input as a search string — the ONE encoding the typed client sends and a download's
+// minted URL carries, so the route's `coerceQuery` reads both back the same way. A leaf: the
+// browser client imports it, and it imports nothing that registers a code table.
+
+import { isJsonObject } from '@ultimat3/core/page';
+import type { PageControls } from './page-controls';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
+
+/**
+ * Input as a query string. Keys are sorted so the same input always produces the
+ * same URL — a GET is a cache key, and an unstable one caches nothing.
+ *
+ * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
+ * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
+ * split at `_first=` to recover the read underneath.
+ *
+ * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
+ * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
+ */
+export function searchOf(input: unknown, page?: PageControls): string {
+  const params = new URLSearchParams();
+  if (isJsonObject(input)) {
+    for (const key of Object.keys(input).sort()) {
+      const value = input[key];
+      if (value === undefined || value === null) continue;
+      for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
+        params.append(key, wireText(item));
+      }
+    }
+  }
+  if (page !== undefined) {
+    params.append(PAGE_FIRST_KEY, String(page.first));
+    if (page.after !== undefined) params.append(PAGE_AFTER_KEY, page.after);
+  }
+  return params.toString();
+}
+
+/**
+ * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
+ * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
+ * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
+ * as the text it prints and the read's own schema says what is wrong with it.
+ */
+function wireText(item: unknown): string {
+  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
+  return typeof item === 'object' ? JSON.stringify(item) : String(item);
+}

package/src/sql.ts

@@ -62,7 +62,8 @@ export async function describeSql(
     // `Object.hasOwn`, because `samples` is a caller's object literal and a name it never carried
     // — `constructor`, `toString` — would otherwise resolve to a FUNCTION and be parsed as input.
     const sample = Object.hasOwn(samples, name) ? samples[name] : undefined;
-    if (sample === undefined) {
+    // A download has no statement to render, sample or not: it answers a file.
+    if (sample === undefined || target.download === true) {
       entries.push({ query: name, live: target.isLive, sql: null });
       continue;
     }

package/src/type-pins.ts

@@ -5,6 +5,13 @@
 
 import type { McpExposureDeclaration } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { QueryClient } from './client';
+import type {
+  DownloadClientMethod,
+  DownloadQuery,
+  DownloadQueryDef,
+  QueryDownload,
+} from './download';
 import type { AnyQuery, Query, QueryDef } from './query';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
@@ -60,3 +67,41 @@ export type _NoQueryMcpTwin = import('./index').QueryMcp;
 export type _NoQueryMcpAnnotationsTwin = import('./index').QueryMcpAnnotations;
 // @ts-expect-error — `QueryListParams` is core's `McpListParams`.
 export type _NoQueryListParamsTwin = import('./index').QueryListParams;
+
+/**
+ * A download query's client is `url()` and nothing else: no rows call, no `page` — the route
+ * answers a minted URL or a file, never rows, so a method that promised rows would be a lie.
+ */
+type DownloadInput = StandardSchemaV1<{ runId: string }, { runId: string }>;
+export type _DownloadClientIsUrlOnly = Assert<
+  Identical<
+    QueryClient<{ rec: DownloadQuery<DownloadInput> }>['rec'],
+    DownloadClientMethod<DownloadInput>
+  >
+>;
+/** And a download declares no rows option: `sql` beside `download` does not compile. */
+export type _DownloadDeclaresNoSql = Assert<
+  Equals<NonNullable<DownloadQueryDef<DownloadInput>['sql']>, never>
+>;
+
+/**
+ * And the other way: a rows declaration names `download?: never`, so a VARIABLE holding both `sql`
+ * and `download` (no excess-property check reaches one) matches neither overload — a compile
+ * error where it is written, never `X_QUERY_DOWNLOAD_INVALID` on the first call.
+ */
+type RowsDownload =
+  QueryDef<DownloadInput, object> extends { readonly download?: infer D } ? D : 'absent';
+export type _RowsDeclareNoDownload = Assert<Equals<NonNullable<RowsDownload>, never>>;
+export type _BothDoNotCompile = Assert<
+  Equals<
+    {
+      input: DownloadInput;
+      policy: QueryDef<DownloadInput, object>['policy'];
+      sql: () => never;
+      download: QueryDownload<DownloadInput>;
+    } extends QueryDef<DownloadInput, object> | DownloadQueryDef<DownloadInput>
+      ? true
+      : false,
+    false
+  >
+>;