Correct sdp-expectation-notifications docs from the 2026-08-22 egress and destination verification (v1.12.2)

[vmariiechko]

Related Issue

Closes #

Summary

Documentation-only pass on the sdp-expectation-notifications asset, driven by a live verification session (2026-08-22, Free Edition serverless SDP, CLI v0.297.2, non-development-mode target). Every change is text: no behavior, no defaults, no code. The shipped throttle (throttle_seconds: 3600), the commented retrigger_seconds, the daily cron with its matching INTERVAL 1 DAY, the failed_records > 0 threshold, and max_allowable_consecutive_failures=None are all untouched.

The headline is a correction of a claim this repo shipped in v1.12.1: a Slack or MS Teams notification destination does not need an OAuth token, channel id, App ID, Auth Secret, Channel URL, or Tenant ID for an alert. Those fields are marked (optional) on the Add-destination form and scoped by the form's own section heading to dashboard subscriptions, a different Databricks feature. For an alert, the webhook URL is the whole requirement, confirmed independently of the form by the stored API config of a Slack destination that then delivered five messages (url_set: true, oauth_token_set: false, channel_id_set: false). The v1.12.1 wording came from a documentation-retrieval summary treated as source text.

The v1.12.1 changelog entry is deliberately not rewritten. Its text stands and carries a short bracketed pointer to the correction, so released history is not edited to hide the error.

Changes

• Destination config corrected in assets/sdp-expectation-notifications/README.md, the backstop alert resource comment, and the skill's adapt-the-pattern.md. What survives unchanged: destinations serve Databricks SQL and jobs only and never the event hook; a destination wraps a webhook rather than replacing one; EMAIL is the only type taking plain addresses; minting a Slack incoming webhook is still a Slack app install; the non-deduplicated double-send when a destination and a user_email point at the same address.
• "A hook cannot send email anyway" re-scoped. There is no Databricks-native email surface inside a hook, but the shipped hook reaches arbitrary HTTPS (two unrelated third-party collectors, HTTP 200, bare request with no proxy or policy header). Two limits travel with it everywhere it appears: the measurement had no egress controls configured, so a governed workspace's network policy is what decides; and the shipped requests.post passes no headers, so an authenticated email API needs the hook edited first.
• generic channel format is live-tested (all six fields verbatim, counts as JSON numbers). teams remains documented and not live-tested.
• Empty result state: Error explained in the three places that invite a sweep-query edit, so COALESCE(SUM(...), 0) reads as load-bearing rather than cosmetic. Editing the query into a zero-row shape silently converts the backstop into a per-evaluation ERROR emailer.
• Measured numbers replace asserted ones: 116 ms per POST on success, 3 ms to fail on an unresolvable name (instrumented), a verbatim WEBHOOK_DELIVERY_FAILED instance (named as requests.exceptions.ConnectionError, since type(e).__name__ renders it bare and collides with the builtin), and the History panel's Notified destinations column as product-shown evidence for one notification per state transition.
• New material: the three message shapes one violation produces (hook payload with counts, email with the evaluated metric plus a five-run history, destination message with a title and two links and no data), the email subject format, and the trap that Last 5 runs lists evaluations rather than notifications.
• Skill gains the CLI delete behavior: delete is effective immediately, list is eventually consistent, so verify with get; a redundant delete errors rather than being idempotent. The existing create-quirk callout is unchanged and still reproduces on CLI v0.297.2.
• Workspace admin for destinations stated as documented, not stress-tested (the verification account owns that workspace, so no blocked case was exercised).
• Stale comment fixed in event_log_queries.sql.tmpl: its hook_progress note still claimed enable/disable state only, which v1.12.0 corrected everywhere else, so the asset shipped a comment contradicting its own README.

Change Area

• Core template (template/, schema, helpers)
• Asset Library (assets/<name>/)
• Both
• Docs / tests / infrastructure only

Configuration Axes Affected

• Environment setup (full/minimal, dev environment)
• Compute type (classic/serverless/both)
• Permissions / RBAC
• CI/CD pipelines (Azure DevOps, GitHub Actions, GitLab)
• Cloud provider (Azure/AWS/GCP)
• Unity Catalog / schemas
• Template schema (databricks_template_schema.json)
• Template helpers (library/helpers.tmpl)
• Asset Library (new asset, asset schema, or framework changes)
• None of the above (docs, tests, infrastructure only)

Testing

• All tests pass (pytest tests/ -V): 2446 passed, 163 skipped in 236s
• Manual template generation tested (databricks bundle init assets/sdp-expectation-notifications --config-file tests/configs/assets/sdp_expectation_notifications.json --output-dir <dir>): all eight files render, no stray {{, alert YAML parses with defaults intact
• New tests added for new functionality (if applicable) — not applicable, docs only

Asset Changes (if applicable)

• Asset installs standalone via databricks bundle init assets/sdp-expectation-notifications --output-dir <dir>
• Asset is self-contained (no references to library/helpers.tmpl or other assets)
• tests/configs/assets/sdp_expectation_notifications.json present (unchanged)
• Asset appears in ASSETS.md catalog (row unchanged: it describes capability, which this pass does not alter)

Release (if this PR cuts a release)

• CHANGELOG.md finalized: [Unreleased] renamed to [1.12.2] - 2026-08-23, fresh empty [Unreleased] added above
• Both version markers bumped to 1.12.2 (pyproject.toml and template/{{.project_name}}/bundle_init_config.json.tmpl)
• Version guard test passes (tests/test_release_metadata.py)

Checklist

• Go template syntax is valid (no unclosed {{ }} blocks)
• No .tmpl files appear in generated output
• Generated YAML files are valid
• Documentation updated (if behavior changed) — behavior did not change; this PR is the documentation update