Add RETURNING * capture and callback polling support

[jeffreyaven]

Summary

This PR adds support for capturing RETURNING * results from DML operations (INSERT/UPDATE/DELETE) and implements callback polling for tracking long-running asynchronous operations. This is particularly useful for providers like AWS Cloud Control API (awscc) that return operation tracking handles requiring polling until completion.

Key Changes

Core Utilities (src/core/utils.rs)

• has_returning_clause() — Detects if a query contains a RETURNING clause (case-insensitive)
• run_stackql_dml_returning() — Executes DML commands and captures the first row of RETURNING * results as a HashMap<String, String>, with retry logic and error handling
• flatten_returning_row() — Flattens a RETURNING row into dotted context keys:
  • callback.{field} (shorthand, scoped to current resource)
  • {resource_name}.callback.{field} (fully-qualified, accessible downstream)
• flatten_value_into_context() and flatten_json_into_context() — Recursively expand JSON objects in RETURNING results into nested dotted keys (e.g., ProgressEvent.OperationStatus)
• check_short_circuit() — Checks if a short-circuit condition is met in captured callback data to skip polling when operation status is already terminal
• run_callback_poll() — Polls a callback query until success or count column returns a truthy value, with configurable retries and delays
• Comprehensive unit tests for all new functions

Template Engine (src/template/engine.rs)

• preprocess_this_prefix() — Preprocesses this. prefix in Tera templates, replacing it with {resource_name}. to enable resource-scoped variable references within .iql files
• insert_nested_key() — Recursively builds nested JSON objects from dotted keys to support multi-level property access (e.g., {{ callback.ProgressEvent.RequestToken }})
• Enhanced build_tera_context() to handle arbitrary-depth dotted keys instead of just two-level nesting
• Unit tests validating three and four-level dotted key access

Templating Configuration (src/core/templating.rs)

• Extended QueryOptions struct with:
  • short_circuit_field: Option<String> — Dot-path into RETURNING result to check before polling
  • short_circuit_value: Option<String> — Expected value that allows skipping polling
• Updated parse_anchor() to distinguish between numeric and string-valued options
• Modified load_sql_queries() to return separate maps for uint and string options
• Updated get_queries() to populate new callback options from parsed anchors
• Added documentation for callback anchor syntax and options

Command Runner (src/commands/base.rs)

• create_resource() — Now returns (bool, Option<HashMap<String, String>>) to capture RETURNING data
• update_resource() — Now returns (bool, Option<HashMap<String, String>>) to capture RETURNING data
• delete_resource() — Now returns Option<HashMap<String, String>> to capture RETURNING data
• store_callback_data() — Stores flattened RETURNING row in global context for downstream access
• run_callback() — Executes callback polling with short-circuit support
• All three methods now detect RETURNING clauses and use run_stackql_dml_returning() when present
• Dry-run mode properly logs RETURNING intent without executing captures

Build Command (src/commands/build.rs)

• After successful create or update, captures RETURNING data and stores it
• Executes callback:create or callback:update blocks (or bare callback) if present
• Passes short-circuit field/value to callback runner
• Handles both operation-specific (callback:create) and generic (callback) anchors

Teardown Command (src/commands/teardown.rs)

https://claude.ai/code/session_01HcAKNRjjQRn7TywY28zv1Y