// Copyright (C) 2026 Dcntrlized
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

package actions

import (
	"context"
	"errors"

	"github.com/google/uuid"
)

// completeAlertDelivery is the decision point for the second half of the
// delivery design: "once every client is removed for an alarm, the alarm is then
// deleted with whichever cascade deletions are relevant".
//
// It is DELIBERATELY UNWIRED — nothing calls it. That sentence has two readings
// and they are different products, so the user has been asked which one is meant:
//
//	(a) delete the ALERT. The definition, both tokens, the subscriptions and the
//	    event history go with it (ON DELETE CASCADE). An alert becomes a
//	    one-shot event: once every device has acknowledged, it cannot be
//	    triggered again and the admin token becomes dead.
//	(b) retire only the DELIVERY record (and/or the event). The alert survives,
//	    stays armed, and can be triggered again later; only the ledger bookkeeping
//	    about this alarm is completed.
//
// Implementing either now would delete or preserve data on a reading nobody
// confirmed, so this function reports that the decision is pending. When the
// answer arrives it gets implemented in exactly one place and called from the
// paths that observe the last outstanding delivery (the alarmStatus check-in and
// the WebSocket ack), where "every client has been told" is decided atomically
// from the ledger rather than from a client's claim.
func completeAlertDelivery(ctx context.Context, alertID uuid.UUID) error {
	_ = ctx
	_ = alertID
	return errors.New("completeAlertDelivery: pending user decision between (a) deleting the alert as a one-shot and (b) retiring only the delivery record")
}