usecaseop

type Operation[C any, E usecase.DomainEvent] struct {
	// Name identifies the operation in diagnostics. Optional but recommended.
	Name string

	// Validate checks command shape: presence, format, length, patterns —
	// anything that does not require loading data. Return a validation-kind
	// [usecase.Error] on failure. Optional: leave nil when the command has
	// nothing to check, though most operations validate at least one field.
	Validate func(ctx context.Context, cmd C) error

	// Authorize is the resource-level access check (ownership, scope,
	// state-based permission). REQUIRED: set it to a real check, or to
	// [Public] to declare the operation intentionally open. Authorization
	// data (the authenticated principal) is carried on ctx — platform code
	// reads it with auth.FromContext(ctx). Run refuses to proceed if this is
	// nil (fail closed), and the uowseal analyzer flags any Operation literal
	// that omits it.
	Authorize func(ctx context.Context, cmd C) error

	// Execute runs invariant checks (loads aggregates, applies business
	// rules), builds the domain event, and returns the [Plan] describing the
	// change to commit. Returning a Plan is the ONLY way an operation can
	// reach the database; Run applies the Plan after Validate and Authorize
	// have passed. REQUIRED. Return a non-nil error (typically a
	// [usecase.Error]) to fail without committing.
	Execute func(ctx context.Context, cmd C, ec usecase.ExecutionContext) (Plan[E], error)
}

type Plan[E usecase.DomainEvent] interface {
	// Dispatch returns a copy of the plan that also writes these dispatch
	// jobs (framework write-path contract 7a): DISPATCH_JOB outbox rows in
	// the same transaction, after the plan's events and before its audit
	// row, in the order given (calls accumulate). The platform's outbox
	// processor delivers them to POST /api/dispatch-jobs/batch. The plan it
	// is called on is not changed.
	//
	// Run validates every job (outbox.DispatchJob.Validate: the 7a rules,
	// with their texts) before the transaction opens; an invalid job fails
	// the operation as INTERNAL DISPATCH_JOB_INVALID (Message = the rule's
	// text, Details["index"] = the job's position) and nothing is written.
	// Check values that come from the command in Validate, so the caller
	// gets a 400 instead. A job without a correlation id takes the plan's
	// event's (the returned event; a Sync plan's rollup). Nothing else is
	// inherited: the job's client is what it names (WithClientCode or
	// WithPlatformClientID; neither leaves it unscoped), and its eventId is
	// set only when the job sets it. The UnitOfWork's sink must implement
	// usecasepgx.DispatchJobSink (outboxpgx.Sink does); otherwise Run fails
	// with INTERNAL DISPATCH_JOB_UNSUPPORTED, again before any write.
	Dispatch(jobs ...outbox.DispatchJob) Plan[E]
	// contains filtered or unexported methods
}

type TxOperation[C any, R any] struct {
	// Name identifies the operation in diagnostics. Optional but recommended.
	Name string

	// Validate checks command shape. Pure, no DB. Optional.
	Validate func(ctx context.Context, cmd C) error

	// Authorize is the resource-level access check. REQUIRED — a real check,
	// or [Public]. RunTx fails closed if it is nil, and the uowseal analyzer
	// flags any TxOperation literal that omits it.
	Authorize func(ctx context.Context, cmd C) error

	// Execute performs the orchestrated writes inside the open transaction s
	// and returns the custom result on success, or an error to roll back.
	// Every aggregate change MUST go through a scoped commit helper
	// (usecasepgx.CommitScoped / EmitEventScoped / …) so it is written with
	// its domain event + audit log atomically. REQUIRED.
	Execute func(ctx context.Context, s *usecasepgx.TxScopedUnitOfWork, cmd C, ec usecase.ExecutionContext) (R, error)
}