feat: Hook system for partition cleanup lifecycle

[vmercierfr]

Summary

This PR introduces a requirements specification for a hook system that allows users to execute custom commands before and after partition archival operations (detach/drop).

The primary use case is archiving partition data (e.g., to S3) before dropping partitions, but the system is designed to be generic enough to support any pre/post operation workflow.

Specification

The full requirements document is available at: .kiro/specs/partition-hooks/requirements.md

Key Design Decisions

Hook Types (initial implementation)

• shell — Execute arbitrary commands with template variables and optional credential propagation
• postgresql — Execute SQL statements (e.g., VACUUM, ANALYZE) using PPM database connection

Hook Types (future)

• s3 — PPM-managed extraction pipeline with two modes:
  • streaming (preferred): direct pipe to S3 multipart upload, no local disk usage
  • temp_dir (fallback): local write + upload with disk space validation using pg_table_size and configurable spare_percent
• aws_s3 — Server-side export via PostgreSQL aws_s3 extension (recommended for large datasets)

Lifecycle Events

• before-detach, after-detach, before-drop, after-drop

Configuration Scope

• Global hooks (applied to all partitions)
• Per-partition hooks (override global)

Production-Ready Features

• Retry with backoff — Fixed or exponential, configurable per hook
• Timeout — Per-hook execution timeout (default 300s)
• Failure behavior — abort (stop everything) or continue, with safe defaults (before-hooks cancel operation, after-hooks log and continue)
• Transaction isolation — Hooks execute outside PostgreSQL transactions, no locks held
• Template variables — {{.Schema}}, {{.Table}}, {{.ParentTable}}, {{.LowerBound}}, {{.UpperBound}}, {{.DatabaseName}}, {{.Hostname}}, etc.
• Credential propagation — Optional injection of PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD for shell hooks
• Dry-run mode — --dry-run flag to preview resolved hooks without execution
• Structured metrics — Hook execution duration, success/failure counters, retry counters in JSON log output

What This PR Does NOT Include

• No implementation code — this is a spec-only PR for review and discussion
• Design document and task breakdown will follow once requirements are validated

Example Configuration

hooks:
  after-detach:
    - name: archive-to-s3
      type: shell
      command: /usr/local/bin/archive-partition.sh
      args:
        - "{{.Schema}}.{{.Table}}"
        - "{{.LowerBound}}"
        - "{{.UpperBound}}"
      timeout: 10m
      on_failure: abort
      retry:
        attempts: 3
        backoff: exponential
        initial_delay: 5s
        max_delay: 60s
    - name: vacuum-parent
      type: postgresql
      config:
        sql: "VACUUM ANALYZE {{.Schema}}.{{.ParentTable}}"
      timeout: 5m

partitions:
  logs:
    schema: public
    table: logs
    partitionKey: created_at
    interval: daily
    retention: 30
    preProvisioned: 7
    cleanupPolicy: drop