@askdb/core 1.0.0-beta.42 → 1.0.0-beta.44

package/README.md

@@ -2,28 +2,34 @@
 
 Dialect-agnostic NL→SQL pipeline for AskDB. Provides `ask()` orchestration, schema/IR types, modes, logging, and retrieval input. Bring your own dialect adapter (e.g. `@askdb/postgres`) and your own model.
 
-> **Status:** pre-1.0. `0.3.0` moved the Postgres dialect and `@askdb/core/postgres` to `@askdb/postgres`. Runtime AI provider construction lives in `@askdb/ai`; core remains BYO-model and does not read `process.env`. See [`docs/adrs/0002-integration-package-layout.md`](../../docs/adrs/0002-integration-package-layout.md), [`docs/adrs/0005-askdb-config-and-env-bootstrap.md`](../../docs/adrs/0005-askdb-config-and-env-bootstrap.md), and [`docs/adrs/0006-ai-provider-integration-strategy.md`](../../docs/adrs/0006-ai-provider-integration-strategy.md).
+> **Status:** pre-release beta (`1.0.0-beta.x`); public APIs may still change before 1.0. `0.3.0` moved the Postgres dialect and `@askdb/core/postgres` to `@askdb/postgres`. Runtime AI provider construction lives in `@askdb/ai`; core remains BYO-model and does not read `process.env`. See [`docs/adrs/0002-integration-package-layout.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0002-integration-package-layout.md), [`docs/adrs/0005-askdb-config-and-env-bootstrap.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0005-askdb-config-and-env-bootstrap.md), and [`docs/adrs/0006-ai-provider-integration-strategy.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0006-ai-provider-integration-strategy.md).
+
+> **Security model:** `ask()` returns SQL and never executes it. Its SQL checks (single `SELECT`/`WITH` statement (with a SQL Server caveat), no comments, no write/DDL keywords, no known side-effecting functions, and the tenant and sensitive-column checks) are heuristic defense in depth that catch common model mistakes. The read-only and sensitive-column checks use a dialect-aware lexer; the tenant check uses a simpler scanner of its own ([#342](https://github.com/Ygilany/AskDB/issues/342)). They are not a SQL parser and not a security boundary. Run generated SQL under a read-only, least-privilege database role and enforce tenant isolation in the database. See [Safety boundaries](https://askdb.tools/concepts/safety-boundaries/).
 
 ## Install
 
 ```bash
-pnpm add @askdb/core
+# `ai` (Vercel AI SDK) is a required peer dependency — your app owns its version
+pnpm add @askdb/core ai
 # Plus a dialect adapter for the engine you target:
 pnpm add @askdb/postgres
-# Plus a model provider, for example:
+# Plus a model — either construct one directly with an AI SDK provider:
 pnpm add @ai-sdk/openai
-# Optional AskDB config/env model factory:
+# Optional AskDB config/env model factory (uses the @ai-sdk/* package above):
 pnpm add @askdb/ai
-pnpm add @askdb/ai-openai
 ```
 
+`ai` is a **peer dependency** (`^6.0.0 || ^7.0.51`: AI SDK 6, or 7.0.51 and later), not a bundled dependency: `ask()` receives a `LanguageModel` your app constructs, so core must use the same `ai` instance your app does. Hosts on AI SDK 6 (e.g. `@ai-sdk/openai@3`) and AI SDK 7 (`@ai-sdk/openai@4`) are both supported. The config-driven path (`@askdb/ai` and `@askdb/client`) currently requires AI SDK 7.
+
+`ai` is a required peer, not an optional one, and core loads it at import time. So any package that depends on `@askdb/core` needs `ai` installed, even for introspection only. That covers `@askdb/client`, `@askdb/connectors`, `@askdb/introspect`, the engine packages, `@askdb/prisma`, `@askdb/enrich` and `@askdb/rag`. npm 7+ and pnpm install the missing peer for you. Yarn doesn't, so add `ai` yourself. ADR 0006 records why (2026-09 amendment).
+
 `@askdb/core` itself does not depend on `pg`. The optional `pg` peer lives on `@askdb/postgres` for live Postgres introspection.
 
-Runtime AI configuration helpers live in `@askdb/ai` and provider adapters such as `@askdb/ai-openai`. If you use [`@askdb/config`](../../packages/config/README.md), call `bootstrapAskDbEnv()`, create an AI registry, then pass **`getAskDbRuntimeConfig().ai.aiEnv`** to `registry.createLanguageModelFromEnv(...)`.
+Runtime AI configuration helpers live in `@askdb/ai`, which has built-in providers for OpenAI, Azure/Foundry, Google, Anthropic, and the Vercel AI Gateway (install the matching `@ai-sdk/*` package). If you use [`@askdb/config`](https://github.com/Ygilany/AskDB/blob/main/packages/config/README.md), call `bootstrapAskDbEnv()`, create an AI registry, then pass **`getAskDbRuntimeConfig().ai.aiEnv`** to `registry.createLanguageModelFromEnv(...)`.
 
 ## Schema format
 
-`@askdb/core` uses **Schema v2** — a split artifact designed for business-context enrichment and RAG chunking. See [`docs/contracts/schema-v2.md`](../../docs/contracts/schema-v2.md) for the full contract.
+`@askdb/core` uses **Schema v2** — a split artifact designed for business-context enrichment and RAG chunking. See [`docs/contracts/schema-v2.md`](https://github.com/Ygilany/AskDB/blob/main/docs/contracts/schema-v2.md) for the full contract.
 
 ### Directory layout
 
@@ -100,7 +106,7 @@ Key rules:
 
 ## What you get
 
-- `ask({ question, schema, model, dialect })` — generate validated SQL (plus optional `unboundSql` / `params` / `parameters` / `preparedQuery`).
+- `ask({ question, schema, model, dialect })` — generate checked SQL (plus optional `unboundSql` / `params` / `parameters` / `preparedQuery`).
 - `bindPreparedQuery(prepared, values)` — pure local rebind of a `PreparedQuery` (no model call).
 - `AskDbLanguageModel` — AskDB's public name for the AI SDK language model contract.
 - `AskDialect` — the dialect adapter contract. `@askdb/postgres` exports a ready-made one.

package/dist/ask.d.ts

@@ -16,6 +16,8 @@ export type AskDialectGenerateOptions = {
     omitSensitiveIdentifiersFromNlToSqlPrompt?: boolean;
     generateText?: typeof defaultGenerateText;
     providerOptions?: Record<string, unknown>;
+    /** The caller's {@link AskPipelineOptions.abortSignal}. A custom dialect passes it to its model call. */
+    abortSignal?: AbortSignal;
     prebuiltDdl?: string;
     tenantPolicy?: import("./schema/v2/tenant-policy.js").NormalizedTenantPolicy;
     tenantScope?: TenantScope;
@@ -31,10 +33,16 @@ export type AskUsage = {
     completionTokens: number | null;
     totalTokens: number | null;
 };
-/** Output of a dialect's generator: validated SQL plus optional dialect-specific explain metadata. */
+/** Output of a dialect's generator: the generated SQL plus optional dialect-specific explain metadata. */
 export type AskDialectGenerateResult = {
     sql: string;
     explain?: unknown;
+    /**
+     * Optional tenant guardrail result from a custom generator. When the schema has a
+     * tenant policy, `ask()` merges its warnings into its own check of `sql` and
+     * `unboundNamedSql` (before tenant rendering); it can add failures but never replace
+     * or relax that check.
+     */
     tenantGuardrail?: import("./sql/tenant-guardrail.js").TenantGuardrailResult;
     usage?: AskUsage;
     unboundNamedSql?: string;
@@ -48,6 +56,19 @@ export type AskDialectGenerateResult = {
  * a {@link DialectSpec} to `ask({ dialect })` and let the centralized pipeline
  * handle prompt assembly + validation. Implement `AskDialect` only when those
  * defaults won't fit.
+ *
+ * Safety responsibilities:
+ *   - **Read-only validation is yours.** `ask()` does not run the SELECT-only
+ *     validator on SQL returned by a custom dialect (custom dialects may target
+ *     non-SELECT statements on purpose). If your generator should only emit
+ *     read-only SQL, call the exported `validateSelectSql(spec, sql)` yourself
+ *     before returning.
+ *   - **Tenant enforcement is not yours to skip.** When the schema has a tenant
+ *     policy, `ask()` runs the tenant guardrail on the returned `sql` (and
+ *     `unboundNamedSql`), with its `:tenant_<root>_ids` placeholders still in place,
+ *     then substitutes them, regardless of dialect; `strict` policies throw
+ *     `TenantGuardrailError`. A `tenantGuardrail` your
+ *     generator returns is merged into that result, never used in place of it.
  */
 export type AskDialect = {
     generate(question: string, schema: AnyNormalizedSchema, model: AskDbLanguageModel, options?: AskDialectGenerateOptions): Promise<AskDialectGenerateResult>;
@@ -71,6 +92,28 @@ export type AskGenerateDeps = {
      */
     providerOptions?: Record<string, unknown>;
 };
+/**
+ * A subtree's IDs grouped by tenant root: each key is a root table id from the
+ * tenant policy (`"table:public.clients"`), and its value holds IDs of that root's
+ * own `tenantIdColumn`, never IDs of another root.
+ *
+ * Root tables have separate ID spaces, so client `5` and agency `5` are different
+ * tenants. Keying the IDs by root lets `ask()` bind each root's IDs to that root's
+ * own `:tenant_<label>_ids` placeholder.
+ */
+export type TenantIdsByRoot = Readonly<Record<string, readonly string[]>>;
+/**
+ * Host callback that expands a `subtree` tenant scope. Given the tenant root id and
+ * the seed IDs, return the subtree's IDs grouped by root ({@link TenantIdsByRoot}):
+ *
+ * - under `tenantRoot`: the seeds and any same-table descendants (e.g. child
+ *   agencies through `agencies.parent_agency_id`);
+ * - under each descendant root the policy declares (`roots[].parent` or
+ *   `hierarchy[]`): that root's IDs in the subtree.
+ *
+ * Pass it to `ask()` as {@link AskPipelineOptions.resolveTenantDescendants}.
+ */
+export type ResolveTenantDescendants = (tenantRoot: string, seedIds: readonly string[]) => Promise<TenantIdsByRoot> | TenantIdsByRoot;
 export type AskPipelineOptions = {
     question: string;
     schema: AnyNormalizedSchema;
@@ -88,6 +131,13 @@ export type AskPipelineOptions = {
      */
     omitSensitiveIdentifiersFromNlToSqlPrompt?: boolean;
     deps?: AskGenerateDeps;
+    /**
+     * Cancels the NL→SQL model call (`generateText({ abortSignal })`), e.g.
+     * `AbortSignal.timeout(60_000)` for a per-request timeout. With a built-in dialect an
+     * aborted call rejects with `SqlGenerationError` (the abort reason is its `cause`). A
+     * custom {@link AskDialect} receives it in its `generate()` options and maps its own errors.
+     */
+    abortSignal?: AbortSignal;
     /** Optional structured logger (host-provided — e.g. `createAskDbLogger` wraps Pino). */
     logger?: AskDbLogger;
     /**
@@ -130,9 +180,30 @@ export type AskPipelineOptions = {
     tenantScope?: TenantScope;
     /**
      * SQL output mode for tenant placeholders. Default `"sql-only"` inlines
-     * literal values; `"sql-params"` converts to positional `$N` parameters.
+     * escaped literal values. `"sql-params"` replaces them with the dialect's
+     * driver markers (`$N` for Postgres/CockroachDB and custom `AskDialect`s, `?`
+     * for MySQL/MariaDB/SQLite, `@pN` for SQL Server): run `sql` with
+     * `tenantParams`, or `unboundSql` with `params`.
      */
     tenantSqlMode?: TenantSqlOutputMode;
+    /**
+     * Expands a `subtree` tenant scope into IDs per tenant root.
+     *
+     * Called with the tenant root id and the seed IDs from
+     * `tenantScope.access.rootIds`; returns the subtree's IDs keyed by root table id
+     * ({@link TenantIdsByRoot}). `ask()` unions the seeds into the `tenantRoot` entry
+     * and turns the result into a `multi_root` scope (an `ids` scope when only
+     * `tenantRoot` has IDs), so each root's IDs bind only to that root's placeholder.
+     * The host is the right place for this: it already knows its own hierarchy, can
+     * cache the closure, and can apply its own authorization rules.
+     *
+     * Required when `tenantScope.access.kind === "subtree"` — AskDB never opens a
+     * database connection of its own. Without it, or when it returns a flat array,
+     * a key that isn't a root in the subtree, a value that isn't an array of
+     * non-empty strings, or no IDs at all, `ask()` throws `TenantScopeError`
+     * (`SUBTREE_NOT_RESOLVABLE`) before calling the model.
+     */
+    resolveTenantDescendants?: ResolveTenantDescendants;
     /**
      * Ask the model to also return the SQL in unbound form plus a JSON manifest
      * of the values it parameterized, populating `unboundSql`, `params`,
@@ -152,10 +223,23 @@ export type AskPipelineOptions = {
     sensitiveGuardrailMode?: SensitiveGuardrailMode | "off";
 };
 export type AskPipelineResult = {
+    /**
+     * The model's bound SQL: business values inlined as literals. Tenant IDs are
+     * inlined literals (`tenantSqlMode: "sql-only"`) or driver markers numbered from
+     * the first slot (`"sql-params"`) — then execute it with `tenantParams`.
+     */
     sql: string;
-    /** Driver markers; executable with `params`. */
+    /**
+     * Driver markers for every value (business and, in `"sql-params"` mode, tenant).
+     * Execute with `params` — never with `tenantParams`.
+     */
     unboundSql?: string;
-    /** Positional values for drivers (array slots on Postgres/CockroachDB listBinding). */
+    /**
+     * Values for `unboundSql`, in driver-marker order (array slots on
+     * Postgres/CockroachDB listBinding). In `"sql-params"` mode this already
+     * includes the tenant values — for `?` dialects interleaved in source order,
+     * otherwise after the business values. Do not concatenate `tenantParams`.
+     */
     params?: QueryParamSlot[];
     /** Named bindings for form UIs (includes runtime values). */
     parameters?: QueryParameterBinding[];
@@ -167,7 +251,20 @@ export type AskPipelineResult = {
      * at least one `sensitive` table/column and `sensitiveGuardrailMode` is not `"off"`.
      */
     sensitiveGuardrail?: SensitiveGuardrailResult;
+    /**
+     * Tenant guardrail result for the model's SQL, checked before tenant rendering: the
+     * bound `sql` and its `sql-unbound` block, with the `:tenant_<root>_ids` placeholders
+     * still in place. `sql` and `unboundSql` differ from those only by the substituted
+     * tenant IDs or markers. Present whenever the schema has a tenant policy, for every
+     * dialect form. In `strict` mode a failure
+     * throws `TenantGuardrailError` instead, so a returned result is always `passed`
+     * under `strict`.
+     */
     tenantGuardrail?: import("./sql/tenant-guardrail.js").TenantGuardrailResult;
+    /**
+     * `"sql-params"` mode only: the tenant IDs for the markers in `sql`, in marker
+     * order. `sql` + `tenantParams` is an executable pair on its own.
+     */
     tenantParams?: unknown[];
     tenantBindings?: TenantBinding[];
     /** Token usage for the LLM generation call. Absent when the provider does not report usage. */

package/dist/ask.d.ts.map

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

package/dist/ask.js

@@ -1,13 +1,17 @@
 import { AskDbLogEvent } from "./logging/log-events.js";
 import { DEFAULT_ASKDB_MODE } from "./modes/types.js";
 import { synthesizeRetrievedDdl } from "./retrieval/synthesize-ddl.js";
+import { unqualifiedNamespaceFor } from "./sql/prompt.js";
+import { promptIdentifierQuoter } from "./sql/prompt-identifiers.js";
 import { getDialectSpec, isBuiltInDialectId, } from "./sql/dialect-spec.js";
-import { generateSelectSql } from "./sql/generate.js";
+import { generateSelectSqlWithoutTenantGuardrail } from "./sql/generate.js";
+import { enforceTenantGuardrails } from "./sql/tenant-guardrail.js";
 import { resolveTenantSql, } from "./sql/tenant-placeholders.js";
+import { subtreeRootIds } from "./sql/tenant-hierarchy.js";
 import { validateTenantScope } from "./sql/tenant-scope-validate.js";
 import { formatSensitiveReference, schemaHasSensitiveIdentifiers, validateSensitiveReferences, } from "./sql/sensitive-guardrail.js";
-import { SensitiveReferenceError } from "./errors.js";
-import { bindPreparedQuery, sqlStructurallyEqual, } from "./sql/bind.js";
+import { SensitiveReferenceError, TenantScopeError, UnknownDialectError, } from "./errors.js";
+import { bindPreparedQuery, markerStyleForDialect, scanPlaceholders, sqlStructurallyEqual, } from "./sql/bind.js";
 export async function ask(options) {
     const logger = options.logger;
     const mode = options.mode ?? DEFAULT_ASKDB_MODE;
@@ -22,15 +26,23 @@ export async function ask(options) {
             enforcement: tenantPolicy.enforcement,
         }, "tenant scope validated");
     }
+    // A `subtree` scope is expanded to IDs per root here, before generation, so the
+    // prompt, guardrail, and placeholder substitution all see the same per-root
+    // access — and a missing or malformed resolver fails before any model call is spent.
+    const tenantScope = tenantPolicy && options.tenantScope
+        ? await expandSubtreeScope(tenantPolicy, options.tenantScope, options.resolveTenantDescendants)
+        : options.tenantScope;
     const explainRequested = options.explain ?? false;
     const omitSensitive = options.omitSensitiveIdentifiersFromNlToSqlPrompt ?? false;
     const parameterize = options.parameterize !== false; // default true
+    const dialectSpec = resolveDialectSpec(options.dialect);
     const prebuiltDdl = await maybeRetrieveDdl({
         options,
         logger,
         omitSensitive,
+        unqualifiedNamespace: unqualifiedNamespaceFor(options.schema, dialectSpec?.unqualifiedNamespace),
+        quoteIdentifier: dialectSpec ? promptIdentifierQuoter(dialectSpec) : undefined,
     });
-    const dialectSpec = resolveDialectSpec(options.dialect);
     const dialect = resolveDialect(options.dialect);
     const generated = await dialect.generate(options.question, options.schema, options.model, {
         logger,
@@ -38,9 +50,10 @@ export async function ask(options) {
         omitSensitiveIdentifiersFromNlToSqlPrompt: omitSensitive || undefined,
         generateText: options.deps?.generateText,
         providerOptions: options.deps?.providerOptions,
+        abortSignal: options.abortSignal,
         prebuiltDdl,
         tenantPolicy,
-        tenantScope: options.tenantScope,
+        tenantScope,
         // Custom AskDialect implementations ignore this; built-in path uses it.
         parameterize: dialectSpec ? parameterize : undefined,
     });
@@ -49,8 +62,11 @@ export async function ask(options) {
     const result = { sql: generated.sql };
     if (generated.explain !== undefined)
         result.explain = generated.explain;
-    if (generated.tenantGuardrail !== undefined)
+    // With a tenant policy, `tenantGuardrail` is computed below, before tenant rendering;
+    // without one, pass through whatever a custom dialect reported.
+    if (!tenantPolicy && generated.tenantGuardrail !== undefined) {
         result.tenantGuardrail = generated.tenantGuardrail;
+    }
     if (generated.usage !== undefined)
         result.usage = generated.usage;
     // Parameterize extras: build PreparedQuery, consistency-check via bindPreparedQuery,
@@ -127,10 +143,21 @@ export async function ask(options) {
             }, "parameterize extras dropped");
         }
     }
-    if (tenantPolicy && options.tenantScope) {
+    if (tenantPolicy && tenantScope) {
+        // Tenant guardrail on the untrusted SQL, before rendering: the model's bound
+        // statement and its unbound block, with the `:tenant_<root>_ids` placeholders
+        // still in place. Rendering below only swaps each placeholder for literals or
+        // driver markers, so one check covers every tenantSqlMode, dialect and output
+        // form (#315). Runs for every dialect (built-in, DialectSpec, or custom
+        // AskDialect); the built-in generator skips its own check so this is the single
+        // report. `dialectSpec` is undefined for a custom AskDialect: the guardrail then
+        // requires the statement to pass under the standard-SQL, Postgres and MySQL readings.
+        result.tenantGuardrail = enforceTenantGuardrails([result.sql, generated.unboundNamedSql], tenantPolicy, tenantScope, logger, generated.tenantGuardrail, dialectSpec);
         const tenantMode = options.tenantSqlMode ?? "sql-only";
-        const paramStartIndex = tenantMode === "sql-params" && result.params ? businessParamCount + 1 : 1;
-        const resolved = resolveTenantSql(result.sql, tenantPolicy, options.tenantScope, tenantMode, paramStartIndex, dialectSpec);
+        // `sql` carries business values as inlined literals, so its only markers are
+        // tenant markers, numbered from the first slot: `sql` runs with `tenantParams`
+        // alone. `unboundSql` runs with the combined `params` (handled below).
+        const resolved = resolveTenantSql(result.sql, tenantPolicy, tenantScope, tenantMode, 1, dialectSpec);
         result.sql = resolved.sql;
         if (resolved.bindings.length > 0)
             result.tenantBindings = resolved.bindings;
@@ -139,36 +166,138 @@ export async function ask(options) {
         }
         if (result.preparedQuery && result.unboundSql) {
             if (tenantMode === "sql-only") {
-                const unboundWithTenant = resolveTenantSql(result.unboundSql, tenantPolicy, options.tenantScope, "sql-only", 1, dialectSpec);
+                const unboundWithTenant = resolveTenantSql(result.unboundSql, tenantPolicy, tenantScope, "sql-only", 1, dialectSpec);
                 result.unboundSql = unboundWithTenant.sql;
             }
-            else {
-                const unboundWithTenant = resolveTenantSql(result.unboundSql, tenantPolicy, options.tenantScope, "sql-params", paramStartIndex, dialectSpec);
-                if (unboundWithTenant.mode === "sql-params") {
-                    result.unboundSql = unboundWithTenant.sql;
-                    result.params = [
-                        ...(result.params ?? []),
-                        ...unboundWithTenant.params,
-                    ];
-                }
+            else if (!bindTenantIntoUnboundSql(result, {
+                namedSql: result.preparedQuery.namedSql,
+                businessParamCount,
+                tenantPolicy,
+                tenantScope,
+                dialectSpec,
+            })) {
+                dropParameterizeExtras(result);
+                logger?.debug?.({
+                    event: AskDbLogEvent.PipelineParameterized,
+                    parameterCount: 0,
+                    listParameterCount: 0,
+                    reason: "tenant_param_alignment",
+                }, "parameterize extras dropped");
             }
         }
     }
-    applySensitiveGuardrail(result, options, logger);
+    applySensitiveGuardrail(result, options, dialectSpec, logger);
     return result;
 }
+/**
+ * Replace a `subtree` access with the per-root access it expands to: `multi_root`
+ * with one entry per root the subtree covers (the scope's root first, then its
+ * descendant roots breadth-first), including a level with no IDs (`ids: []`), or `ids`
+ * when the subtree is the scope's root alone. Other access kinds pass through untouched.
+ *
+ * Each root's IDs stay under that root, so they bind only to its own placeholder:
+ * root tables have separate ID spaces, and folding a client ID into the agency
+ * placeholder would match another agency (#338). This relies on every root deriving a distinct
+ * placeholder, which `validateTenantScope()` and the policy loader enforce. The seeds are unioned into the
+ * `tenantRoot` entry here, not trusted to the resolver, so an ancestor never loses
+ * its own rows when a host returns strict descendants only.
+ *
+ * Fails closed with `SUBTREE_NOT_RESOLVABLE`: no resolver; a result that is an
+ * array (the old flat shape) or not a plain object; a key that isn't a root in
+ * this subtree; a value that isn't an array of non-empty strings; or no IDs at all.
+ */
+async function expandSubtreeScope(policy, scope, resolve) {
+    const access = scope.access;
+    if (access.kind !== "subtree")
+        return scope;
+    const { tenantRoot, rootIds } = access;
+    const levels = subtreeRootIds(policy, tenantRoot);
+    const shape = `{ ${levels.map((root) => `"${root}": [...]`).join(", ")} }`;
+    const fail = (message) => new TenantScopeError(message, "SUBTREE_NOT_RESOLVABLE");
+    if (!resolve) {
+        throw fail(`tenantScope.access is a 'subtree' of '${tenantRoot}', but no ` +
+            "resolveTenantDescendants was passed to ask(). AskDB does not query your database " +
+            "to find descendants: pass resolveTenantDescendants to expand the seed IDs, or pass " +
+            "an 'ids' or 'multi_root' access with each root's IDs already expanded.");
+    }
+    const result = await resolve(tenantRoot, rootIds);
+    if (Array.isArray(result)) {
+        throw fail(`resolveTenantDescendants for '${tenantRoot}' returned an array. It must return IDs per ` +
+            `tenant root, keyed by root table id: ${shape}. Root tables have separate ID spaces, so ` +
+            "a flat list can't say which root each ID belongs to, and binding them all to " +
+            `'${tenantRoot}' would match other tenants. Put the seeds and any same-table ` +
+            `descendants under '${tenantRoot}', and each descendant root's IDs under that root.`);
+    }
+    if (!isPlainObject(result)) {
+        throw fail(`resolveTenantDescendants for '${tenantRoot}' must return an object mapping each ` +
+            `tenant root in the subtree to its IDs: ${shape}.`);
+    }
+    // Read the result exactly once: validate and build from this snapshot, so a getter
+    // can't return one value to validation and another to the scope, and a property
+    // validation can't see (non-enumerable) is never read at all.
+    const idsByRoot = new Map();
+    const knownRoots = new Set(policy.roots.map((root) => root.id));
+    let returned = 0;
+    for (const [root, value] of Object.entries(result)) {
+        const ids = Array.isArray(value) ? [...value] : value;
+        if (!knownRoots.has(root)) {
+            throw fail(`resolveTenantDescendants returned IDs under a key the subtree can't have: '${root}' is ` +
+                `not a tenant root in the policy. Allowed keys for a subtree of '${tenantRoot}': ` +
+                `${levels.join(", ")}.`);
+        }
+        if (!levels.includes(root)) {
+            throw fail(`resolveTenantDescendants returned IDs under a key the subtree can't have: '${root}' is ` +
+                `not in the subtree of '${tenantRoot}' (the policy's hierarchy doesn't reach it from ` +
+                `there). Allowed keys: ${levels.join(", ")}.`);
+        }
+        if (!isTenantIdArray(ids)) {
+            throw fail(`resolveTenantDescendants: the IDs for '${root}' must be an array of non-empty strings.`);
+        }
+        idsByRoot.set(root, ids);
+        returned += ids.length;
+    }
+    if (returned === 0) {
+        throw fail(`resolveTenantDescendants returned no IDs for '${tenantRoot}' (seeds: ${rootIds.join(", ")}). ` +
+            `Return at least the seeds under '${tenantRoot}'; refusing to build an empty tenant scope.`);
+    }
+    // Every level the subtree covers stays in the scope, even one with no IDs. The
+    // guardrail then checks a read of that root on its own placeholder, and binding that
+    // placeholder fails closed (UNRESOLVED_TENANT_PLACEHOLDER). Dropping the level would
+    // leave its rows readable through a parent's foreign key or an ancestor, which is
+    // less restricted than a level the resolver narrowed to some IDs.
+    const scopes = levels.map((root) => {
+        const own = idsByRoot.get(root) ?? [];
+        return { tenantRoot: root, ids: [...new Set(root === tenantRoot ? [...rootIds, ...own] : own)] };
+    });
+    const expanded = scopes.length === 1 ? { kind: "ids", ...scopes[0] } : { kind: "multi_root", scopes };
+    return { ...scope, access: expanded };
+}
+function isTenantIdArray(value) {
+    return Array.isArray(value) && value.every((id) => typeof id === "string" && id.length > 0);
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /**
  * Run the sensitive-identifier guardrail over the SQL the host is about to receive.
  * Runs after tenant resolution so it sees exactly the statement in `result.sql`.
+ * With a built-in id or `DialectSpec`, the SQL is lexed the way that engine reads it;
+ * for a custom `AskDialect` (no spec) references are unioned across every built-in reading.
  */
-function applySensitiveGuardrail(result, options, logger) {
+function applySensitiveGuardrail(result, options, dialectSpec, logger) {
     const mode = options.sensitiveGuardrailMode ?? "warn";
     if (mode === "off")
         return;
     if (!schemaHasSensitiveIdentifiers(options.schema))
         return;
     try {
-        const guardrail = validateSensitiveReferences(result.sql, options.schema, { mode });
+        const guardrail = validateSensitiveReferences(result.sql, options.schema, {
+            mode,
+            dialect: dialectSpec,
+        });
         result.sensitiveGuardrail = guardrail;
         logSensitiveReferences(logger, guardrail.references);
     }
@@ -189,6 +318,91 @@ function logSensitiveReferences(logger, references) {
         sensitiveColumns,
     }, "generated SQL references sensitive identifiers");
 }
+/**
+ * Substitute tenant placeholders in `result.unboundSql` with driver markers and
+ * fold their values into `result.params`, so `unboundSql` + `params` is a single
+ * executable pair (`sql-params` mode).
+ *
+ * - `$N` / `@pN` dialects: markers are explicitly numbered, so tenant markers
+ *   continue after the business slots and tenant values are appended.
+ * - `?` dialects: markers are positional, so `params` must follow source order.
+ *   Business and tenant values are interleaved by walking the named template in
+ *   order, and `parameters[].indices` are remapped to the new positions.
+ *
+ * Returns false when the business binding and the tenant substitution disagree
+ * about the statement's shape; the caller then drops the extras rather than ship
+ * misaligned params.
+ */
+function bindTenantIntoUnboundSql(result, ctx) {
+    if (result.unboundSql === undefined)
+        return false;
+    const unbound = resolveTenantSql(result.unboundSql, ctx.tenantPolicy, ctx.tenantScope, "sql-params", ctx.businessParamCount + 1, ctx.dialectSpec);
+    if (unbound.mode !== "sql-params")
+        return false;
+    const business = result.params ?? [];
+    const tenantValues = unbound.params;
+    const dialectId = ctx.dialectSpec?.id;
+    const style = dialectId !== undefined && isBuiltInDialectId(dialectId)
+        ? markerStyleForDialect(dialectId)
+        : "dollar";
+    if (style !== "question") {
+        result.unboundSql = unbound.sql;
+        result.params = [...business, ...tenantValues];
+        return true;
+    }
+    const idsByPlaceholder = new Map(unbound.bindings.map((b) => [b.placeholder, b.ids]));
+    const bindingByName = new Map((result.parameters ?? []).map((b) => [b.name, b]));
+    // Same lexer reading as bindPreparedQuery and the tenant substitution above.
+    const occurrences = scanPlaceholders(ctx.namedSql, ctx.dialectSpec);
+    const occurrenceCount = new Map();
+    for (const occ of occurrences) {
+        occurrenceCount.set(occ.name, (occurrenceCount.get(occ.name) ?? 0) + 1);
+    }
+    const combined = [];
+    const indexMap = new Map();
+    const seen = new Map();
+    for (const occ of occurrences) {
+        const tenantIds = idsByPlaceholder.get(occ.placeholder);
+        if (tenantIds) {
+            combined.push(...tenantIds);
+            continue;
+        }
+        // bindPreparedQuery pushes each occurrence's values contiguously, in source
+        // order, so occurrence k of a name owns the k-th equal slice of its indices.
+        const binding = bindingByName.get(occ.name);
+        const total = occurrenceCount.get(occ.name);
+        if (!binding || binding.indices.length % total !== 0)
+            return false;
+        const per = binding.indices.length / total;
+        const k = seen.get(occ.name) ?? 0;
+        seen.set(occ.name, k + 1);
+        for (const idx of binding.indices.slice(k * per, (k + 1) * per)) {
+            if (idx >= business.length || indexMap.has(idx))
+                return false;
+            indexMap.set(idx, combined.length);
+            combined.push(business[idx]);
+        }
+    }
+    if (indexMap.size !== business.length ||
+        combined.length !== business.length + tenantValues.length) {
+        return false;
+    }
+    result.unboundSql = unbound.sql;
+    result.params = combined;
+    if (result.parameters) {
+        result.parameters = result.parameters.map((b) => ({
+            ...b,
+            indices: b.indices.map((i) => indexMap.get(i)),
+        }));
+    }
+    return true;
+}
+function dropParameterizeExtras(result) {
+    delete result.unboundSql;
+    delete result.params;
+    delete result.parameters;
+    delete result.preparedQuery;
+}
 const TENANT_MASK_RE = /:tenant_([a-z0-9_]+)_ids/g;
 const TENANT_UNMASK_RE = /__askdb_tenant_([a-z0-9_]+)_ids__/g;
 function maskTenantPlaceholders(sql) {
@@ -235,7 +449,7 @@ function resolveDialectSpec(input) {
 function resolveDialect(input) {
     if (typeof input === "string") {
         if (!isBuiltInDialectId(input)) {
-            throw new Error(`Unknown dialect id '${input}'. Pass a built-in DialectId, a DialectSpec object, or a custom AskDialect.`);
+            throw new UnknownDialectError(`Unknown dialect id '${input}'. Pass a built-in DialectId, a DialectSpec object, or a custom AskDialect.`, input);
         }
         return specToDialect(getDialectSpec(input));
     }
@@ -245,14 +459,16 @@ function resolveDialect(input) {
 }
 function specToDialect(spec) {
     return {
-        generate: (question, schema, model, options) => generateSelectSql(spec, question, schema, model, options),
+        // ask() runs the tenant guardrail itself on the final SQL, so the built-in
+        // generator's copy is skipped to avoid a second (pre-substitution) report.
+        generate: (question, schema, model, options) => generateSelectSqlWithoutTenantGuardrail(spec, question, schema, model, options),
     };
 }
 /** Default chunk-count threshold below which the full DDL is preferred. */
 const DEFAULT_RETRIEVAL_THRESHOLD_CHUNKS = 30;
 const DEFAULT_RETRIEVAL_K = 8;
 async function maybeRetrieveDdl(args) {
-    const { options, logger, omitSensitive } = args;
+    const { options, logger, omitSensitive, unqualifiedNamespace, quoteIdentifier } = args;
     const retriever = options.retriever;
     if (!retriever)
         return undefined;
@@ -291,6 +507,8 @@ async function maybeRetrieveDdl(args) {
         schema: options.schema,
         results,
         omitSensitiveIdentifiersFromPrompt: omitSensitive,
+        unqualifiedNamespace,
+        quoteIdentifier,
     });
     logger?.info({
         event: AskDbLogEvent.PipelineRetrievalUsed,