Expected vs. unrecoverable.

/** One exception-shaped channel for both expected outcomes and defects. */
export function submitAllThrow(fault: Fault): Receipt {
	const expected = expectedFailureFor(fault);
	if (expected) throw new ReservationFailure(expected);
	if (fault === 'invariant') throw new InvariantViolation();
	return receipt();
}

// SubmitAllError is the closest Go equivalent to putting every failure in one
// channel: expected failures and defects both arrive as an error value.
func SubmitAllError(fault Fault) (Receipt, error) {
	switch fault {
	case Valid:
		return Receipt{ReservationID: "R-204", Seat: "12A"}, nil
	case SoldOut:
		return Receipt{}, ExpectedFailure{Kind: FailureSoldOut, Seat: "12A", Message: "Seat 12A has just been taken."}
	case Invalid:
		return Receipt{}, ExpectedFailure{Kind: FailureInvalid, Field: "seat", Message: "Choose a seat from this show."}
	case Invariant:
		return Receipt{}, InvariantViolation{Message: "The reservation ledger has an impossible state."}
	default:
		return Receipt{}, errors.New("unknown reservation fault")
	}
}

export type Fault = 'valid' | 'sold-out' | 'invalid' | 'invariant';
export type Policy = 'all-throw' | 'all-return' | 'split';

export type Receipt = Readonly<{
	reservationId: string;
	seat: string;
}>;

export type ExpectedFailure =
	| Readonly<{ kind: 'sold-out'; seat: string; message: string }>
	| Readonly<{ kind: 'invalid'; field: 'seat'; message: string }>;

export type Defect = Readonly<{
	kind: 'invariant';
	message: string;
}>;

export type Reported = ExpectedFailure | Defect;
export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

export type Observation = Readonly<{
	policy: Policy;
	fault: Fault;
	path: 'success' | 'expected' | 'defect' | 'caught-defect';
	action:
		| 'confirm reservation'
		| 'ask for another seat'
		| 'show validation'
		| 'stop and alert'
		| 'return generic error';
	detail: string;
}>;

function receipt(): Receipt {
	return { reservationId: 'R-204', seat: '12A' };
}

function expectedFailureFor(fault: Fault): ExpectedFailure | null {
	switch (fault) {
		case 'sold-out':
			return { kind: 'sold-out', seat: '12A', message: 'Seat 12A has just been taken.' };
		case 'invalid':
			return { kind: 'invalid', field: 'seat', message: 'Choose a seat from this show.' };
		case 'valid':
		case 'invariant':
			return null;
		default:
			throw new Error('unknown reservation fault');
	}
}

export class ReservationFailure extends Error {
	readonly failure: ExpectedFailure;

	constructor(failure: ExpectedFailure) {
		super(failure.message);
		this.name = 'ReservationFailure';
		this.failure = failure;
	}
}

export class InvariantViolation extends Error {
	constructor(message = 'The reservation ledger has an impossible state.') {
		super(message);
		this.name = 'InvariantViolation';
	}
}

/** One exception-shaped channel for both expected outcomes and defects. */
export function submitAllThrow(fault: Fault): Receipt {
	const expected = expectedFailureFor(fault);
	if (expected) throw new ReservationFailure(expected);
	if (fault === 'invariant') throw new InvariantViolation();
	return receipt();
}

export function submitAllReturn(fault: Fault): Result<Receipt, Reported> {
	const expected = expectedFailureFor(fault);
	if (expected) return { ok: false, error: expected };
	if (fault === 'invariant') {
		return {
			ok: false,
			error: { kind: 'invariant', message: 'The reservation ledger has an impossible state.' }
		};
	}
	return { ok: true, value: receipt() };
}

/** Expected outcomes stay in the normal result; a defect escapes to its boundary. */
export function submitSplit(fault: Fault): Result<Receipt, ExpectedFailure> {
	const expected = expectedFailureFor(fault);
	if (expected) return { ok: false, error: expected };
	if (fault === 'invariant') throw new InvariantViolation();
	return { ok: true, value: receipt() };
}

function expectedAction(failure: ExpectedFailure): Observation['action'] {
	return failure.kind === 'sold-out' ? 'ask for another seat' : 'show validation';
}

