[FEATURE] `predelete` hook: run a statement or script before a resource's `delete`

Problem

Some resources cannot be deleted until something else is done to them first, and that something is not expressible as a single statement in the resource's .iql file. The canonical case is an S3 bucket: DeleteBucket fails with 409 BucketNotEmpty (surfaced by stackql as no response body for operation = DeleteBucket) while the bucket holds objects, and emptying a bucket needs an object listing loop (and a version listing loop for versioned buckets). A Databricks workspace root bucket is never empty at teardown time because the control plane writes DBFS and log data into it.

Today the only options are:

• skip_on_delete: true on the bucket, which retains it (fine when the data should be kept, wrong when it should not),
• --on-failure ignore, which finishes the teardown but leaves the bucket behind, or
• an out-of-band aws s3 rm --recursive before running teardown.

Other resources with the same shape: ECR repositories with images, Cognito user pools with a deletion protection flag, RDS instances with deletion protection, Key Vaults with soft delete, GitHub repositories with branch protection rules, or any resource where a dependent that is not managed by the stack has to be cleared first.

Proposal

A predelete hook that teardown runs for a resource after the exists check reports the resource present and before its delete statement. Two forms:

1. A /*+ predelete */ anchor in the resource's .iql file for cases that are a single statement (for example flipping a deletion protection property with an UPDATE, or a DELETE on a dependent resource that the provider can address in one call). Rendered with the same context as delete, including this.* fields captured by the exists check.
2. A predelete script in the manifest for cases that need a loop or an external tool, using the same contract as type: script resources (run with sh -c, exports optional):

  - name: aws/s3/root_bucket
    file: aws/s3/bucket.iql
    predelete:
      run: aws s3 rm s3://{{ root_bucket_name }} --recursive
    props:
      - name: bucket_name
        value: "{{ root_bucket_name }}"

If both are present the anchor runs first, then the script.

Behaviour to pin down

• Ordering. exists check, then predelete, then delete, then callback:delete, then the post-delete check (per postdelete_retries / postdelete_retry_delay). When the delete is re-issued (the delete anchor's retries), predelete should run again before each attempt, since the reason for the retry may be that more objects appeared.
• Failure. A failing predelete is a failed delete: abort under --on-failure error, log and report the resource as not confirmed deleted under --on-failure ignore. Fatal errors abort in both modes.
• Dry run. Render and log the anchor / script without executing, like delete.
• Not run when the resource does not exist, when the resource has skip_on_delete: true, or when the delete is skipped because a query references an export that could not be collected.
• Not run by build or test.
• Idempotency is the author's responsibility, as with script resources; document that a predelete may run more than once per teardown.
• The anchor form should support the usual options (retries, retry_delay).

Related

• #56 / #57: skip_on_delete, --on-failure ignore and the end-of-run summary of unconfirmed deletes, which are the current workarounds.
• The tests/live_stacks/aws_ssm_onfailure live stack already has an S3 DeleteBucket failure case; a predelete that empties a bucket could be exercised there, or in a small dedicated S3 stack (an empty standard bucket is free).

Start by reading the teardown delete flow and the existing type: script resource contract, then inspect tests/live_stacks/aws_ssm_onfailure for the existing S3 DeleteBucket failure case. Define and test the ordering, retry, failure, dry-run, skip, and idempotency behavior described here; done means a predelete anchor and manifest script work without affecting build or test.