@duckedup/nidus 0.99.0 → 0.101.0

package/dist/index.d.cts

@@ -33,18 +33,26 @@ interface NidusRecord {
     id: string;
     /** Omit for a text-only doc (indexed by FTS/metadata only, never by vector search). */
     vector?: number[];
+    /**
+     * Named vectors beyond the reserved `"default"` vector above (nidus-85t), keyed by
+     * name. Each name must be declared on the collection first with
+     * {@link NidusClient.setVectorNames}, and every vector must be the store's dimension.
+     */
+    vectors?: Record<string, number[]>;
     attrs: Record<string, Value>;
 }
 /** Like {@link NidusRecord} but accepts plain JS values in `attrs` (auto-normalized). */
 interface RecordInput {
     id: string;
     vector?: number[];
+    vectors?: Record<string, number[]>;
     attrs: Record<string, AttrInput>;
 }
 /** A record read back from the server, with `attrs` decoded to plain JS values. */
 interface DecodedRecord {
     id: string;
     vector?: number[];
+    vectors?: Record<string, number[]>;
     attrs: Record<string, DecodedValue>;
 }
 /** A single attribute predicate, externally tagged as `nidus` encodes `Predicate`. */
@@ -355,6 +363,13 @@ interface OrderBy {
     field: string;
     descending?: boolean;
 }
+/**
+ * How several named-vector scores fold into one per-record score, before top-k
+ * selection (nidus-85t). `"Max"` (the default) takes the best weighted per-name score;
+ * an absent name then contributes nothing and carries no penalty. `"Sum"` adds every
+ * weighted named score. Meaningless when {@link SearchOptions.names} is empty.
+ */
+type Pool = "Max" | "Sum";
 /** Ranking knobs shared by {@link NidusClient.search} and {@link NidusClient.textSearch}. */
 interface RankingOptions {
     rankBy?: RankBy;
@@ -429,6 +444,21 @@ interface SearchOptions extends ProjectionOptions, RankingOptions {
     exact?: boolean;
     /** See {@link RerankOptions}. `query` is required here. */
     rerank?: RerankOptions;
+    /**
+     * Named vectors to score (nidus-85t), each declared on the collection first with
+     * {@link NidusClient.setVectorNames}. Omitted or empty (the default, and the only
+     * shape a pre-nidus-85t caller ever sends) searches only the reserved `"default"`
+     * vector, so an existing call is unaffected. A record is scored on whichever of
+     * these names it actually carries, reduced to one score by `pool`.
+     */
+    names?: string[];
+    /**
+     * Per-name weight multiplying that name's score before pooling. A name absent here
+     * weights `1`. Meaningless when `names` is empty.
+     */
+    nameWeights?: Record<string, number>;
+    /** How several named scores fold into one record score (default `"Max"`). See {@link Pool}. */
+    pool?: Pool;
 }
 /**
  * Options for {@link NidusClient.searchSimilar}. `collection`/`id` name the source
@@ -587,6 +617,13 @@ interface HybridSearchBase extends AnnotationOptions {
     expand?: Expand;
     /** See {@link RerankOptions}. `query` is required here. */
     rerank?: RerankOptions;
+    /**
+     * Cap the fused hits carrying any one value of an attribute (nidus-29ui). Applied on
+     * the shared cap → MMR → page-cut tail, same as {@link NidusClient.search}.
+     */
+    limitPer?: LimitPer;
+    /** MMR lambda spreading the fused page in vector space (nidus-29ui). See {@link RankingOptions.diversity}. */
+    diversity?: number;
 }
 /** Options for {@link NidusClient.hybridSearch} (vector + BM25 fused via RRF). */
 type HybridSearchOptions = HybridSearchBase & HybridQuerySpelling;
@@ -757,6 +794,47 @@ interface RecallOptions {
      */
     rankBy?: RankBy;
 }