function expectedDetail(failure: ExpectedFailure): string {
	return failure.kind === 'sold-out'
		? `${failure.message} The caller can offer another seat.`
		: `${failure.message} The caller can correct the request.`;
}

function successObservation(policy: Policy, fault: Fault, value: Receipt): Observation {
	return {
		policy,
		fault,
		path: 'success',
		action: 'confirm reservation',
		detail: `${value.seat} is reserved as ${value.reservationId}.`
	};
}

export function observe(policy: Policy, fault: Fault): Observation {
	if (policy === 'all-throw') {
		try {
			return successObservation(policy, fault, submitAllThrow(fault));
		} catch (error) {
			if (error instanceof ReservationFailure) {
				return {
					policy,
					fault,
					path: 'expected',
					action: expectedAction(error.failure),
					detail: `${expectedDetail(error.failure)} It arrived through the same throw path as defects.`
				};
			}
			return {
				policy,
				fault,
				path: 'caught-defect',
				action: 'return generic error',
				detail:
					'The catch boundary caught an invariant violation beside expected failures; a broad catch can hide a bug as an ordinary server error.'
			};
		}
	}

	if (policy === 'all-return') {
		const result = submitAllReturn(fault);
		if (result.ok) return successObservation(policy, fault, result.value);
		if (result.error.kind === 'invariant') {
			return {
				policy,
				fault,
				path: 'defect',
				action: 'return generic error',
				detail:
					'The invariant violation is now ordinary result data. A caller can accidentally normalize a defect as a business outcome.'
			};
		}
		return {
			policy,
			fault,
			path: 'expected',
			action: expectedAction(result.error),
			detail: expectedDetail(result.error)
		};
	}

	try {
		const result = submitSplit(fault);
		if (result.ok) return successObservation(policy, fault, result.value);
		return {
			policy,
			fault,
			path: 'expected',
			action: expectedAction(result.error),
			detail: `${expectedDetail(result.error)} It is listed in the normal caller contract.`
		};
	} catch (error) {
		return {
			policy,
			fault,
			path: 'defect',
			action: 'stop and alert',
			detail:
				error instanceof InvariantViolation
					? 'The invariant violation escaped the normal result. A boundary can stop, alert, and choose its blast radius.'
					: 'An unknown failure escaped the normal result and should be handled by the owning boundary.'
		};
	}
}

export type BoundaryResponse = Readonly<{ status: 200 | 409 | 422 | 500; body: string }>;

/** The request handler owns containment: expected failures become answers, defects an alert. */
export function handleReservation(fault: Fault, alert: (error: unknown) => void): BoundaryResponse {
	try {
		const result = submitSplit(fault);
		if (result.ok) {
			return {
				status: 200,
				body: `Reserved ${result.value.seat} as ${result.value.reservationId}.`
			};
		}
		return { status: result.error.kind === 'sold-out' ? 409 : 422, body: result.error.message };
	} catch (error) {
		// Only the boundary catches the defect: it keeps the evidence and fails this request.
		alert(error);
		return { status: 500, body: 'Reservations are paused while we check the ledger.' };
	}
}

export function runExample() {
	return (['valid', 'sold-out', 'invariant'] as Fault[]).map((fault) => ({
		fault,
		allThrow: observe('all-throw', fault),
		allReturn: observe('all-return', fault),
		split: observe('split', fault)
	}));
}

console.log(JSON.stringify(runExample(), null, 2));

package main

import (
	"encoding/json"
	"errors"
	"fmt"
)

type Fault string

const (
	Valid     Fault = "valid"
	SoldOut   Fault = "sold-out"
	Invalid   Fault = "invalid"
	Invariant Fault = "invariant"
)

type Receipt struct {
	ReservationID string `json:"reservationId"`
	Seat          string `json:"seat"`
}

type FailureKind string

const (
	FailureSoldOut   FailureKind = "sold-out"
	FailureInvalid   FailureKind = "invalid"
	FailureInvariant FailureKind = "invariant"
)

type ExpectedFailure struct {
	Kind    FailureKind `json:"kind"`
	Seat    string      `json:"seat,omitempty"`
	Field   string      `json:"field,omitempty"`
	Message string      `json:"message"`
}

func (f ExpectedFailure) Error() string { return f.Message }

