@deepagents/text2sql 7.0.2 → 7.1.1

package/dist/bin/sql.js

@@ -3,6 +3,12 @@
 // packages/text2sql/src/bin/sql.ts
 import { cac } from "cac";
 
+// packages/text2sql/src/lib/index-cache.ts
+import {
+  isFragment,
+  isFragmentData
+} from "@deepagents/context";
+
 // packages/text2sql/src/lib/file-cache.ts
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -29,8 +35,14 @@ var FileCache = class {
   }
 };
 var JsonCache = class extends FileCache {
-  constructor(watermark, baseDir) {
+  #isValid;
+  /**
+   * @param isValid - Checks that a parsed cache file holds a T; a file that
+   * fails it is read as a miss.
+   */
+  constructor(watermark, isValid, baseDir) {
     super(watermark, ".json", baseDir);
+    this.#isValid = isValid;
   }
   async read() {
     const content = await this.get();
@@ -38,7 +50,8 @@ var JsonCache = class extends FileCache {
       return null;
     }
     try {
-      return JSON.parse(content);
+      const value = JSON.parse(content);
+      return this.#isValid(value) ? value : null;
     } catch {
       return null;
     }
@@ -64,57 +77,12 @@ var FileIndexCache = class {
   }
   #cacheFor(key) {
     const watermark = this.#namespace ? `${this.#namespace}-${key}` : key;
-    return new JsonCache(watermark, this.#dir);
+    return new JsonCache(watermark, isFragmentList, this.#dir);
   }
 };
-
-// packages/text2sql/src/lib/index-lock.ts
-import { createHash as createHash2 } from "node:crypto";
-import { mkdir as mkdir2 } from "node:fs/promises";
-import { tmpdir as tmpdir2 } from "node:os";
-import * as path2 from "node:path";
-import { lock as acquireLock } from "proper-lockfile";
-var DEFAULT_STALE_MS = 3e4;
-var DEFAULT_RETRIES = {
-  retries: 10,
-  factor: 2,
-  minTimeout: 100,
-  maxTimeout: 2e3
-};
-var FileIndexLock = class {
-  #dir;
-  #namespace;
-  #stale;
-  #retries;
-  constructor(options = {}) {
-    this.#dir = options.dir ?? tmpdir2();
-    this.#namespace = options.namespace;
-    this.#stale = options.stale ?? DEFAULT_STALE_MS;
-    this.#retries = options.retries ?? DEFAULT_RETRIES;
-  }
-  async run(key, fn) {
-    await mkdir2(this.#dir, { recursive: true });
-    const release = await acquireLock(this.#lockPathFor(key), {
-      realpath: false,
-      stale: this.#stale,
-      retries: this.#retries
-    });
-    try {
-      return await fn();
-    } finally {
-      await release().catch(() => {
-      });
-    }
-  }
-  #lockPathFor(key) {
-    const watermark = this.#namespace ? `${this.#namespace}-${key}` : key;
-    const hash = createHash2("md5").update(watermark).digest("hex");
-    return path2.join(this.#dir, `text2sql-lock-${hash}`);
-  }
-};
-
-// packages/text2sql/src/lib/sql.ts
-import "@deepagents/agent";
+function isFragmentList(value) {
+  return Array.isArray(value) && value.every((item) => isFragment(item) && isFragmentData(item));
+}
 
 // packages/text2sql/src/lib/adapter-index.ts
 import { fragment } from "@deepagents/context";
@@ -141,6 +109,7 @@ function validateAdapterNames(names) {
 
 // packages/text2sql/src/lib/adapters/adapter.ts
 import { format as formatSql } from "sql-formatter";
+import { z } from "zod";
 
 // packages/text2sql/src/lib/agents/exceptions.ts
 var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
@@ -238,7 +207,6 @@ function databaseNameFragment(name) {
 var AdapterIndexer = class {
   #adapters;
   #cache;
-  #lock;
   constructor(options) {
     const adapterNames = Object.keys(options.adapters);
     if (adapterNames.length === 0) {
@@ -247,7 +215,6 @@ var AdapterIndexer = class {
     validateAdapterNames(adapterNames);
     this.#adapters = options.adapters;
     this.#cache = options.cache;
-    this.#lock = options.lock;
   }
   async index(options = {}) {
     const progress = timestampProgressHandler(options.onProgress);
@@ -305,41 +272,15 @@ var AdapterIndexer = class {
       message: `Indexing adapter "${name}"...`
     });
     const cache = this.#cache;
-    const key = name;
-    const emitCacheHit = () => progress({
-      type: "adapter:cache-hit",
-      adapter: name,
-      message: `Using cached index for adapter "${name}".`,
-      cached: true
-    });
-    const emitCacheMiss = () => progress({
-      type: "adapter:cache-miss",
-      adapter: name,
-      message: `No cached index for adapter "${name}".`,
-      cached: false
-    });
-    const introspect = async () => {
-      const ctx = createGroundingContext({
-        onProgress: (event) => progress(adapterProgressEvent(name, event))
-      });
-      const fragments = await adapter.introspect(ctx);
-      await cache?.write(key, fragments);
-      return fragments;
-    };
-    let servedFromCache = false;
-    const populate = async () => {
-      const recheck = await cache?.read(key);
-      if (recheck) {
-        servedFromCache = true;
-        return recheck;
-      }
-      if (cache) emitCacheMiss();
-      return introspect();
-    };
     try {
-      const cached = await cache?.read(key);
+      const cached = await cache?.read(name);
       if (cached) {
-        emitCacheHit();
+        progress({
+          type: "adapter:cache-hit",
+          adapter: name,
+          message: `Using cached index for adapter "${name}".`,
+          cached: true
+        });
         progress({
           type: "adapter:end",
           adapter: name,
@@ -348,13 +289,24 @@ var AdapterIndexer = class {
         });
         return cached;
       }
-      const fragments = await this.#lock.run(key, populate);
-      if (servedFromCache) emitCacheHit();
+      if (cache) {
+        progress({
+          type: "adapter:cache-miss",
+          adapter: name,
+          message: `No cached index for adapter "${name}".`,
+          cached: false
+        });
+      }
+      const ctx = createGroundingContext({
+        onProgress: (event) => progress(adapterProgressEvent(name, event))
+      });
+      const fragments = await adapter.introspect(ctx);
+      await cache?.write(name, fragments);
       progress({
         type: "adapter:end",
         adapter: name,
         message: `Finished indexing adapter "${name}".`,
-        cached: servedFromCache
+        cached: false
       });
       return fragments;
     } catch (error) {
@@ -399,456 +351,6 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-// packages/text2sql/src/lib/agents/sql.agent.ts
-import { groq } from "@ai-sdk/groq";
-import {
-  APICallError,
-  JSONParseError,
-  NoContentGeneratedError,
-  NoObjectGeneratedError,
-  NoOutputGeneratedError,
-  TypeValidationError,
-  defaultSettingsMiddleware,
-  wrapLanguageModel
-} from "ai";
-import dedent from "dedent";
-import pRetry from "p-retry";
-import z from "zod";
-import "@deepagents/agent";
-import {
-  ContextEngine,
-  InMemoryContextStore,
-  example,
-  fragment as fragment2,
-  guardrail,
-  hint,
-  persona,
-  policy,
-  structuredOutput,
-  user,
-  workflow
-} from "@deepagents/context";
-
-// packages/text2sql/src/lib/sql-scope-error.ts
-function buildScopeParseErrorPayload(sql, parserDialect, error) {
-  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
-  return {
-    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
-    error_type: "SQL_SCOPE_PARSE_ERROR",
-    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
-    sql_attempted: sql,
-    parser_dialect: parserDialect,
-    parser_error: parserError
-  };
-}
-
-// packages/text2sql/src/lib/agents/sql.agent.ts
-var RETRY_TEMPERATURES = [0, 0.2, 0.3];
-var SQL_AGENT_ROLE = "Expert SQL query generator.";
-var SQL_AGENT_OBJECTIVE = "Generate precise SQL grounded in provided schema.";
-var SQL_AGENT_POLICIES = [
-  fragment2(
-    "schema_mapping",
-    policy({
-      rule: "Translate natural language into precise SQL grounded in available schema entities."
-    }),
-    hint("Preserve schema spelling exactly, including typos in column names.")
-  ),
-  fragment2(
-    "projection_minimality",
-    policy({
-      rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
-    }),
-    policy({
-      rule: 'For requests of the form "X sorted/ordered by Y", project X only unless Y is explicitly requested as an output field.'
-    }),
-    policy({
-      rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
-    }),
-    hint(
-      "Do not include ORDER BY, GROUP BY, or JOIN helper columns in SELECT output unless the question explicitly asks for them."
-    ),
-    policy({
-      rule: "Use DISTINCT only when uniqueness is explicitly requested (for example distinct/unique/different/no duplicates)."
-    }),
-    hint(
-      'Do not infer DISTINCT from generic wording such as "some", plural nouns, or entity-set phrasing; for transactional/attendance-style tables, default to raw rows unless uniqueness is explicitly requested.'
-    )
-  ),
-  fragment2(
-    "date_transform_safety",
-    policy({
-      rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
-    }),
-    policy({
-      rule: "Use date-part extraction only when both conditions hold: the question explicitly asks for transformation and schema values require transformation to produce that unit."
-    }),
-    hint(
-      "Do not apply SUBSTR, STRFTIME, DATE_PART, YEAR, or similar extraction functions unless the question explicitly asks for transformation and schema values require it."
-    ),
-    hint(
-      "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
-    )
-  ),
-  fragment2(
-    "sql_minimality",
-    guardrail({
-      rule: "Never hallucinate tables or columns.",
-      reason: "Schema fidelity is required.",
-      action: "Use only available schema entities."
-    }),
-    guardrail({
-      rule: "Avoid unnecessary transformations and derived projections.",
-      reason: "Extra transformations frequently change semantics and reduce correctness.",
-      action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
-    })
-  ),
-  fragment2(
-    "preflight_checklist",
-    workflow({
-      task: "Final SQL preflight before returning output",
-      steps: [
-        "Verify selected columns match the question and remove unrequested helper projections.",
-        "If aggregate values are used only for ranking/filtering, keep them out of SELECT unless explicitly requested.",
-        "Prefer raw schema columns over derived expressions when raw columns already satisfy the request.",
-        "If a candidate query uses STRFTIME, SUBSTR, DATE_PART, YEAR, or similar extraction on text-like columns, remove that transformation unless explicitly required by the question.",
-        "Return only schema-grounded SQL using existing tables and columns."
-      ]
-    })
-  ),
-  fragment2(
-    "set_semantics",
-    policy({
-      rule: "For questions asking where both condition A and condition B hold over an attribute, compute the intersection of qualifying sets for that attribute."
-    }),
-    policy({
-      rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
-    }),
-    hint(
-      "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
-    ),
-    hint(
-      "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
-    ),
-    hint(
-      "Do not collapse cross-group conditions into a single-row AND predicate when the intent is shared values across groups."
-    ),
-    policy({
-      rule: "If two predicates on the same field cannot both be true for one row, do not combine them with AND; use set operations across separate filtered subsets when shared values are requested."
-    })
-  ),
-  fragment2(
-    "predicate_column_alignment",
-    policy({
-      rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
-    }),
-    hint(
-      "When a filter value is a descriptive label (for example a department name), join through the lookup table and filter on its name/title column, not on *_id columns."
-    ),
-    hint(
-      "When relation roles are explicit in wording (for example host/home/source/destination), prefer foreign keys with matching role qualifiers over generic similarly named columns."
-    ),
-    policy({
-      rule: "When multiple foreign-key candidates exist, select the column whose qualifier best matches the relationship described in the question."
-    }),
-    policy({
-      rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
-    }),
-    hint(
-      'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
-    ),
-    policy({
-      rule: "Do not compare descriptive labels or names to *_id columns; join to the table containing the descriptive field and filter there."
-    }),
-    policy({
-      rule: "Keep numeric identifiers unquoted when used as numeric equality filters unless schema indicates text identifiers."
-    }),
-    policy({
-      rule: "When filtering by a descriptive label value and a related table exposes a corresponding *_name or title column, join to that table and filter on the descriptive column."
-    })
-  ),
-  fragment2(
-    "ordering_semantics",
-    policy({
-      rule: "Respect explicit sort direction terms. If direction is not specified, use ascending order unless a superlative intent (most/least/highest/lowest) implies direction."
-    }),
-    policy({
-      rule: "When ranking categories by frequency, use COUNT for ordering but keep output focused on requested category fields unless counts are explicitly requested."
-    }),
-    policy({
-      rule: "Do not use DESC unless descending direction is explicit or a superlative intent requires descending ranking."
-    }),
-    policy({
-      rule: 'For "most common/frequent <attribute>" requests, return the attribute value(s) only; use counts only for ordering/filtering unless the question explicitly asks to return counts.'
-    }),
-    hint(
-      'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
-    )
-  ),
-  fragment2(
-    "negative_membership_queries",
-    policy({
-      rule: "For requests asking entities that did not participate/host/appear in related records, prefer NOT IN or NOT EXISTS against the related foreign-key set."
-    }),
-    hint(
-      "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
-    ),
-    hint(
-      'For "never had/never exceeded" conditions over history tables, exclude entities via NOT IN/NOT EXISTS against the disqualifying entity-id set (often built with GROUP BY/HAVING MAX(...)).'
-    )
-  ),
-  fragment2(
-    "join_completeness",
-    policy({
-      rule: "Preserve entity-restricting joins implied by the question. Do not widen results by querying only a broader attribute table when a subset entity table is available."
-    }),
-    policy({
-      rule: "If an entity term in the question maps to a table, keep that table in query scope and join to attribute tables rather than dropping the entity table."
-    }),
-    hint(
-      "If the question targets a specific entity group, include that entity table and its join conditions even when selected columns come from a related table."
-    ),
-    hint(
-      "When the question names an entity type and a relation table links to that entity via *_id, include the entity table in scope instead of counting only relation rows."
-    ),
-    hint(
-      "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
-    )
-  ),
-  fragment2(
-    "aggregation_exactness",
-    policy({
-      rule: "Preserve requested aggregation semantics exactly: use COUNT(*) by default for total rows, use COUNT(DISTINCT ...) only when uniqueness is explicitly requested, and group by stable entity keys when computing per-entity aggregates."
-    }),
-    policy({
-      rule: "For questions asking which entity has lowest/highest average of a metric, compute AVG(metric) per entity (GROUP BY entity) and rank those aggregates."
-    }),
-    hint(
-      'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
-    )
-  ),
-  fragment2(
-    "query_shape_examples",
-    example({
-      question: "List categories ordered by how many records belong to each category.",
-      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*)"
-    }),
-    example({
-      question: "Show labels shared by rows with metric > 100 and rows with metric < 10.",
-      answer: "SELECT label FROM records WHERE metric > 100 INTERSECT SELECT label FROM records WHERE metric < 10"
-    }),
-    example({
-      question: "List locations that have not hosted any event.",
-      answer: "SELECT location_name FROM locations WHERE location_id NOT IN (SELECT host_location_id FROM events)"
-    }),
-    example({
-      question: "List the most common category across records.",
-      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*) DESC LIMIT 1"
-    })
-  )
-];
-function extractSql(output) {
-  const match = output.match(/```sql\n?([\s\S]*?)```/);
-  return match ? match[1].trim() : output.trim();
-}
-async function toSql(options) {
-  const { maxRetries = 3 } = options;
-  return withRetry(
-    async (attemptNumber, errors, attempts) => {
-      const context = new ContextEngine({
-        store: new InMemoryContextStore(),
-        chatId: `sql-gen-${crypto.randomUUID()}`,
-        userId: "system"
-      });
-      context.set(
-        persona({
-          name: "Freya",
-          role: SQL_AGENT_ROLE,
-          objective: SQL_AGENT_OBJECTIVE
-          // role: `You are a data science expert that provides well-reasoned and detailed responses.`,
-          // objective: `Your task is to understand the schema and generate a valid SQL query to answer the question. You first think about the reasoning process as an internal monologue and then provide the user with the answer.`,
-        }),
-        ...SQL_AGENT_POLICIES,
-        ...options.fragments
-      );
-      if (errors.length) {
-        const lastError = errors.at(-1);
-        context.set(
-          user(dedent`
-            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
-Given the question, the evidence and the database schema, return the SQL script that addresses the question.
-
-Question: ${options.input}
-`),
-          UnanswerableSQLError.isInstance(lastError) ? user(
-            `<retry_instruction>Your previous response marked the task as unanswerable. Re-evaluate using best-effort schema mapping. If the core intent is answerable with existing tables/columns, return SQL. Return error only when required core intent cannot be mapped without inventing schema elements.</retry_instruction>`
-          ) : user(
-            `<validation_error>Your previous SQL query had the following error: ${lastError?.message}. Please fix the query.</validation_error>`
-          )
-        );
-      } else {
-        context.set(
-          user(dedent`
-            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
-Given the question, the evidence and the database schema, return the SQL script that addresses the question.
-
-Question: ${options.input}
-`)
-        );
-      }
-      const temperature = RETRY_TEMPERATURES[attemptNumber - 1] ?? RETRY_TEMPERATURES[RETRY_TEMPERATURES.length - 1];
-      const baseModel = options.model ?? groq("openai/gpt-oss-20b");
-      const model = wrapLanguageModel({
-        model: baseModel,
-        middleware: defaultSettingsMiddleware({ settings: { temperature } })
-      });
-      const sqlOutput = structuredOutput({
-        model,
-        context,
-        schema: z.object({
-          result: z.union([
-            z.object({
-              sql: z.string().describe("The SQL query that answers the question"),
-              reasoning: z.string().describe("The reasoning steps taken to generate the SQL")
-            }),
-            z.object({
-              error: z.string().describe(
-                "Error message explaining why the question cannot be answered with the given schema"
-              )
-            })
-          ])
-        })
-      });
-      const { result: output } = await sqlOutput.generate();
-      const finalizeSql = async (rawSql) => {
-        const extractedSql = extractSql(rawSql);
-        const errorsOrUndefined = errors.length ? errors.map(formatErrorMessage) : void 0;
-        if (extractedSql === "") {
-          return {
-            attempts,
-            sql: "",
-            errors: errorsOrUndefined
-          };
-        }
-        const sql = options.adapter.format(extractedSql);
-        if (rawSql.trimStart().startsWith("```") && extractedSql === rawSql.trim()) {
-          throw new SQLValidationError(
-            JSON.stringify(
-              buildScopeParseErrorPayload(
-                sql,
-                options.adapter.formatterLanguage,
-                new Error(
-                  "SQL response was fenced markdown, not executable SQL."
-                )
-              )
-            )
-          );
-        }
-        const validationError = await options.adapter.validate(sql);
-        if (validationError) {
-          throw new SQLValidationError(validationError);
-        }
-        return {
-          attempts,
-          sql,
-          errors: errorsOrUndefined
-        };
-      };
-      if ("error" in output) {
-        context.set(
-          user(
-            "<best_effort_fallback>Do not return unanswerable. Produce the best valid SQL query that answers the core intent using only available schema entities.</best_effort_fallback>"
-          )
-        );
-        const forcedSqlOutput = structuredOutput({
-          model,
-          context,
-          schema: z.object({
-            sql: z.string().describe(
-              "Best-effort SQL query that answers the core intent using only available schema entities."
-            ),
-            reasoning: z.string().describe("Reasoning steps for best-effort schema mapping.")
-          })
-        });
-        try {
-          const forced = await forcedSqlOutput.generate();
-          return await finalizeSql(forced.sql);
-        } catch (error) {
-          if (SQLValidationError.isInstance(error) || APICallError.isInstance(error) || JSONParseError.isInstance(error) || TypeValidationError.isInstance(error) || NoObjectGeneratedError.isInstance(error) || NoOutputGeneratedError.isInstance(error) || NoContentGeneratedError.isInstance(error)) {
-            throw error;
-          }
-          throw new UnanswerableSQLError(output.error);
-        }
-      }
-      return await finalizeSql(output.sql);
-    },
-    { retries: maxRetries - 1 }
-  );
-}
-function formatErrorMessage(error) {
-  if (APICallError.isInstance(error)) {
-    if (error.message.startsWith("Failed to validate JSON")) {
-      return `Schema validation failed: ${error.message}`;
-    }
-    return error.message;
-  }
-  if (SQLValidationError.isInstance(error)) {
-    return `SQL Validation Error: ${error.message}`;
-  }
-  return error.message;
-}
-function isModelUnavailableError(error) {
-  if (!APICallError.isInstance(error)) {
-    return false;
-  }
-  const message = error.message.toLowerCase();
-  const responseBody = (error.responseBody ?? "").toLowerCase();
-  const is404ModelError = error.statusCode === 404 && (message.includes("model") || responseBody.includes("model_not_found"));
-  const errorCode = typeof error.data === "object" && error.data !== null && "error" in error.data && typeof error.data.error === "object" && error.data.error !== null && "code" in error.data.error && typeof error.data.error.code === "string" ? error.data.error.code.toLowerCase() : void 0;
-  return is404ModelError || errorCode === "model_not_found" || responseBody.includes('"code":"model_not_found"') || message.includes("model") && message.includes("does not exist or you do not have access to it");
-}
-async function withRetry(computation, options = { retries: 3 }) {
-  const errors = [];
-  let attempts = 0;
-  return pRetry(
-    (attemptNumber) => {
-      return computation(attemptNumber, errors, ++attempts);
-    },
-    {
-      retries: options.retries,
-      shouldRetry: (context) => {
-        if (UnanswerableSQLError.isInstance(context.error)) {
-          return false;
-        }
-        if (isModelUnavailableError(context.error)) {
-          return false;
-        }
-        if (SQLValidationError.isInstance(context.error)) {
-          return true;
-        }
-        console.log({
-          NoObjectGeneratedError: NoObjectGeneratedError.isInstance(
-            context.error
-          ),
-          NoOutputGeneratedError: NoOutputGeneratedError.isInstance(
-            context.error
-          ),
-          APICallError: APICallError.isInstance(context.error),
-          JSONParseError: JSONParseError.isInstance(context.error),
-          TypeValidationError: TypeValidationError.isInstance(context.error),
-          NoContentGeneratedError: NoContentGeneratedError.isInstance(
-            context.error
-          )
-        });
-        return APICallError.isInstance(context.error) || JSONParseError.isInstance(context.error) || TypeValidationError.isInstance(context.error) || NoObjectGeneratedError.isInstance(context.error) || NoOutputGeneratedError.isInstance(context.error) || NoContentGeneratedError.isInstance(context.error);
-      },
-      onFailedAttempt(context) {
-        errors.push(context.error);
-      }
-    }
-  );
-}
-
 // packages/text2sql/src/lib/sql.ts
 var text2SqlValidationMarker = /* @__PURE__ */ Symbol("Text2SqlValidationError");
 var text2SqlUnknownAdapterMarker = /* @__PURE__ */ Symbol("Text2SqlUnknownAdapterError");
@@ -910,8 +412,7 @@ var Text2Sql = class {
     this.#config = config;
     this.#indexer = new AdapterIndexer({
       adapters: config.adapters,
-      cache: config.cache,
-      lock: config.lock
+      cache: config.cache
     });
   }
   #requireAdapter(name) {
@@ -921,13 +422,6 @@ var Text2Sql = class {
     }
     return adapter;
   }
-  #requireModel(op) {
-    const model = this.#config.model;
-    if (!model) {
-      throw new Error(`Text2Sql.${op}() requires a model in Text2SqlConfig`);
-    }
-    return model;
-  }
   adapterNames() {
     return Object.keys(this.#config.adapters);
   }
@@ -969,8 +463,10 @@ var Text2Sql = class {
     if (!Array.isArray(result)) {
       throw new Error("adapter.execute must return an array of rows");
     }
-    const columns = result.length > 0 ? Object.keys(result[0]) : [];
-    return { rows: result, columns };
+    const rows = result;
+    const [first] = rows;
+    const columns = typeof first === "object" && first !== null ? Object.keys(first) : [];
+    return { rows, columns };
   }
   async #validateWith(adapter, sql) {
     const formatted = adapter.format(sql);
@@ -984,18 +480,6 @@ var Text2Sql = class {
       onProgress: options.onProgress
     });
   }
-  async toSql(input, adapterName) {
-    const adapter = this.#requireAdapter(adapterName);
-    const model = this.#requireModel("toSql");
-    const fragments = await this.#indexer.indexAdapter(adapterName);
-    const result = await toSql({
-      input,
-      adapter,
-      fragments,
-      model
-    });
-    return result.sql;
-  }
   async toPairs(adapterName, factory) {
     const adapter = this.#requireAdapter(adapterName);
     const producer = factory(adapter);
@@ -1004,14 +488,18 @@ var Text2Sql = class {
 };
 
 // packages/text2sql/src/bin/command.ts
-import * as path3 from "node:path";
+import * as path2 from "node:path";
+import z2 from "zod";
+var cliWord = z2.union([z2.string(), z2.number()]).transform(String);
+var cliOptions = z2.record(z2.string(), z2.unknown());
+var queryArgs = z2.tuple([cliWord, z2.array(cliWord)]);
 var OUT_DIR_OPTION = {
   flag: "--out-dir <path>",
   description: "Output directory (default: $TEXT2SQL_OUT_DIR or ./sql)"
 };
 function resolveOutputDir(ctx, options) {
   const explicit = typeof options.outDir === "string" ? options.outDir : void 0;
-  return path3.resolve(ctx.cwd, explicit ?? ctx.env.TEXT2SQL_OUT_DIR ?? "./sql");
+  return path2.resolve(ctx.cwd, explicit ?? ctx.env.TEXT2SQL_OUT_DIR ?? "./sql");
 }
 var CommandError = class extends Error {
   command;
@@ -1047,9 +535,9 @@ var SqlCommand = class {
 var SqlQueryCommand = class extends SqlCommand {
   args = "<db> <...sql>";
   async execute(ctx, args, options) {
-    const [db, sqlParts] = args;
+    const [db, sqlParts] = queryArgs.parse(args);
     const name = this.resolveAdapterName(ctx.text2Sql, db);
-    const sql = (sqlParts ?? []).join(" ").trim();
+    const sql = sqlParts.join(" ").trim();
     if (!sql) this.fail("no query provided");
     try {
       return await this.runQuery(ctx, name, sql, options);
@@ -1064,14 +552,15 @@ var SqlQueryCommand = class extends SqlCommand {
 // packages/text2sql/src/bin/commands/index.ts
 import { constants, createWriteStream } from "node:fs";
 import {
-  mkdir as mkdir3,
+  mkdir as mkdir2,
   open,
   stat,
   writeFile as writeFile2
 } from "node:fs/promises";
-import * as path4 from "node:path";
+import * as path3 from "node:path";
 import { finished } from "node:stream/promises";
 import { v7 } from "uuid";
+import z3 from "zod";
 
 // packages/text2sql/src/bin/commands/indexing-formatter.ts
 var REDUNDANT_MESSAGE_TYPES = /* @__PURE__ */ new Set([
@@ -1092,6 +581,7 @@ function formatPretty(event) {
 }
 
 // packages/text2sql/src/bin/commands/index.ts
+var indexArgs = z3.tuple([z3.array(cliWord)]);
 var IndexCommand = class extends SqlCommand {
   name = "index";
   description = "Index adapter schemas and write context artifacts";
@@ -1107,19 +597,19 @@ var IndexCommand = class extends SqlCommand {
     OUT_DIR_OPTION
   ];
   async execute(ctx, args, options) {
-    const adapterNames = args[0] ?? [];
+    const [adapterNames] = indexArgs.parse(args);
     const requested = options.all ? [] : adapterNames;
     const names = this.resolveNames(ctx.text2Sql, requested);
     const verbose = this.resolveVerbose(options.verbose);
     const outputDir = resolveOutputDir(ctx, options);
     const id = v7();
-    const fragmentsPath = path4.join(outputDir, `index-${id}.json`);
+    const fragmentsPath = path3.join(outputDir, `index-${id}.json`);
     const explicitEventsPath = resolveExplicitEventsPath(ctx);
-    const eventsPath = explicitEventsPath ?? path4.join(outputDir, `index-${id}.events.ndjson`);
+    const eventsPath = explicitEventsPath ?? path3.join(outputDir, `index-${id}.events.ndjson`);
     try {
-      await mkdir3(outputDir, { recursive: true });
+      await mkdir2(outputDir, { recursive: true });
       if (explicitEventsPath) {
-        await mkdir3(path4.dirname(explicitEventsPath), { recursive: true });
+        await mkdir2(path3.dirname(explicitEventsPath), { recursive: true });
       }
       const eventsStream = await openEventsWriter(
         eventsPath,
@@ -1179,7 +669,7 @@ function createProgressHandler(eventsStream, verbose, stderr) {
 }
 function resolveExplicitEventsPath(ctx) {
   const explicit = ctx.env.TEXT2SQL_INDEX_EVENTS_PATH?.trim();
-  return explicit ? path4.resolve(ctx.cwd, explicit) : null;
+  return explicit ? path3.resolve(ctx.cwd, explicit) : null;
 }
 async function openEventsWriter(eventsPath, explicitEventsPath, stderr) {
   const probe = explicitEventsPath ? await probeFifoWriter(explicitEventsPath, stderr) : null;
@@ -1203,14 +693,14 @@ async function probeFifoWriter(eventsPath, stderr) {
   try {
     stats = await stat(eventsPath);
   } catch (err) {
-    if (err.code === "ENOENT") return null;
+    if (hasErrorCode(err, "ENOENT")) return null;
     throw err;
   }
   if (!stats.isFIFO()) return null;
   try {
     return await open(eventsPath, constants.O_WRONLY | constants.O_NONBLOCK);
   } catch (err) {
-    if (err.code === "ENXIO") {
+    if (hasErrorCode(err, "ENXIO")) {
       stderr.write(`sql index: waiting for reader on FIFO ${eventsPath}...
 `);
       return null;
@@ -1218,6 +708,9 @@ async function probeFifoWriter(eventsPath, stderr) {
     throw err;
   }
 }
+function hasErrorCode(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
 function waitForOpen(stream) {
   return new Promise((resolve4, reject) => {
     if (!stream.pending) {
@@ -1241,8 +734,8 @@ function dedupe(values) {
 }
 
 // packages/text2sql/src/bin/commands/run.ts
-import { mkdir as mkdir4, writeFile as writeFile3 } from "node:fs/promises";
-import * as path5 from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import * as path4 from "node:path";
 import { v7 as v72 } from "uuid";
 var RunCommand = class extends SqlQueryCommand {
   name = "run";
@@ -1253,9 +746,9 @@ var RunCommand = class extends SqlQueryCommand {
   async runQuery(ctx, name, sql, options) {
     const outputDir = resolveOutputDir(ctx, options);
     const { rows, columns } = await ctx.text2Sql.run(name, sql);
-    const outPath = path5.join(outputDir, `${v72()}.json`);
+    const outPath = path4.join(outputDir, `${v72()}.json`);
     try {
-      await mkdir4(outputDir, { recursive: true });
+      await mkdir3(outputDir, { recursive: true });
       await writeFile3(outPath, JSON.stringify(rows, null, 2));
     } catch (error) {
       this.fail(errorMessage2(error));
@@ -1301,15 +794,12 @@ async function loadAdapters() {
     );
   }
   const specifier = target.startsWith(".") || target.startsWith("/") ? pathToFileURL(resolve3(target)).href : target;
-  let mod;
-  try {
-    mod = await import(specifier);
-  } catch (cause) {
+  const mod = await import(specifier).catch((cause) => {
     throw new Error(
       `TEXT2SQL_ADAPTERS=${target}: failed to import module - ${errorMessage2(cause)}`
     );
-  }
-  const exported = mod.default;
+  });
+  const exported = typeof mod === "object" && mod !== null && "default" in mod ? mod.default : void 0;
   if (!exported || typeof exported !== "object" || Array.isArray(exported)) {
     throw new Error(
       `TEXT2SQL_ADAPTERS=${target}: default export must be a Record<string, Adapter> (got ${describe(exported)}).`
@@ -1321,24 +811,24 @@ async function loadAdapters() {
       `TEXT2SQL_ADAPTERS=${target}: default export is an empty object - declare at least one adapter.`
     );
   }
+  const adapters = {};
   for (const [name, value] of entries) {
     if (!isAdapterShape(value)) {
       throw new Error(
         `TEXT2SQL_ADAPTERS=${target}: adapter "${name}" is missing one of the required methods (format, validate, execute).`
       );
     }
+    adapters[name] = value;
   }
   try {
     validateAdapterNames(entries.map(([name]) => name));
   } catch (cause) {
     throw new Error(`TEXT2SQL_ADAPTERS=${target}: ${errorMessage2(cause)}`);
   }
-  return exported;
+  return adapters;
 }
 function isAdapterShape(value) {
-  if (!value || typeof value !== "object") return false;
-  const v = value;
-  return typeof v.format === "function" && typeof v.validate === "function" && typeof v.execute === "function";
+  return typeof value === "object" && value !== null && "format" in value && typeof value.format === "function" && "validate" in value && typeof value.validate === "function" && "execute" in value && typeof value.execute === "function";
 }
 function describe(value) {
   if (value === null) return "null";
@@ -1387,7 +877,7 @@ function registerCommand(cli2, command) {
     cliCommand.option(option.flag, option.description);
   }
   cliCommand.action(async (...callArgs) => {
-    const options = callArgs[callArgs.length - 1] ?? {};
+    const options = cliOptions.parse(callArgs.at(-1));
     const positional = callArgs.slice(0, -1);
     return runCommand(command, positional, options);
   });
@@ -1400,19 +890,12 @@ function resolveIndexCache() {
   }
   return new FileIndexCache({ dir, namespace });
 }
-function resolveIndexLock() {
-  return new FileIndexLock({
-    dir: process.env.TEXT2SQL_INDEX_LOCK_DIR ?? process.env.TEXT2SQL_INDEX_CACHE_DIR,
-    namespace: process.env.TEXT2SQL_INDEX_VERSION
-  });
-}
 async function runCommand(command, positional, options) {
   let ctx;
   try {
     const text2Sql = new Text2Sql({
       adapters: await loadAdapters(),
-      cache: resolveIndexCache(),
-      lock: resolveIndexLock()
+      cache: resolveIndexCache()
     });
     ctx = {
       text2Sql,