@askdb/core 1.0.0-beta.41 → 1.0.0-beta.43

package/dist/sql/prompt.js

@@ -18,7 +18,13 @@ export function buildNlToSqlUserPrompt(dialect, question, schema, ambiguityNotes
  * still fires using the consumer-supplied `nlToSqlSchemaOptions` to keep
  * observability consistent.
  */
-prebuiltDdl, tenantPolicy, tenantScope) {
+prebuiltDdl, tenantPolicy, tenantScope, 
+/**
+ * When true, append the unbound-SQL + parameter-manifest output-format
+ * instructions. When false/undefined, the prompt is unchanged from the
+ * pre-parameterize path (byte-identical).
+ */
+parameterize) {
     const formatted = isV2(schema)
         ? formatSchemaV2ForNlToSql(schema, nlToSqlSchemaOptions)
         : formatSchemaForNlToSql(schema, nlToSqlSchemaOptions);
@@ -66,6 +72,23 @@ prebuiltDdl, tenantPolicy, tenantScope) {
         lines.push("");
     }
     lines.push(`Question: ${question}`);
+    if (parameterize === true) {
+        const listBinding = dialect.listBinding ?? "expand";
+        const listForm = listBinding === "array"
+            ? "For multi-value parameters use `= ANY(:name)` (array dialects)."
+            : "For multi-value parameters use `IN (:name)`.";
+        lines.push("");
+        lines.push("Parameterized output format (required):");
+        lines.push("1. Emit the complete bound SQL (values inlined as literals) in a ```sql fence — exactly as you would without this instruction.");
+        lines.push("2. Emit the same statement in a ```sql-unbound fence, replacing values taken from the user's question with `:name` placeholders.");
+        lines.push("3. Emit a ```json fence with `{\"parameters\":[{\"name\",\"type\",\"cardinality\",\"description\",\"value\"}, ...]}` describing each placeholder.");
+        lines.push("- Placeholder names match `^[a-z][a-z0-9_]*$`. Never quote placeholders (`state = :state_name`, never `state = ':state_name'`).");
+        lines.push("- Never write `$1`, `?`, or `@p0` markers — only `:name` placeholders. AskDB derives driver markers.");
+        lines.push(`- ${listForm}`);
+        lines.push("- Types are `string` | `number` | `boolean` | `date` | `datetime`. Use `cardinality` `one` or `many`. Dates/datetimes are ISO strings.");
+        lines.push("- Keep `:tenant_*` placeholders exactly as the tenant policy block instructs; do not put them in the manifest.");
+        lines.push("- Only parameterize values that came from the user's question — not structural constants you chose (e.g. status enums you invented).");
+    }
     return lines.join("\n");
 }
 /** Dialect-parameterized system prompt for the NL→SQL generator. */

package/dist/sql/prompt.js.map

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

package/dist/sql/sensitive-guardrail.d.ts

@@ -0,0 +1,62 @@
+import { type SensitiveReference, type SensitiveScopeReport } from "../errors.js";
+import type { AnyNormalizedSchema } from "../schema/types.js";
+import type { DialectSpec } from "./dialect-spec.js";
+export type SensitiveGuardrailMode = "warn" | "strict";
+export type ValidateSensitiveReferencesOptions = {
+    /**
+     * `"warn"` (default) returns the references without throwing — today's CLI behaviour.
+     * `"strict"` throws {@link SensitiveReferenceError} whenever the statement cannot be
+     * proven clean (references found, or scope could not be resolved).
+     */
+    mode?: SensitiveGuardrailMode;
+    /**
+     * The engine the SQL targets, so strings, quoted identifiers, and comments are lexed
+     * the way that engine reads them (e.g. MySQL backslash escapes, Postgres `E'…'`).
+     * When omitted, references are collected under every built-in engine's reading, which
+     * is conservative and can over-report in rare cases.
+     */
+    dialect?: Pick<DialectSpec, "id" | "backslashEscapes">;
+};
+export type SensitiveGuardrailResult = {
+    /** True only when nothing sensitive was referenced **and** table scope was fully resolved. */
+    passed: boolean;
+    references: SensitiveReference[];
+    /** Present when the statement's `FROM`/`JOIN` scope could not be resolved with confidence. */
+    unresolvedScope?: SensitiveScopeReport;
+};
+/**
+ * Check whether a SQL statement references tables/columns marked `sensitive`
+ * in the schema artifact.
+ *
+ * `sensitive: true` is otherwise a **prompt-level** marker: `formatSchemaForNlToSql`
+ * either tags identifiers `(sensitive)` or withholds them entirely. Both act on what
+ * the model *sees*. This function is the **enforcement** path — it inspects SQL that
+ * is about to execute, so hosts that cache, store, or replay statements should call it
+ * on every execution path, not only at generation time.
+ *
+ * Unlike a bare substring scan, an unqualified column name only counts when the owning
+ * table is actually in the statement's scope: `FROM`/`JOIN` targets and their aliases
+ * are resolved first. When scope cannot be resolved (no resolvable table source, or a
+ * qualifier that binds to nothing known), the check fails conservatively — it widens
+ * matching and reports why in {@link SensitiveGuardrailResult.unresolvedScope} — rather
+ * than passing silently. A string, quoted identifier, or comment that never closes is
+ * reported the same way (`UNTERMINATED_TOKEN`).
+ *
+ * `SELECT *`, `alias.*`, and whole-row references such as `row_to_json(alias)` count as
+ * referencing every sensitive column of the table they reach. They expand per query
+ * block: a bare `*` covers its own `SELECT`'s FROM/JOIN tables, and an alias resolves in
+ * its own block first, then in enclosing blocks. When the block structure cannot be
+ * read with confidence, they expand against every table in the statement.
+ *
+ * Heuristic, not a SQL parser, and not a security boundary. It is defense in depth for
+ * review and enforcement; database-side column privileges are the real control.
+ */
+export declare function validateSensitiveReferences(sql: string, schema: AnyNormalizedSchema, options?: ValidateSensitiveReferencesOptions): SensitiveGuardrailResult;
+/**
+ * True when the schema marks at least one table or column `sensitive`. Cheap pre-check
+ * for hosts (and `ask()`) that skip the guardrail entirely on schemas with no markers.
+ */
+export declare function schemaHasSensitiveIdentifiers(schema: AnyNormalizedSchema): boolean;
+/** Render a reference as `schema.table.column` (or `table.column` when the schema has no namespace). */
+export declare function formatSensitiveReference(ref: SensitiveReference): string;
+//# sourceMappingURL=sensitive-guardrail.d.ts.map

package/dist/sql/sensitive-guardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-guardrail.d.ts","sourceRoot":"","sources":["../../src/sql/sensitive-guardrail.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EAGvB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAUrD,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,MAAM,kCAAkC,GAAG;IAC/C;;;;OAIG;IACH,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,kBAAkB,CAAC,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,8FAA8F;IAC9F,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,8FAA8F;IAC9F,eAAe,CAAC,EAAE,oBAAoB,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,mBAAmB,EAC3B,OAAO,CAAC,EAAE,kCAAkC,GAC3C,wBAAwB,CAiB1B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAElF;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAGxE"}