fix: harden related-subquery policy enforcement

CHANGELOG.md

@@ -13,6 +13,10 @@ This file tracks the major changes in each release.
 - Added a security policy and threat model covering safe deployment defaults, cross-tenant data exposure, schema-context filtering, observability data exposure, and vulnerability reporting.
 
 ### Changed
+- Security compatibility: when a `policy_adapter` is configured, executable `Query` objects must come from `CodeToQuery.ask` (or the compiler path) with the compiler's opaque policy contract. Directly constructed queries have no valid contract and now fail closed.
+- `Query#sql`, `#params`, `#intent`, and `#metrics` now return detached deep copies. Mutating a returned value no longer changes query state; repeated reads may allocate new objects.
+- Compiled policy queries are bound to the exact policy adapter and configuration identity used at compilation. Replacing the adapter or relevant configuration invalidates existing queries; compile them again before execution.
+- Compatibility note: policy adapters that explicitly return `allowed_tables: []` deny access to all tables, as intended; omit `allowed_tables` only when no policy table allowlist is being supplied.
 - Added explicit explain-gate profiles and deployment tradeoff guidance for `explain_fail_open` in the README, including strict, availability-first, and local/test configuration patterns.
 - Breaking default change: EXPLAIN gate errors now fail closed by default; set `explain_fail_open = true` only for availability-first readonly deployments that can tolerate skipped EXPLAIN checks.
 - Context pack generation now omits sensitive schema metadata by default for password, secret, token, credential, digest, salt, OTP, and API key style columns; customize `sensitive_column_patterns` when applications use additional naming conventions.

docs/pundit-policy-adapter.md

@@ -27,6 +27,12 @@ Keep these boundaries explicit:
 - **Pundit remains authoritative.** Use Pundit to decide whether the user can access the reporting surface. Do not use natural-language prompts as authorization input.
 - **Keep logs narrow.** Prefer logging table names, policy key names, and decisions. Avoid logging raw prompts, row data, full bind values, credentials, or full generated schema context in normal application logs.
 
+### Query lifecycle and compatibility
+
+- With a `policy_adapter` configured, obtain executable queries through `CodeToQuery.ask` or the compiler path. Policy compilation issues an opaque contract that callers cannot construct; a directly instantiated `CodeToQuery::Query` lacks that evidence and fails closed at safety checks and execution.
+- A compiled query's policy contract is bound to the exact policy adapter object and configuration instance used to compile it, including the captured database adapter and policy fail-open setting. Replacing the policy adapter or changing that relevant configuration invalidates the query. Recompile instead of retaining policy-bearing queries across configuration changes or application reloads.
+- The public `Query#sql`, `#params`, `#intent`, and `#metrics` readers return detached deep copies. Mutating those values does not alter the immutable state used for safety checks or execution, and repeated reads may allocate new objects.
+
 ## Lambda adapter for tenant, account, and user predicates
 
 This example keeps table and column exposure small and derives row predicates from trusted application state. It raises on missing users, unknown tables, and denied policies so CodeToQuery fails closed. Define the custom Pundit predicates such as `code_to_query?`, `view_all_tickets?`, and `view_account_users?` on the relevant policies before using this shape.

lib/code_to_query.rb

@@ -12,6 +12,8 @@
 require_relative 'code_to_query/configuration'
 require_relative 'code_to_query/errors'
 require_relative 'code_to_query/instrumentation'
+require_relative 'code_to_query/identifier_semantics'
+require_relative 'code_to_query/policy_adapter_invoker'
 require_relative 'code_to_query/providers/base'
 require_relative 'code_to_query/providers/openai'
 require_relative 'code_to_query/providers/local'
@@ -110,7 +112,9 @@ def self.ask(prompt:, schema: nil, allow_tables: nil, current_user: nil)
       policy_applied: false
     }
     compiled = Instrumentation.instrument(:compile, compile_payload) do
-      compile_result = Compiler.new(config).compile(validated_intent, current_user: current_user)
+      compile_result = Compiler.new(config).compile(
+        validated_intent, current_user: current_user, allow_tables: allow_tables
+      )
       compile_payload[:policy_applied] = policy_applied_from_bind_spec?(compile_result[:bind_spec])
       compile_result
     end
@@ -124,9 +128,13 @@ def self.ask(prompt:, schema: nil, allow_tables: nil, current_user: nil)
       row_limit: validated_intent['limit'],
       policy_applied: policy_applied
     }
+    query = Query.new(sql: compiled[:sql], params: compiled[:params], bind_spec: compiled[:bind_spec],
+                      intent: compiled[:intent] || validated_intent, allow_tables: allow_tables, config: config,
+                      policy_contract: compiled[:policy_contract])
+
     begin
       Instrumentation.instrument(:lint, **lint_payload) do
-        Guardrails::SqlLinter.new(config, allow_tables: allow_tables).check!(compiled[:sql])
+        query.send(:lint_sql!)
       end
     rescue SecurityError => e
       Instrumentation.instrument(
@@ -141,8 +149,7 @@ def self.ask(prompt:, schema: nil, allow_tables: nil, current_user: nil)
       raise
     end
 
-    Query.new(sql: compiled[:sql], params: compiled[:params], bind_spec: compiled[:bind_spec],
-              intent: validated_intent, allow_tables: allow_tables, config: config)
+    query
   end
 
   def self.query_shape(intent)