+/**
+ * One statement's answer from {@link NidusClient.query}: a ranked/listed statement decodes
+ * to a bare {@link Hit} array, or to `{hits, plan}` when it asked `WITH (plan)`; a `GROUP BY`
+ * statement decodes to an {@link Aggregation}.
+ */
+type QueryAnswer = Hit[] | {
+    hits: Hit[];
+    plan: QueryPlan;
+} | Aggregation;
+/**
+ * One compiled statement from {@link NidusClient.compile}: the typed value the SQL front end
+ * would hand the matching `Store` method (`search`/`text_search`/`hybrid_search`/`list`/
+ * `aggregate`), rendered for introspection only. `opts` (and, for `text_search`/`hybrid`,
+ * `query`/`text`) are the server's raw snake_case JSON — never executed, so never decoded
+ * into this SDK's own camelCase option shapes.
+ */
+type Compiled = {
+    kind: "search";
+    collections: string[];
+    vector: number[];
+    opts: Record<string, unknown>;
+} | {
+    kind: "text_search";
+    collections: string[];
+    query: unknown;
+    opts: Record<string, unknown>;
+} | {
+    kind: "hybrid";
+    collections: string[];
+    vector: number[];
+    text: unknown;
+    opts: Record<string, unknown>;
+} | {
+    kind: "list";
+    collections: string[];
+    opts: Record<string, unknown>;
+} | {
+    kind: "aggregate";
+    collections: string[];
+    opts: Record<string, unknown>;
+};
 
 /** Minimal `fetch` signature the client needs — satisfied by the platform global. */
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
@@ -839,6 +917,12 @@ declare class NidusClient {
      * paid at write time and in memory. Pass an empty array to drop the declaration.
      */
     setFilterIndex(name: string, fields: (string | FilterIndexField)[]): Promise<void>;
+    /**
+     * Declare the named-vector fields a collection accepts on upsert and search, beyond
+     * the reserved `"default"` vector (nidus-85t). Upserting an undeclared name is a
+     * `400` naming it; mirrors {@link NidusClient.setFtsSchema}'s declare-then-use shape.
+     */
+    setVectorNames(name: string, names: string[]): Promise<void>;
     /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
     search(opts: SearchOptions): Promise<Hit[]>;
     /** Like {@link NidusClient.search}, but also reports the scan strategy the server took. */
@@ -892,6 +976,22 @@ declare class NidusClient {
      * in-RAM index alone — no record is built and no vector is read.
      */
     aggregate(opts?: AggregateOptions): Promise<Aggregation>;
+    /**
+     * Compile and run a `SELECT ...` script against `POST /query` (SPEC §7.12). A single
+     * statement decodes to its own answer (hits, `{hits, plan}`, or an {@link Aggregation});
+     * a `;`-separated script answers one {@link QueryAnswer} per statement, in request order.
+     * A parse error rejects with the server's message verbatim (byte offset and §7 section).
+     */
+    query(sql: string): Promise<QueryAnswer | QueryAnswer[]>;
+    /**
+     * Compile a `SELECT ...` script without running it: the typed value(s) the matching
+     * `Store` method would receive. Always an array, one entry per `;`-separated statement.
+     */
+    compile(sql: string): Promise<Compiled[]>;
+    /** A wire hit's shape, distinguishing a bare hits-answer from a batch of answers. */
+    private isHitShaped;
+    /** Decode one statement's `/query` answer: hits (bare or `{hits, plan}`), or an aggregation. */
+    private decodeQueryAnswer;
     /**
      * Answer several vector queries in one round-trip (16 max). Returns one ranking per
      * query in request order, or — with `opts.fuse` — a single array holding the one fused
@@ -1052,4 +1152,4 @@ declare function decodeValue(value: Value): DecodedValue;
 /** Decode a whole wire `attrs` map back to plain JS values. */
 declare function decodeAttrs(attrs: Record<string, Value>): Record<string, DecodedValue>;
 
-export { type AggregateOptions, type Aggregation, type AnnInfo, type AnnotationOptions, type Annotations, type AttrInput, type ClauseScore, type ClusterStatus, type CodeFileHit, type CodeSearchOptions, type CodeSymbolHit, type Decay, type DecodedRecord, type DecodedValue, type Expand, type Expansion, type FetchLike, type Filter, type FilterIndexField, type Footprint, type Fragment, type FtsCombine, type FtsField, type Highlight, type HighlightOptions, type Hit, type HybridQuerySpelling, type HybridSearchBase, type HybridSearchOptions, type LegScore, type LimitPer, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type OrderBy, type PlanCandidates, type PlanNarrowing, type PlanTimings, type Predicate, type ProjectionOptions, type QueryPath, type QueryPlan, type RankBy, type RankingOptions, type Readiness, type RecallOptions, type RecordInput, type RememberOptions, type RememberResult, type RerankOptions, type Rollup, type SearchOptions, type SimilarSearchOptions, type Stats, type StoreVersions, type SuggestOptions, type Suggestion, type Suggestions, type TextClause, type TextQuerySpelling, type TextSearchBase, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };
+export { type AggregateOptions, type Aggregation, type AnnInfo, type AnnotationOptions, type Annotations, type AttrInput, type ClauseScore, type ClusterStatus, type CodeFileHit, type CodeSearchOptions, type CodeSymbolHit, type Compiled, type Decay, type DecodedRecord, type DecodedValue, type Expand, type Expansion, type FetchLike, type Filter, type FilterIndexField, type Footprint, type Fragment, type FtsCombine, type FtsField, type Highlight, type HighlightOptions, type Hit, type HybridQuerySpelling, type HybridSearchBase, type HybridSearchOptions, type LegScore, type LimitPer, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type OrderBy, type PlanCandidates, type PlanNarrowing, type PlanTimings, type Predicate, type ProjectionOptions, type QueryAnswer, type QueryPath, type QueryPlan, type RankBy, type RankingOptions, type Readiness, type RecallOptions, type RecordInput, type RememberOptions, type RememberResult, type RerankOptions, type Rollup, type SearchOptions, type SimilarSearchOptions, type Stats, type StoreVersions, type SuggestOptions, type Suggestion, type Suggestions, type TextClause, type TextQuerySpelling, type TextSearchBase, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };

package/dist/index.d.ts

@@ -33,18 +33,26 @@ interface NidusRecord {
     id: string;
     /** Omit for a text-only doc (indexed by FTS/metadata only, never by vector search). */
     vector?: number[];
+    /**
+     * Named vectors beyond the reserved `"default"` vector above (nidus-85t), keyed by
+     * name. Each name must be declared on the collection first with
+     * {@link NidusClient.setVectorNames}, and every vector must be the store's dimension.
+     */
+    vectors?: Record<string, number[]>;
     attrs: Record<string, Value>;
 }
 /** Like {@link NidusRecord} but accepts plain JS values in `attrs` (auto-normalized). */
 interface RecordInput {
     id: string;
     vector?: number[];
+    vectors?: Record<string, number[]>;
     attrs: Record<string, AttrInput>;
 }
 /** A record read back from the server, with `attrs` decoded to plain JS values. */
 interface DecodedRecord {
     id: string;
     vector?: number[];
+    vectors?: Record<string, number[]>;
     attrs: Record<string, DecodedValue>;
 }
 /** A single attribute predicate, externally tagged as `nidus` encodes `Predicate`. */
@@ -355,6 +363,13 @@ interface OrderBy {
     field: string;
     descending?: boolean;
 }
+/**
+ * How several named-vector scores fold into one per-record score, before top-k
+ * selection (nidus-85t). `"Max"` (the default) takes the best weighted per-name score;
+ * an absent name then contributes nothing and carries no penalty. `"Sum"` adds every
+ * weighted named score. Meaningless when {@link SearchOptions.names} is empty.
+ */
+type Pool = "Max" | "Sum";
 /** Ranking knobs shared by {@link NidusClient.search} and {@link NidusClient.textSearch}. */
 interface RankingOptions {
     rankBy?: RankBy;
@@ -429,6 +444,21 @@ interface SearchOptions extends ProjectionOptions, RankingOptions {
     exact?: boolean;
     /** See {@link RerankOptions}. `query` is required here. */
     rerank?: RerankOptions;
+    /**
+     * Named vectors to score (nidus-85t), each declared on the collection first with
+     * {@link NidusClient.setVectorNames}. Omitted or empty (the default, and the only
+     * shape a pre-nidus-85t caller ever sends) searches only the reserved `"default"`
+     * vector, so an existing call is unaffected. A record is scored on whichever of
+     * these names it actually carries, reduced to one score by `pool`.
+     */
+    names?: string[];
+    /**
+     * Per-name weight multiplying that name's score before pooling. A name absent here
+     * weights `1`. Meaningless when `names` is empty.
+     */
+    nameWeights?: Record<string, number>;
+    /** How several named scores fold into one record score (default `"Max"`). See {@link Pool}. */
+    pool?: Pool;
 }
 /**
  * Options for {@link NidusClient.searchSimilar}. `collection`/`id` name the source
@@ -587,6 +617,13 @@ interface HybridSearchBase extends AnnotationOptions {
     expand?: Expand;
     /** See {@link RerankOptions}. `query` is required here. */
     rerank?: RerankOptions;
+    /**
+     * Cap the fused hits carrying any one value of an attribute (nidus-29ui). Applied on
+     * the shared cap → MMR → page-cut tail, same as {@link NidusClient.search}.
+     */
+    limitPer?: LimitPer;
+    /** MMR lambda spreading the fused page in vector space (nidus-29ui). See {@link RankingOptions.diversity}. */
+    diversity?: number;
 }
 /** Options for {@link NidusClient.hybridSearch} (vector + BM25 fused via RRF). */
 type HybridSearchOptions = HybridSearchBase & HybridQuerySpelling;
@@ -757,6 +794,47 @@ interface RecallOptions {
      */
     rankBy?: RankBy;
 }
+/**
+ * One statement's answer from {@link NidusClient.query}: a ranked/listed statement decodes
+ * to a bare {@link Hit} array, or to `{hits, plan}` when it asked `WITH (plan)`; a `GROUP BY`
+ * statement decodes to an {@link Aggregation}.
+ */
+type QueryAnswer = Hit[] | {
+    hits: Hit[];
+    plan: QueryPlan;
+} | Aggregation;
+/**
+ * One compiled statement from {@link NidusClient.compile}: the typed value the SQL front end
+ * would hand the matching `Store` method (`search`/`text_search`/`hybrid_search`/`list`/
+ * `aggregate`), rendered for introspection only. `opts` (and, for `text_search`/`hybrid`,
+ * `query`/`text`) are the server's raw snake_case JSON — never executed, so never decoded
+ * into this SDK's own camelCase option shapes.
+ */
+type Compiled = {
+    kind: "search";
+    collections: string[];
+    vector: number[];
+    opts: Record<string, unknown>;
+} | {
+    kind: "text_search";
+    collections: string[];
+    query: unknown;
+    opts: Record<string, unknown>;
+} | {
+    kind: "hybrid";
+    collections: string[];
+    vector: number[];
+    text: unknown;
+    opts: Record<string, unknown>;
+} | {
+    kind: "list";
+    collections: string[];
+    opts: Record<string, unknown>;
+} | {
+    kind: "aggregate";
+    collections: string[];
+    opts: Record<string, unknown>;
+};
 
 /** Minimal `fetch` signature the client needs — satisfied by the platform global. */
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
@@ -839,6 +917,12 @@ declare class NidusClient {
      * paid at write time and in memory. Pass an empty array to drop the declaration.
      */
     setFilterIndex(name: string, fields: (string | FilterIndexField)[]): Promise<void>;
+    /**
+     * Declare the named-vector fields a collection accepts on upsert and search, beyond
+     * the reserved `"default"` vector (nidus-85t). Upserting an undeclared name is a
+     * `400` naming it; mirrors {@link NidusClient.setFtsSchema}'s declare-then-use shape.
+     */
+    setVectorNames(name: string, names: string[]): Promise<void>;
     /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
     search(opts: SearchOptions): Promise<Hit[]>;
     /** Like {@link NidusClient.search}, but also reports the scan strategy the server took. */
@@ -892,6 +976,22 @@ declare class NidusClient {
      * in-RAM index alone — no record is built and no vector is read.
      */
     aggregate(opts?: AggregateOptions): Promise<Aggregation>;
+    /**
+     * Compile and run a `SELECT ...` script against `POST /query` (SPEC §7.12). A single
+     * statement decodes to its own answer (hits, `{hits, plan}`, or an {@link Aggregation});
+     * a `;`-separated script answers one {@link QueryAnswer} per statement, in request order.
+     * A parse error rejects with the server's message verbatim (byte offset and §7 section).
+     */
+    query(sql: string): Promise<QueryAnswer | QueryAnswer[]>;
+    /**
+     * Compile a `SELECT ...` script without running it: the typed value(s) the matching
+     * `Store` method would receive. Always an array, one entry per `;`-separated statement.
+     */
+    compile(sql: string): Promise<Compiled[]>;
+    /** A wire hit's shape, distinguishing a bare hits-answer from a batch of answers. */
+    private isHitShaped;
+    /** Decode one statement's `/query` answer: hits (bare or `{hits, plan}`), or an aggregation. */
+    private decodeQueryAnswer;
     /**
      * Answer several vector queries in one round-trip (16 max). Returns one ranking per
      * query in request order, or — with `opts.fuse` — a single array holding the one fused
@@ -1052,4 +1152,4 @@ declare function decodeValue(value: Value): DecodedValue;
 /** Decode a whole wire `attrs` map back to plain JS values. */
 declare function decodeAttrs(attrs: Record<string, Value>): Record<string, DecodedValue>;
 
-export { type AggregateOptions, type Aggregation, type AnnInfo, type AnnotationOptions, type Annotations, type AttrInput, type ClauseScore, type ClusterStatus, type CodeFileHit, type CodeSearchOptions, type CodeSymbolHit, type Decay, type DecodedRecord, type DecodedValue, type Expand, type Expansion, type FetchLike, type Filter, type FilterIndexField, type Footprint, type Fragment, type FtsCombine, type FtsField, type Highlight, type HighlightOptions, type Hit, type HybridQuerySpelling, type HybridSearchBase, type HybridSearchOptions, type LegScore, type LimitPer, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type OrderBy, type PlanCandidates, type PlanNarrowing, type PlanTimings, type Predicate, type ProjectionOptions, type QueryPath, type QueryPlan, type RankBy, type RankingOptions, type Readiness, type RecallOptions, type RecordInput, type RememberOptions, type RememberResult, type RerankOptions, type Rollup, type SearchOptions, type SimilarSearchOptions, type Stats, type StoreVersions, type SuggestOptions, type Suggestion, type Suggestions, type TextClause, type TextQuerySpelling, type TextSearchBase, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };
+export { type AggregateOptions, type Aggregation, type AnnInfo, type AnnotationOptions, type Annotations, type AttrInput, type ClauseScore, type ClusterStatus, type CodeFileHit, type CodeSearchOptions, type CodeSymbolHit, type Compiled, type Decay, type DecodedRecord, type DecodedValue, type Expand, type Expansion, type FetchLike, type Filter, type FilterIndexField, type Footprint, type Fragment, type FtsCombine, type FtsField, type Highlight, type HighlightOptions, type Hit, type HybridQuerySpelling, type HybridSearchBase, type HybridSearchOptions, type LegScore, type LimitPer, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type OrderBy, type PlanCandidates, type PlanNarrowing, type PlanTimings, type Predicate, type ProjectionOptions, type QueryAnswer, type QueryPath, type QueryPlan, type RankBy, type RankingOptions, type Readiness, type RecallOptions, type RecordInput, type RememberOptions, type RememberResult, type RerankOptions, type Rollup, type SearchOptions, type SimilarSearchOptions, type Stats, type StoreVersions, type SuggestOptions, type Suggestion, type Suggestions, type TextClause, type TextQuerySpelling, type TextSearchBase, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };

package/dist/index.js

@@ -256,6 +256,7 @@ var NidusClient = class {
     const wire = records.map((r) => ({
       id: r.id,
       ...r.vector !== void 0 ? { vector: r.vector } : {},
+      ...r.vectors !== void 0 ? { vectors: r.vectors } : {},
       attrs: encodeAttrs(r.attrs)
     }));
     const res = await this.request(
@@ -292,6 +293,7 @@ var NidusClient = class {
     return recs.map((r) => ({
       id: r.id,
       ...r.vector !== void 0 ? { vector: r.vector } : {},
+      ...r.vectors !== void 0 ? { vectors: r.vectors } : {},
       attrs: decodeAttrs(r.attrs)
     }));
   }
@@ -319,6 +321,14 @@ var NidusClient = class {
       fields: fields.map(encodeFilterIndexField)
     });
   }
+  /**
+   * Declare the named-vector fields a collection accepts on upsert and search, beyond
+   * the reserved `"default"` vector (nidus-85t). Upserting an undeclared name is a
+   * `400` naming it; mirrors {@link NidusClient.setFtsSchema}'s declare-then-use shape.
+   */
+  async setVectorNames(name, names) {
+    await this.request("POST", `/collections/${enc(name)}/vector-names`, { names });
+  }
   // ── Search ──────────────────────────────────────────────────────────────
   /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
   search(opts) {
@@ -336,7 +346,10 @@ var NidusClient = class {
       limit_per: opts.limitPer,
       diversity: opts.diversity,
       expand: encodeExpand(opts.expand),
-      rerank: encodeRerank(opts.rerank)
+      rerank: encodeRerank(opts.rerank),
+      names: opts.names,
+      name_weights: opts.nameWeights,
+      pool: opts.pool
     });
   }
   /** Like {@link NidusClient.search}, but also reports the scan strategy the server took. */
@@ -355,7 +368,10 @@ var NidusClient = class {
       limit_per: opts.limitPer,
       diversity: opts.diversity,
       expand: encodeExpand(opts.expand),
-      rerank: encodeRerank(opts.rerank)
+      rerank: encodeRerank(opts.rerank),
+      names: opts.names,
+      name_weights: opts.nameWeights,
+      pool: opts.pool
     });
   }
   /** Records most like an existing one. The source record itself is never returned. */
@@ -491,7 +507,9 @@ var NidusClient = class {
       vector_weight: opts.vectorWeight,
       text_weight: opts.textWeight,
       expand: encodeExpand(opts.expand),
-      rerank: encodeRerank(opts.rerank)
+      rerank: encodeRerank(opts.rerank),
+      limit_per: opts.limitPer,
+      diversity: opts.diversity
     });
   }
   /** Like {@link NidusClient.hybridSearch}, but also reports the scan strategy taken. */
