distributor/docs/internal/notify.md

# Notification Internals

Audience: developers and LLM coding agents changing `internal/notify` or app notification wiring.

## Purpose

`internal/notify` defines the notification interface used by app orchestration after successful destination publication or replacement.

## Inputs And Outputs

Input is a context and notification event containing pipeline id, destination id, bundle id, bundle path, action, and output metadata. Output is an error that app orchestration can record as a destination-scoped failure.

## Boundaries

Only the no-op notifier exists in the repository. The package does not load config, send network requests, write destination state, publish files, or own run reporting.

## Config Fields Used

None.

## Adapters Used

None.

## State And Manifest Behavior

Notification events carry output metadata projected from publish plans. The package does not inspect source manifests or destination state.

## Skip And Resume Behavior

Dry-run, skipped destinations, failed destinations, and planning failures do not notify. The no-op notifier has no durable state.

## Failure Behavior

`notify.Noop` returns the context error when the context is canceled; otherwise it succeeds. If another notifier implementation returns an error, `internal/app` records the affected destination as failed and continues with remaining destinations where applicable.

## Tests To Inspect

- `internal/notify`
- `internal/app/run_notify.go`
- notification coverage in `internal/app/run_test.go`

## Architectural Invariants

- Notifications occur only after successful publish or replacement execution.
- Dry-run never notifies.
- Skipped and failed destinations never notify.
- The default app notifier is `notify.Noop`.