type InvariantViolation struct{ Message string }

func (e InvariantViolation) Error() string { return e.Message }

type Reported struct {
	Expected  *ExpectedFailure
	Invariant *InvariantViolation
}

// SubmitAllError is the closest Go equivalent to putting every failure in one
// channel: expected failures and defects both arrive as an error value.
func SubmitAllError(fault Fault) (Receipt, error) {
	switch fault {
	case Valid:
		return Receipt{ReservationID: "R-204", Seat: "12A"}, nil
	case SoldOut:
		return Receipt{}, ExpectedFailure{Kind: FailureSoldOut, Seat: "12A", Message: "Seat 12A has just been taken."}
	case Invalid:
		return Receipt{}, ExpectedFailure{Kind: FailureInvalid, Field: "seat", Message: "Choose a seat from this show."}
	case Invariant:
		return Receipt{}, InvariantViolation{Message: "The reservation ledger has an impossible state."}
	default:
		return Receipt{}, errors.New("unknown reservation fault")
	}
}


type Result[T any, E any] struct {
	Value T
	Error *E
}

// SubmitAllReturn keeps even an invariant violation in ordinary result data.
func SubmitAllReturn(fault Fault) Result[Receipt, Reported] {
	value, err := SubmitAllError(fault)
	if err == nil {
		return Result[Receipt, Reported]{Value: value}
	}
	var expected ExpectedFailure
	if errors.As(err, &expected) {
		return Result[Receipt, Reported]{Error: &Reported{Expected: &expected}}
	}
	var invariant InvariantViolation
	if errors.As(err, &invariant) {
		return Result[Receipt, Reported]{Error: &Reported{Invariant: &invariant}}
	}
	return Result[Receipt, Reported]{Error: &Reported{Invariant: &InvariantViolation{Message: err.Error()}}}
}


// SubmitSplit returns expected failures through Go's normal error protocol.
// An impossible ledger state panics so the owning boundary cannot mistake it
// for a seat the user can choose differently.
func SubmitSplit(fault Fault) (Receipt, error) {
	if fault == Invariant {
		panic(InvariantViolation{Message: "The reservation ledger has an impossible state."})
	}
	return SubmitAllError(fault)
}


type Response struct {
	Status int    `json:"status"`
	Body   string `json:"body"`
}

// HandleReservation is the boundary that owns containment: expected failures
// become answers, and a defect is recovered here, alerted, and fails this request.
func HandleReservation(fault Fault, alert func(any)) (response Response) {
	defer func() {
		if recovered := recover(); recovered != nil {
			alert(recovered)
			response = Response{Status: 500, Body: "Reservations are paused while we check the ledger."}
		}
	}()
	receipt, err := SubmitSplit(fault)
	var expected ExpectedFailure
	switch {
	case err == nil:
		return Response{Status: 200, Body: fmt.Sprintf("Reserved %s as %s.", receipt.Seat, receipt.ReservationID)}
	case errors.As(err, &expected) && expected.Kind == FailureSoldOut:
		return Response{Status: 409, Body: expected.Message}
	case errors.As(err, &expected):
		return Response{Status: 422, Body: expected.Message}
	default:
		alert(err)
		return Response{Status: 500, Body: "Reservations are paused while we check the ledger."}
	}
}


func Example() map[string]any {
	_, expected := SubmitSplit(SoldOut)
	allReturn := SubmitAllReturn(Invariant)
	defectEscaped := recoverInvariant()
	return map[string]any{
		"expectedKind":     expected.(ExpectedFailure).Kind,
		"allReturnDefect":  allReturn.Error.Invariant != nil,
		"splitPanics":      defectEscaped,
		"validReservation": mustReserve(Valid).ReservationID,
		"boundaryStatus":   HandleReservation(Invariant, func(any) {}).Status,
	}
}

func recoverInvariant() (deferred bool) {
	defer func() {
		if recover() != nil {
			deferred = true
		}
	}()
	_, _ = SubmitSplit(Invariant)
	return false
}

func mustReserve(fault Fault) Receipt {
	receipt, err := SubmitSplit(fault)
	if err != nil {
		panic(err)
	}
	return receipt
}


func main() {
	encoded, err := json.MarshalIndent(Example(), "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(encoded))
}