@askdb/core 0.5.0-beta.12 → 0.5.0-beta.14

package/dist/sql/tenant-placeholders.js

@@ -0,0 +1,156 @@
+// ---------------------------------------------------------------------------
+// Placeholder naming convention (matches tenant-prompt.ts)
+// ---------------------------------------------------------------------------
+const PLACEHOLDER_RE = /:tenant_([a-z0-9_]+)_ids/g;
+export function placeholderForRoot(label) {
+    return `:tenant_${label.toLowerCase().replace(/[^a-z0-9]+/g, "_")}_ids`;
+}
+// ---------------------------------------------------------------------------
+// Extract placeholders found in SQL
+// ---------------------------------------------------------------------------
+export function extractTenantPlaceholders(sql) {
+    const matches = new Set();
+    for (const m of sql.matchAll(PLACEHOLDER_RE)) {
+        matches.add(m[0]);
+    }
+    return [...matches];
+}
+export function resolvePlaceholders(sql, policy, scope) {
+    const placeholders = extractTenantPlaceholders(sql);
+    if (placeholders.length === 0)
+        return [];
+    const rootsByPlaceholder = new Map();
+    for (const root of policy.roots) {
+        rootsByPlaceholder.set(placeholderForRoot(root.label), {
+            rootId: root.id,
+            label: root.label,
+        });
+    }
+    const idsByRoot = buildIdsByRoot(scope.access);
+    const resolved = [];
+    for (const ph of placeholders) {
+        const rootInfo = rootsByPlaceholder.get(ph);
+        if (!rootInfo)
+            continue;
+        const ids = idsByRoot.get(rootInfo.rootId) ?? [];
+        resolved.push({
+            placeholder: ph,
+            rootLabel: rootInfo.label,
+            rootId: rootInfo.rootId,
+            ids,
+        });
+    }
+    return resolved;
+}
+function buildIdsByRoot(access) {
+    const m = new Map();
+    switch (access.kind) {
+        case "ids":
+            m.set(access.tenantRoot, access.ids);
+            break;
+        case "subtree":
+            m.set(access.tenantRoot, access.rootIds);
+            break;
+        case "multi_root":
+            for (const s of access.scopes) {
+                const existing = m.get(s.tenantRoot) ?? [];
+                m.set(s.tenantRoot, [...existing, ...s.ids]);
+            }
+            break;
+        case "global":
+            break;
+    }
+    return m;
+}
+// ---------------------------------------------------------------------------
+// Replace placeholders — SQL-only mode (inline literals)
+// ---------------------------------------------------------------------------
+function escapeSqlLiteral(value) {
+    return "'" + value.replace(/'/g, "''") + "'";
+}
+export function replacePlaceholdersWithLiterals(sql, resolved) {
+    let result = sql;
+    for (const r of resolved) {
+        if (r.ids.length === 0)
+            continue;
+        const literal = r.ids.length === 1
+            ? escapeSqlLiteral(r.ids[0])
+            : `(${r.ids.map(escapeSqlLiteral).join(", ")})`;
+        result = replaceOperatorAware(result, r.placeholder, literal, r.ids.length > 1);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Replace placeholders — SQL+params mode (positional $N)
+// ---------------------------------------------------------------------------
+export function replacePlaceholdersWithParams(sql, resolved, startIndex = 1) {
+    let result = sql;
+    const params = [];
+    let idx = startIndex;
+    for (const r of resolved) {
+        if (r.ids.length === 0)
+            continue;
+        if (r.ids.length === 1) {
+            const paramRef = `$${idx}`;
+            result = replaceOperatorAware(result, r.placeholder, paramRef, false);
+            params.push(r.ids[0]);
+            idx++;
+        }
+        else {
+            const paramRefs = r.ids.map(() => `$${idx++}`);
+            const paramList = `(${paramRefs.join(", ")})`;
+            result = replaceOperatorAware(result, r.placeholder, paramList, true);
+            params.push(...r.ids);
+        }
+    }
+    return { sql: result, params, nextIndex: idx };
+}
+// ---------------------------------------------------------------------------
+// Operator-aware replacement: = → IN when multiple values
+// ---------------------------------------------------------------------------
+function replaceOperatorAware(sql, placeholder, replacement, isMultiple) {
+    if (isMultiple) {
+        const eqPattern = new RegExp(`=\\s*${escapeRegex(placeholder)}`, "g");
+        sql = sql.replace(eqPattern, `IN ${replacement}`);
+        const inPattern = new RegExp(`IN\\s*\\(\\s*${escapeRegex(placeholder)}\\s*\\)`, "gi");
+        sql = sql.replace(inPattern, `IN ${replacement}`);
+    }
+    sql = sql.replace(new RegExp(escapeRegex(placeholder), "g"), replacement);
+    return sql;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// ---------------------------------------------------------------------------
+// High-level entry point
+// ---------------------------------------------------------------------------
+export function resolveTenantSql(sql, policy, scope, mode = "sql-only", paramStartIndex = 1) {
+    if (scope.access.kind === "global") {
+        return mode === "sql-only"
+            ? { mode: "sql-only", sql, bindings: [] }
+            : { mode: "sql-params", sql, params: [], bindings: [], paramStartIndex };
+    }
+    const resolved = resolvePlaceholders(sql, policy, scope);
+    const bindings = resolved.map((r) => ({
+        placeholder: r.placeholder,
+        rootLabel: r.rootLabel,
+        rootId: r.rootId,
+        ids: r.ids,
+    }));
+    if (mode === "sql-only") {
+        return {
+            mode: "sql-only",
+            sql: replacePlaceholdersWithLiterals(sql, resolved),
+            bindings,
+        };
+    }
+    const paramResult = replacePlaceholdersWithParams(sql, resolved, paramStartIndex);
+    return {
+        mode: "sql-params",
+        sql: paramResult.sql,
+        params: paramResult.params,
+        bindings,
+        paramStartIndex,
+    };
+}
+//# sourceMappingURL=tenant-placeholders.js.map

package/dist/sql/tenant-placeholders.js.map

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

package/dist/sql/tenant-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedTenantPolicy } from "../schema/v2/tenant-policy.js";
+import type { TenantScope } from "../schema/v2/tenant-policy.js";
+/**
+ * Build the tenant policy + runtime scope block for NL→SQL prompts.
+ * This block is always injected when a tenant policy exists (security boundary).
+ */
+export declare function buildTenantPromptBlock(policy: NormalizedTenantPolicy, scope: TenantScope): string;
+//# sourceMappingURL=tenant-prompt.d.ts.map

package/dist/sql/tenant-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-prompt.d.ts","sourceRoot":"","sources":["../../src/sql/tenant-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,WAAW,GACjB,MAAM,CA4HR"}

package/dist/sql/tenant-prompt.js

@@ -0,0 +1,127 @@
+/**
+ * Build the tenant policy + runtime scope block for NL→SQL prompts.
+ * This block is always injected when a tenant policy exists (security boundary).
+ */
+export function buildTenantPromptBlock(policy, scope) {
+    const lines = [];
+    lines.push("--- TENANT POLICY (mandatory — every tenant-scoped table MUST be filtered) ---");
+    lines.push("");
+    // Hierarchy
+    lines.push("Tenant hierarchy:");
+    for (const root of policy.roots) {
+        const parentNote = root.parent
+            ? ` (child of ${policy.roots.find((r) => r.id === root.parent.root)?.label ?? root.parent.root})`
+            : " (top-level)";
+        lines.push(`  - ${root.label} [${root.id}]${parentNote}`);
+    }
+    lines.push("");
+    // Scoped tables
+    if (policy.scopedTables.length > 0) {
+        lines.push("Tenant-scoped tables (MUST include tenant predicate):");
+        for (const st of policy.scopedTables) {
+            for (const path of st.scopeThrough) {
+                const rootLabel = policy.roots.find((r) => r.id === path.root)?.label ?? path.root;
+                if ("column" in path) {
+                    lines.push(`  - ${st.id} → filter via ${path.column} (${rootLabel} scope)`);
+                }
+                else {
+                    const joinPath = path.join.map((j) => `${j.from} → ${j.to}`).join(" → ");
+                    lines.push(`  - ${st.id} → join path: ${joinPath} (${rootLabel} scope)`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // Polymorphic tables
+    if (policy.polymorphicTables.length > 0) {
+        lines.push("Polymorphic tables (MUST include type discriminator AND id filter):");
+        for (const pt of policy.polymorphicTables) {
+            lines.push(`  - ${pt.id}: type column = ${pt.typeColumn}, id column = ${pt.idColumn}`);
+            for (const [typeVal, targetRoot] of Object.entries(pt.mapping)) {
+                const rootLabel = policy.roots.find((r) => r.id === targetRoot)?.label ?? targetRoot;
+                lines.push(`    - '${typeVal}' → ${rootLabel}`);
+            }
+        }
+        lines.push("");
+    }
+    // Global tables
+    if (policy.globalTables.length > 0) {
+        lines.push("Global tables (no tenant filter needed):");
+        for (const gt of policy.globalTables) {
+            lines.push(`  - ${gt}`);
+        }
+        lines.push("");
+    }
+    // Runtime scope
+    lines.push("Current user scope:");
+    const access = scope.access;
+    switch (access.kind) {
+        case "ids": {
+            const rootLabel = policy.roots.find((r) => r.id === access.tenantRoot)?.label ?? access.tenantRoot;
+            const placeholder = `:tenant_${rootLabel.toLowerCase().replace(/[^a-z0-9]+/g, "_")}_ids`;
+            lines.push(`  Access: ${rootLabel} IDs = ${placeholder}`);
+            lines.push(`  Use ${placeholder} as the parameter placeholder for tenant predicates.`);
+            break;
+        }
+        case "subtree": {
+            const rootLabel = policy.roots.find((r) => r.id === access.tenantRoot)?.label ?? access.tenantRoot;
+            const placeholder = `:tenant_${rootLabel.toLowerCase().replace(/[^a-z0-9]+/g, "_")}_ids`;
+            lines.push(`  Access: ${rootLabel} subtree from IDs = ${placeholder} (include all descendants)`);
+            lines.push(`  Use ${placeholder} as the parameter placeholder for tenant predicates.`);
+            break;
+        }
+        case "multi_root": {
+            lines.push("  Access: multiple roots —");
+            for (const s of access.scopes) {
+                const rootLabel = policy.roots.find((r) => r.id === s.tenantRoot)?.label ?? s.tenantRoot;
+                const placeholder = `:tenant_${rootLabel.toLowerCase().replace(/[^a-z0-9]+/g, "_")}_ids`;
+                lines.push(`    - ${rootLabel} IDs = ${placeholder}`);
+            }
+            break;
+        }
+        case "global":
+            lines.push(`  Access: GLOBAL (reason: ${access.reason}) — no tenant filtering required`);
+            break;
+    }
+    lines.push("");
+    // Advisory context
+    if (scope.context) {
+        const ctx = scope.context;
+        const parts = [];
+        if (ctx.role)
+            parts.push(`role: ${ctx.role}`);
+        if (ctx.department)
+            parts.push(`department: ${ctx.department}`);
+        if (ctx.region)
+            parts.push(`region: ${ctx.region}`);
+        if (ctx.label)
+            parts.push(`user: ${ctx.label}`);
+        if (ctx.description)
+            parts.push(ctx.description);
+        if (ctx.attributes) {
+            for (const [k, v] of Object.entries(ctx.attributes)) {
+                parts.push(`${k}: ${v}`);
+            }
+        }
+        if (parts.length > 0) {
+            lines.push("User context (advisory — not enforced):");
+            for (const part of parts) {
+                lines.push(`  - ${part}`);
+            }
+            lines.push("");
+        }
+    }
+    // Enforcement instructions
+    lines.push("Enforcement rules:");
+    lines.push("- Every query on a tenant-scoped table MUST include the tenant predicate.");
+    lines.push("- Use named placeholders for tenant IDs (e.g., :tenant_agency_ids).");
+    lines.push("- For inherited scope, JOIN through the specified path to reach the tenant root.");
+    lines.push("- For polymorphic tables, always include the type discriminator column in WHERE.");
+    lines.push("- Global/reference tables do NOT need tenant predicates.");
+    if (scope.access.kind === "global") {
+        lines.push("- GLOBAL scope is active — tenant predicates are optional for this query.");
+    }
+    lines.push("--- END TENANT POLICY ---");
+    return lines.join("\n");
+}
+//# sourceMappingURL=tenant-prompt.js.map

package/dist/sql/tenant-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-prompt.js","sourceRoot":"","sources":["../../src/sql/tenant-prompt.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAA8B,EAC9B,KAAkB;IAElB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,gFAAgF,CAAC,CAAC;IAC7F,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,YAAY;IACZ,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM;YAC5B,CAAC,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAO,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG;YAClG,CAAC,CAAC,cAAc,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,EAAE,IAAI,UAAU,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,gBAAgB;IAChB,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;QACpE,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACrC,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,YAAY,EAAE,CAAC;gBACnC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC;gBACnF,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;oBACrB,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,iBAAiB,IAAI,CAAC,MAAM,KAAK,SAAS,SAAS,CAAC,CAAC;gBAC9E,CAAC;qBAAM,CAAC;oBACN,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACzE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,iBAAiB,QAAQ,KAAK,SAAS,SAAS,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,qBAAqB;IACrB,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;QAClF,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,mBAAmB,EAAE,CAAC,UAAU,iBAAiB,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YACvF,KAAK,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,EAAE,KAAK,IAAI,UAAU,CAAC;gBACrF,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,OAAO,SAAS,EAAE,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,gBAAgB;IAChB,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACvD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,gBAAgB;IAChB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC;YACnG,MAAM,WAAW,GAAG,WAAW,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC;YACzF,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,UAAU,WAAW,EAAE,CAAC,CAAC;YAC1D,KAAK,CAAC,IAAI,CAAC,SAAS,WAAW,sDAAsD,CAAC,CAAC;YACvF,MAAM;QACR,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC;YACnG,MAAM,WAAW,GAAG,WAAW,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC;YACzF,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,uBAAuB,WAAW,4BAA4B,CAAC,CAAC;YACjG,KAAK,CAAC,IAAI,CAAC,SAAS,WAAW,sDAAsD,CAAC,CAAC;YACvF,MAAM;QACR,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;YACzC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,UAAU,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,UAAU,CAAC;gBACzF,MAAM,WAAW,GAAG,WAAW,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC;gBACzF,KAAK,CAAC,IAAI,CAAC,SAAS,SAAS,UAAU,WAAW,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,QAAQ;YACX,KAAK,CAAC,IAAI,CAAC,6BAA6B,MAAM,CAAC,MAAM,kCAAkC,CAAC,CAAC;YACzF,MAAM;IACV,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,mBAAmB;IACnB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;QAC1B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,IAAI,GAAG,CAAC,UAAU;YAAE,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAChE,IAAI,GAAG,CAAC,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,IAAI,GAAG,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QAChD,IAAI,GAAG,CAAC,WAAW;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;YACtD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;IACxF,KAAK,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAC/F,KAAK,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAC/F,KAAK,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IACvE,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;IAC1F,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAExC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/sql/tenant-scope-validate.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedTenantPolicy } from "../schema/v2/tenant-policy.js";
+import { type TenantScope } from "../schema/v2/tenant-policy.js";
+/**
+ * Validate a `TenantScope` input against a tenant policy before prompt generation.
+ * Throws `TenantScopeError` on failure.
+ */
+export declare function validateTenantScope(tenantPolicy: NormalizedTenantPolicy, tenantScope: TenantScope | undefined): void;
+//# sourceMappingURL=tenant-scope-validate.d.ts.map

package/dist/sql/tenant-scope-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-scope-validate.d.ts","sourceRoot":"","sources":["../../src/sql/tenant-scope-validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,sBAAsB,EACpC,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,IAAI,CA2DN"}

package/dist/sql/tenant-scope-validate.js

@@ -0,0 +1,46 @@
+import { TenantScopeError } from "../errors.js";
+import { tenantScopeSchema } from "../schema/v2/tenant-policy.js";
+/**
+ * Validate a `TenantScope` input against a tenant policy before prompt generation.
+ * Throws `TenantScopeError` on failure.
+ */
+export function validateTenantScope(tenantPolicy, tenantScope) {
+    // Fail closed: policy exists but no scope
+    if (!tenantScope) {
+        throw new TenantScopeError("Tenant policy is active but no tenantScope was provided. " +
+            "Pass a TenantScope to ask() or remove tenant-policy.md to disable enforcement.", "MISSING_SCOPE");
+    }
+    // Validate shape with zod
+    const parsed = tenantScopeSchema.safeParse(tenantScope);
+    if (!parsed.success) {
+        throw new TenantScopeError(`Invalid tenantScope shape: ${parsed.error.message}`, "INVALID_SCOPE_SHAPE");
+    }
+    const rootIds = new Set(tenantPolicy.roots.map((r) => r.id));
+    const access = tenantScope.access;
+    switch (access.kind) {
+        case "ids":
+            if (!rootIds.has(access.tenantRoot)) {
+                throw new TenantScopeError(`tenantScope.access references unknown tenant root '${access.tenantRoot}'. ` +
+                    `Known roots: ${[...rootIds].join(", ")}`, "UNKNOWN_TENANT_ROOT");
+            }
+            break;
+        case "subtree":
+            if (!rootIds.has(access.tenantRoot)) {
+                throw new TenantScopeError(`tenantScope.access references unknown tenant root '${access.tenantRoot}'. ` +
+                    `Known roots: ${[...rootIds].join(", ")}`, "UNKNOWN_TENANT_ROOT");
+            }
+            break;
+        case "multi_root":
+            for (const scope of access.scopes) {
+                if (!rootIds.has(scope.tenantRoot)) {
+                    throw new TenantScopeError(`tenantScope.access.scopes references unknown tenant root '${scope.tenantRoot}'. ` +
+                        `Known roots: ${[...rootIds].join(", ")}`, "UNKNOWN_TENANT_ROOT");
+                }
+            }
+            break;
+        case "global":
+            // reason is already validated as non-empty by zod
+            break;
+    }
+}
+//# sourceMappingURL=tenant-scope-validate.js.map

package/dist/sql/tenant-scope-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-scope-validate.js","sourceRoot":"","sources":["../../src/sql/tenant-scope-validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAoB,MAAM,+BAA+B,CAAC;AAEpF;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAAoC,EACpC,WAAoC;IAEpC,0CAA0C;IAC1C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,gBAAgB,CACxB,2DAA2D;YACzD,gFAAgF,EAClF,eAAe,CAChB,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,gBAAgB,CACxB,8BAA8B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EACpD,qBAAqB,CACtB,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IAElC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,gBAAgB,CACxB,sDAAsD,MAAM,CAAC,UAAU,KAAK;oBAC1E,gBAAgB,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC3C,qBAAqB,CACtB,CAAC;YACJ,CAAC;YACD,MAAM;QAER,KAAK,SAAS;YACZ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,gBAAgB,CACxB,sDAAsD,MAAM,CAAC,UAAU,KAAK;oBAC1E,gBAAgB,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC3C,qBAAqB,CACtB,CAAC;YACJ,CAAC;YACD,MAAM;QAER,KAAK,YAAY;YACf,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;oBACnC,MAAM,IAAI,gBAAgB,CACxB,6DAA6D,KAAK,CAAC,UAAU,KAAK;wBAChF,gBAAgB,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC3C,qBAAqB,CACtB,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,QAAQ;YACX,kDAAkD;YAClD,MAAM;IACV,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askdb/core",
-  "version": "0.5.0-beta.12",
+  "version": "0.5.0-beta.14",
   "description": "AskDB core: dialect-agnostic NL→SQL pipeline. Provides ask() orchestration, schema/IR types, modes, logging, and retrieval input. Bring your own dialect (e.g. @askdb/postgres).",
   "keywords": [
     "askdb",