@@ -510,7 +528,9 @@ var NidusClient = class {
       vector_weight: opts.vectorWeight,
       text_weight: opts.textWeight,
       expand: encodeExpand(opts.expand),
-      rerank: encodeRerank(opts.rerank)
+      rerank: encodeRerank(opts.rerank),
+      limit_per: opts.limitPer,
+      diversity: opts.diversity
     });
   }
   /** Metadata-only listing (no vector), paginated by `offset`/`limit`. */
@@ -554,6 +574,60 @@ var NidusClient = class {
       ...res.groups_truncated ? { groupsTruncated: true } : {}
     };
   }
+  // ── SQL (SPEC §7.12) ────────────────────────────────────────────────────
+  /**
+   * Compile and run a `SELECT ...` script against `POST /query` (SPEC §7.12). A single
+   * statement decodes to its own answer (hits, `{hits, plan}`, or an {@link Aggregation});
+   * a `;`-separated script answers one {@link QueryAnswer} per statement, in request order.
+   * A parse error rejects with the server's message verbatim (byte offset and §7 section).
+   */
+  async query(sql) {
+    const raw = await this.request("POST", "/query", { sql });
+    if (Array.isArray(raw) && raw.length > 0 && !this.isHitShaped(raw[0])) {
+      return raw.map((a) => this.decodeQueryAnswer(a));
+    }
+    return this.decodeQueryAnswer(raw);
+  }
+  /**
+   * Compile a `SELECT ...` script without running it: the typed value(s) the matching
+   * `Store` method would receive. Always an array, one entry per `;`-separated statement.
+   */
+  async compile(sql) {
+    const raw = await this.request("POST", "/query", {
+      sql,
+      compile_only: true
+    });
+    return Array.isArray(raw) ? raw : [raw];
+  }
+  /** A wire hit's shape, distinguishing a bare hits-answer from a batch of answers. */
+  isHitShaped(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x) && typeof x.id === "string";
+  }
+  /** Decode one statement's `/query` answer: hits (bare or `{hits, plan}`), or an aggregation. */
+  decodeQueryAnswer(raw) {
+    if (Array.isArray(raw)) {
+      return raw.map((h) => this.decodeHit(h));
+    }
+    const obj = raw;
+    if ("count" in obj) {
+      return {
+        count: obj.count,
+        sums: decodeAttrs(obj.sums),
+        ...obj.groups ? {
+          groups: obj.groups.map((g) => ({
+            value: g.value === null ? null : decodeValue(g.value),
+            count: g.count,
+            sums: decodeAttrs(g.sums)
+          }))
+        } : {},
+        ...obj.groups_truncated ? { groupsTruncated: true } : {}
+      };
+    }
+    return {
+      hits: obj.hits.map((h) => this.decodeHit(h)),
+      plan: decodeQueryPlan(obj.plan)
+    };
+  }
   /**
    * Answer several vector queries in one round-trip (16 max). Returns one ranking per
    * query in request order, or — with `opts.fuse` — a single array holding the one fused