work

type ActivityJournal struct {
	Entries activityrepo.Journal
	IDs     clock.IDGenerator
}

type AddComment struct {
	Writer CommentWriter
}

type AddCommentCommand struct {
	// ID is the identifier the client minted, or empty for one the server mints - a device
	// commenting offline assigns its own (offline-sync.md §3.2), CreateWorkItemCommand's rule.
	ID     shared.ID
	ItemID shared.ID
	// SystemCode and SystemParams make the comment one the server files on the author's behalf
	// (offline-sync.md §5). Not declared as inputs: nobody asks for a system comment over a
	// channel, and FileDisplaced is the one caller.
	SystemCode   string
	SystemParams map[string]string
	// ParentCommentID is the comment being replied to, empty for a top-level comment.
	ParentCommentID shared.ID
	Body            string
}

type AddLabel struct {
	Writer ItemLabelWriter
}

type AddMember struct {
	Writer ItemMemberWriter
}

type AiProviders interface {
	For(ctx context.Context, actor appshared.ActorContext) (aiprovider.Provider, error)
}

type AiTranslate struct {
	// Reader is the ordinary read of the entry: the permission question and the existence
	// question at once, asked before any provider is called.
	Reader    GetWorkItem
	Providers AiProviders
	Prompts   aiprovider.Prompts
	Audit     audit.Sink
	// UnitOfWork opens the transaction the audit entry is written in. The asking use cases
	// record theirs inside one; this one recorded it outside and met
	// `postgres.no_transaction_in_context` the first time a person asked.
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	// Timeout bounds the provider call. Zero takes the default above.
	Timeout time.Duration
	// Kept is whose content stays out of AI (data-protection.md §4.1). Nil keeps nobody out.
	Kept KeptOutReader
}

type Anchored interface {
	ReachInto(
		ctx context.Context, actor appshared.ActorContext, request access.Request,
		containerID shared.ID,
	) (access.Reach, error)
}

type ArchiveContainer struct {
	Writer ContainerWriter
}

type ArchiveContainerCommand struct {
	ContainerID     shared.ID
	ExpectedVersion int
}

type ArchiveWorkItem struct {
	Lifecycle LifecycleWriter
}

type AssignWorkItem struct {
	Assignment AssignmentWriter
}

type AssignmentCommand struct {
	ItemID    shared.ID
	AccountID shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read none
	// and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type AssignmentWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	Visibility Visibility
	// Accounts answers whether a rule is about to put a restricted person on the entry: no rule
	// does (data-protection.md §4). Nil restricts nobody.
	Accounts   RestrictedAccounts
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
}

type AttachMedia struct {
	Writer ItemAttachmentWriter
}

type AttachmentCommand struct {
	ItemID  shared.ID
	MediaID shared.ID
}

type Authorizer interface {
	Authorize(ctx context.Context, actor appshared.ActorContext, request access.Request) error
}

type AutoAssignOutcome struct {
	Assigned bool
	Strategy domain.AutoAssignStrategy
	// Code is the stable reason when nobody was assigned, empty otherwise.
	Code string
}

type AutoAssignWorkItem struct {
	Assignment AssignmentWriter
	Policies   repository.AutoAssignPolicies
	Groups     identityrepo.Groups
	// Accounts answers which candidates are under a restriction of processing. Art. 18 is a
	// technical state, and an automatic decision about somebody is exactly the processing it
	// stops (data-protection.md §4) - so the pool is narrowed here rather than the draw
	// being allowed to land on them.
	Accounts identityrepo.Accounts
	Random   clock.RandomSource
}

type BucketDeletion struct {
	BucketID shared.ID
	// TargetBucketID is the column the entries moved to. Zero when this was the last column on the
	// board, in which case the entries now carry none - the state the collection was in before
	// anybody made a board.
	TargetBucketID shared.ID
	MovedItems     int
}

type BucketInserter interface {
	Insert(ctx context.Context, bucket domain.Bucket) error
}

type BucketWriter struct {
	Buckets    repository.Buckets
	Containers repository.Containers
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type BulkOperation struct {
	Op     string
	ItemID shared.ID
	// Payload is what the single-entry operation takes in its body, by the field names it takes
	// there. It is not inspected here: the catalogue checks it against the operation's own
	// declaration, so a field the operation does not know comes back named rather than ignored.
	Payload map[string]any
}

type BulkOutcome struct {
	Index  int
	Op     string
	Output usecase.Output
	Err    *shared.Error
}

type BulkResult struct {
	Outcomes []BulkOutcome
	Applied  int
	Failed   int
}

type BulkUpdateWorkItems struct {
	Catalogue  Catalogue
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type BulkUpdateWorkItemsCommand struct {
	// Atomic makes the bulk all or nothing. Without it, the operations that succeeded stay applied.
	Atomic     bool
	Operations []BulkOperation
}

type CalendarFeedWriter struct {
	Feeds      feedrepo.CalendarFeeds
	Views      viewrepo.SavedViews
	Containers repository.Containers
	// Permits answers the view's visibility without writing a denial: a view the caller cannot
	// see is not found, and a DENIED entry per invisible bookmark makes the trail unreadable
	// (T-04, the reasoning GetSavedView already applies).
	Permits    Permitting
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	// Entropy is where the token's secret half comes from. A port, so that production draws from
	// crypto/rand and a test can fix the credential it asserts on (rule 4).
	Entropy clock.Entropy
}

type Catalogue interface {
	Invoke(
		ctx context.Context, name string, actor appshared.ActorContext, in usecase.Input,
	) (usecase.Output, error)
}

type ChangeCommentCommand struct {
	ItemID    shared.ID
	CommentID shared.ID
	Body      string
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read
	// none and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type ChangePreset struct{ Desk PresetDesk }

type ChangePresetCommand struct {
	PresetID        shared.ID
	Name            string
	ContainerID     shared.ID
	Settings        domain.StructureValues
	ExpectedVersion int
}

type ChangeReminderCommand struct {
	ItemID     shared.ID
	ReminderID shared.ID
	Patch      domain.ReminderPatch
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read
	// none and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type ChangeTemplateCommand struct {
	TemplateID shared.ID
	Patch      domain.TemplatePatch
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read
	// none and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type ClearCover struct {
	Cover CoverWriter
}

type ClearDueDate struct {
	Due DueDateWriter
}

type CloseStarter struct{ Starter Starter }

type CommentWriter struct {
	Comments   repository.Comments
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	// Moderation answers the one question the permission cannot: which role the actor holds.
	// Only the edit and the deletion consult it - "only the author or an administrator may
	// change a comment" is their rule, and it is named where it is enforced (Authorization.go).
	Moderation Moderation
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Text brings the body to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
	// Holds are the legal holds a deletion is judged against: under one, the deleted comment keeps
	// its text until the retention pass clears it (data-retention.md §4). Only the deletion reads
	// them.
	Holds lifecyclerepo.LegalHolds
}

type CompleteWorkItem struct {
	Completion CompletionWriter
}

type CompletionCommand struct {
	ItemID shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read none and
	// accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type CompletionWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	// Jobs is where an ON_COMPLETION series asks for its next occurrence. The completion is what
	// seeds it, which is SY-8's server half: creation is bound to the status transition rather
	// than to the event, so two devices completing the same entry produce one transition and one
	// follow-up (offline-sync.md §8).
	Jobs       queue.Queue
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Structure answers the completion in force: the collection's own, else its hub's, else the
	// workspace's (domain-model.md §2). A build without it reads the collection's own alone.
	Structure StructureResolver
	// Milestones records the collection, and its hub, a completion left with nothing open
	// (UC-WRK-29 check 4). A build without it records none.
	Milestones repository.Milestones
}

type ContainerLifecycleCommand struct {
	ContainerID shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read none
	// and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type ContainerWriter struct {
	Containers repository.Containers
	// Policies is where the auto_assign key of the policies document is stored: its own row, so
	// the rotation's state can be locked (see work.AutoAssignPolicy). Only UpdateContainerPolicies
	// writes it, for the reason only TrashContainer uses Queue - the dependency set is shared, the
	// verbs are not.
	Policies   repository.AutoAssignPolicies
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Queue is where a deletion asks for the tenant's cleanup to be scheduled. Only TrashContainer
	// uses it; the reasoning is at LifecycleWriter.Queue.
	Queue queue.Queue
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type CoverCommand struct {
	ItemID     shared.ID
	Kind       domain.CoverKind
	ColorToken string
	MediaID    shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read
	// none and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type CoverWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Media      MediaReferences
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
}

type CreateBucket struct {
	Buckets    repository.Buckets
	Containers repository.Containers
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type CreateBucketCommand struct {
	CollectionID shared.ID
	Name         string

	// WipLimit is a number of which zero means "no limit", exactly as the empty string means "not
	// set" for the text fields (domain.BucketAttributes).
	WipLimit     int
	IsDoneBucket bool
	ColorToken   string
	// BeforeBucketID is the column the new one goes to the left of. Empty means the right hand end,
	// which is where a board grows unless somebody says otherwise.
	BeforeBucketID shared.ID
}

type CreateCalendarFeed struct{ Writer CalendarFeedWriter }

type CreateContainer struct {
	Containers repository.Containers
	Authorizer Authorizer
	// OwnHubs answers who may make a private hub; Grants makes its creator its owner. Both are
	// needed only for a private hub, and a build without them refuses one rather than making a hub
	// nobody holds.
	OwnHubs OwnHubs
	Grants  identityrepository.MembershipGrants
	// PrivateHubs is the workspace's switch, read only for a private hub.
	PrivateHubs PrivateHubsRule
	Events      outbox.Events
	Changes     changelog.ChangeLog
	Audit       audit.Sink
	UnitOfWork  persistence.UnitOfWork
	Clock       clock.Clock
	IDs         clock.IDGenerator
	HLC         clock.HLCSource
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
	// Structure resolves and seeds the new container's structure (domain-model.md §2). A build
	// without it creates containers with no layer of their own and answers no structure.
	Structure StructureResolver
	// Buckets, Workspaces and Renderer give a new collection the columns its board starts with
	// (domain.StartingColumns), named in the workspace's language: the names are content once
	// created, so the backend renders them where they are created, as provisioning does. A build
	// without them creates collections with no column.
	Buckets    BucketInserter
	Workspaces WorkspaceReader
	Renderer   i18n.Renderer
}

type CreateContainerCommand struct {
	Type     domain.ContainerType
	ParentID shared.ID
	Name     string

	Description string
	Icon        string
	ColorToken  string

	// Private makes a new hub private, its creator its owner (ADR-0073 §2).
	Private bool

	// Preset is the preset the new container starts from, empty for none: a hub then takes the
	// workspace's default, a collection follows its hub (domain-model.md §2).
	Preset domain.PresetKey
}

type CreateLabel struct {
	Labels     repository.Labels
	Containers repository.Containers
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type CreateLabelCommand struct {
	CollectionID shared.ID
	Name         string
	ColorToken   string
	Description  string
}

type CreateReminder struct {
	Writer ReminderWriter
}

type CreateReminderCommand struct {
	ItemID     shared.ID
	OffsetSpec string
	// Channels as the caller named them, and empty for the default. Strings rather than the
	// domain's type, because an unknown channel is a validation answer rather than a parse error
	// (ADR-0011): the domain names the value it refused.
	Channels   []string
	Recipients []shared.ID
}

type CreateSavedView struct {
	Views      viewrepo.SavedViews
	Containers repository.Containers
	Authorizer Authorizer
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	// Text brings the name to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type CreateSavedViewCommand struct {
	ScopeType view.ViewScope
	ScopeID   shared.ID
	Name      string
	Layout    string
	Query     map[string]any
	Grouping  map[string]any
	// VisibleFields distinguishes nil - not sent, stored empty - from an empty list a client
	// chose, though the two store alike.
	VisibleFields []string
	Sharing       view.Sharing
}

type CreateTemplate struct {
	Writer TemplateWriter
}

type CreateTemplateCommand struct {
	Spec domain.TemplateSpec
}

type CreateWorkItem struct {
	Items      repository.Items
	Quota      ItemQuota
	Buckets    repository.Buckets
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	Ownership  Ownership
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// AutoAssign is the machinery behind :auto-assign, reused whole: the create path is
	// its second caller - the policy that applies itself to what a collection creates, and the
	// explicit `auto_assign` ask - and its Assignment writer is also how an explicit assignee is
	// written, with the same guards and the same four records as :assign.
	AutoAssign AutoAssignWorkItem
	// DueDates is the writer the declared due fields dispatch into, reused whole for the same
	// reason.
	DueDates DueDateWriter
	// Labels and Members are the writers the two set fields dispatch into, reused whole: a label
	// put on at creation is the same OR-set element, the same events and the same audit entry as
	// one put on a moment later.
	Labels  ItemLabelWriter
	Members ItemMemberWriter
	// Covers is the writer the declared cover dispatches into, reused whole for the same reason:
	// one place decides what a cover may be, what an image has to be before it may become one, and
	// what the change owes.
	Covers CoverWriter
	// CustomFields is the use case the declared values dispatch into, one key at a time. Whole
	// rather than a slice of it, because what judges a value is the definition in force for the
	// entry's collection, and that resolution is the thing that may not be duplicated.
	CustomFields SetCustomField
	// Text brings the title and the notes to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
	// Structure resolves the collection's structure in force, which decides whether it offers an
	// amount (ensureAmountOffered).
	Structure StructureResolver
	// Flow refuses an entry created into a column past the first without its required fields,
	// where the collection applies that (FlowGate).
	Flow FlowGate
}

type CreateWorkItemCommand struct {
	// ID is the identifier the client minted, or empty for one the server mints. A device
	// creating an entry offline assigns its own UUIDv7 so that the entry has its final identity
	// at once and a repeated push is idempotent (offline-sync.md §3.2, §9); through the API a
	// caller may do the same, and one that does is held to the same rule.
	ID   shared.ID
	Type domain.ItemType
	// CollectionID may be left empty when ParentID is given: an item's collection is the one its
	// parent is in, and making a client repeat it is making it possible to contradict.
	CollectionID shared.ID
	ParentID     shared.ID
	Title        string
	Notes        string
	// Amount is how much of it, empty for none: only where the collection's structure in force
	// carries AMOUNT for the type (ensureAmountOffered).
	Amount string
	// BucketID is the column of the collection's board the entry starts in, empty for none.
	BucketID shared.ID
	// AssigneeID creates the entry already on somebody: the same checks and the same
	// records as :assign, in the same transaction as the creation. Empty for nobody.
	AssigneeID shared.ID
	// AutoAssign asks the collection's assignment policy to hand the new entry out, explicitly -
	// an enabled policy applies itself without this flag. Contradicts AssigneeID and is refused
	// beside it: a named person and a policy cannot both decide one scalar.
	AutoAssign bool
	// ContentLanguage is the language the entry is written in, and empty takes the creator's
	// locale (i18n-l10n.md §5). What it decides is the text search configuration the entry is
	// indexed under, which is the whole of why it is worth carrying (ADR-0034).
	ContentLanguage string
	// StartAt is when the work begins, nil for no start - the create's own field, a plain
	// attribute beside the notes.
	StartAt *time.Time
	// CalendarUID is the UID a calendar client chose for the entry it is making, and empty for
	// every other creation (offline-sync.md §4.2). The tree answers the entry at that address
	// from then on; nothing else reads it, and nothing ever changes it.
	CalendarUID string
	// Due creates the entry already carrying a due date: the same validation and the same
	// records as PUT /items/{id}/due, in the same transaction as the creation - the way an
	// explicit assignee reuses the :assign machinery. Nil for none.
	Due *domain.DueDate
	// LabelIDs creates the entry already carrying labels of its collection, and MemberIDs already
	// on a member list. Each goes through the writer that owns the set, with the same guards and
	// the same four records as the standalone route, in the same transaction as the creation. Empty
	// for none.
	LabelIDs  []shared.ID
	MemberIDs []shared.ID
	// CustomFields creates the entry already carrying values, each judged against the definition in
	// force for its collection and each written as its own change - the per-key merge rule the
	// standalone route exists to keep. Nil for none.
	CustomFields map[string]any
	// Cover creates the entry already covered: a colour token or an image, with the rules and the
	// records of `PUT /items/{id}/cover`, in the same transaction as the creation. Nil for an entry
	// with no cover. `ItemID` is filled at the dispatch - the caller of a create does not know the
	// identifier yet, which is half of why this field had to be written here rather than left to a
	// second request.
	Cover *CoverCommand
	// BeforeItemID is the sibling the new entry is ranked in front of, and empty puts it at the
	// end. It is the move's own anchor, answered by the same neighbours query and the same
	// refusal - a sibling that is not at this level is `items.before_item_not_in_level` rather
	// than a silent append, because a client that asked for a position and got the end of the list
	// has been ignored.
	BeforeItemID shared.ID
}

type CustomFieldWriter struct {
	Fields     repository.CustomFields
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	Authorizer Authorizer
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	// Text brings the options and a TEXT value to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type DefineCustomField struct {
	Fields     repository.CustomFields
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	Authorizer Authorizer
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	// Text brings the options and a TEXT value to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type DefineCustomFieldCommand struct {
	// CollectionID is the collection the field belongs to, zero for the whole workspace.
	CollectionID shared.ID
	Key          string
	Kind         domain.CustomFieldKind
	Options      []string
	IsRequired   bool
	// AppliesTo are the item types that carry the field. Empty means the column's default, which
	// is a task alone.
	AppliesTo []domain.ItemType
}

type DeleteBucket struct {
	Writer BucketWriter
}

type DeleteBucketCommand struct {
	BucketID shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read none
	// and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type DeleteComment struct {
	Writer CommentWriter
}

type DeleteCustomField struct {
	Writer CustomFieldWriter
}

type DeleteCustomFieldCommand struct {
	FieldID         shared.ID
	ExpectedVersion int
}

type DeleteLabel struct {
	Writer LabelWriter
}

type DeleteLabelCommand struct {
	LabelID         shared.ID
	ExpectedVersion int
}

type DeleteReminder struct {
	Writer ReminderWriter
}

type DeleteSavedView struct {
	Writer SavedViewWriter
}

type DeleteTemplate struct {
	Writer TemplateWriter
}

type DetachMedia struct {
	Writer ItemAttachmentWriter
}

type DueDateCommand struct {
	ItemID shared.ID
	Due    *domain.DueDate
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read
	// none and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type DueDateWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate EntryGate
	// Reminders is here because a due date that moves takes the relative reminders with it: the
	// reminder lives on the same entry, so its moment is recomputed in the same transaction rather
	// than by a job that would leave the two disagreeing until it ran.
	Reminders repository.Reminders
	// Jobs is where the tenant's next wake-up is asked for, in the transaction that moved the
	// date: a reminder that came forward with it needs the schedule to come forward too.
	Jobs       queue.Queue
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
}

type DuplicateResult struct {
	Item domain.WorkItem
	// Copied is the size of the copy, the entry itself included.
	Copied int
	// DroppedReferences is what could not be carried over, from every entry that lost something.
	// Empty rather than nil: a client that iterates the losses should not have to nil-check the
	// field.
	DroppedReferences []domain.DroppedReference
}

type DuplicateWorkItem struct {
	Quota       ItemQuota
	Items       repository.Items
	ItemLabels  repository.ItemLabels
	ItemMembers repository.ItemMembers
	Labels      repository.Labels
	Buckets     repository.Buckets
	Fields      repository.CustomFields
	Containers  repository.Containers
	Attachments mediarepo.Attachments
	Media       MediaReferences
	Profiles    metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	// Ownership is the same question the create path asks: does the role the actor holds write only
	// what is assigned to them. A copy is a create, so it has to ask it too.
	Ownership  Ownership
	Visibility Visibility
	// Restrictions answers whether a rule is copying an entry onto a restricted person: the copy is
	// made unassigned and the drop reported (data-protection.md §4). Nil restricts nobody.
	Restrictions RestrictedAccounts
	Events       outbox.Events
	Changes      changelog.ChangeLog
	Audit        audit.Sink
	Activity     ActivityJournal
	UnitOfWork   persistence.UnitOfWork
	Clock        clock.Clock
	IDs          clock.IDGenerator
	HLC          clock.HLCSource
	// Text is what a copied TEXT value is checked with; a value written before the form was
	// applied is composed by the copy, exactly as its next edit would compose it.
	Text text.Normalizer
}

type DuplicateWorkItemCommand struct {
	ItemID shared.ID
	// IncludeSubtree copies everything below the entry with it. Without it the entry is copied
	// alone and its children stay where they are.
	IncludeSubtree bool
	// TargetParentID is the entry the copy sits under, meaningful only together with ParentGiven:
	// the zero value is both "the top level" and "not asked for", and those are different requests.
	TargetParentID shared.ID
	ParentGiven    bool
	// TargetCollectionID may be omitted when a parent is given: an entry's collection is the one
	// its parent is in, and making a client repeat it is making it possible to contradict.
	TargetCollectionID shared.ID
	// Title is the copy's title, and empty keeps the original's. A server that invented "Copy of …"
	// would be writing display text (ADR-0011).
	Title string
}

type EditComment struct {
	Writer CommentWriter
}

type EmbedItems struct {
	Embeddings repository.Embeddings
	Providers  AiProviders
	Semantic   SemanticSearch
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	// BatchSize bounds one pass. Zero takes the default below.
	BatchSize int
	// Kept is whose content stays out of AI: their entries are not embedded, and their vectors
	// are forgotten by the pass (data-protection.md §4.1). Nil keeps nobody out.
	Kept KeptOutReader
}

type EmbedOutcome struct {
	// Embedded is how many vectors were written.
	Embedded int
	// Exhausted is true when the pass filled its batch, which means there is probably more owed.
	Exhausted bool
}

type EmbeddingQueue interface {
	Enqueue(ctx context.Context, request queue.Request) (shared.ID, error)
}

type EmergencyNotices interface {
	EmergencyAccessOpened(ctx context.Context, access domain.EmergencyAccess, members []shared.ID) error
}

type EntryGate struct {
	Structure StructureResolver
	Types     repository.ItemTypes
}

type ExportItems struct {
	Query      QueryItems
	ItemLabels repository.ItemLabels
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type ExportView struct {
	Views      viewrepo.SavedViews
	Containers repository.Containers
	Permits    Permitting
	// Query is the same use case an ad-hoc query goes through. Held rather than reimplemented:
	// an export that selected rows its own way would be a second answer to "what does this view
	// contain", and the two would drift.
	Query      QueryItems
	ItemLabels repository.ItemLabels
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type ExportedItems struct {
	Items       []domain.WorkItem
	Labels      map[shared.ID][]shared.ID
	Truncated   bool
	GeneratedAt time.Time
}

type ExportedView struct {
	View  view.SavedView
	Items []domain.WorkItem
	// Labels is the label identifiers per entry, so that a rendering that shows them does not
	// have to ask again.
	Labels map[shared.ID][]shared.ID
	// Truncated says the result reached view.MaxExportRows and there was more behind it.
	Truncated bool
	// TimeZone is the zone the selection ran under - the caller's own, or the feed owner's. It
	// decides nothing about which rows came back and everything about which day an all-day entry
	// falls on when one is rendered (i18n-l10n.md §4).
	TimeZone    string
	GeneratedAt time.Time
}

type FigureReader struct {
	Figures  repository.Figures
	Clock    clock.Clock
	Profiles metarepo.CapabilityProfiles
}

type FireReminders struct {
	Reminders repository.Reminders
	Items     repository.Items
	// Schedule is the scan the two announcements run on: the same repository as Items, under the
	// narrow interface that says what this pass may do with it.
	Schedule    repository.DueAnnouncements
	Containers  repository.Containers
	ItemMembers repository.ItemMembers
	// Visibility answers whether a named recipient can still see the entry. A membership revoked
	// since the reminder was written is not survived by a reminder that remembers better days -
	// the same question the write asked, asked again at the moment it matters.
	Visibility Visibility
	Notifier   ReminderNotifier
	// Events is where the two scheduling announcements go: item.due_soon and item.overdue are
	// facts about a deadline rather than messages to a person, and what reacts to them is
	// automation (domain-model.md §4).
	Events outbox.Events
	// Changes is how a device learns that a reminder fired. offline-sync.md §8 requires a client
	// to reconcile the local notification it scheduled, and it can only do that if the server's
	// decision reaches it - so the state the pass writes travels like any other field.
	Changes changelog.ChangeLog
	Clock   clock.Clock
	IDs     clock.IDGenerator
	HLC     clock.HLCSource
	Signals ReminderSignals
	// BatchSize bounds one pass. A pass is one transaction, and a transaction that fired ten
	// thousand reminders would hold its locks for as long as that took.
	BatchSize int
}

type FlowGate struct {
	Buckets repository.Buckets
	Fields  repository.CustomFields
}

type GetContainer struct {
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
	// Structure resolves the container's structure in force for the answer (domain-model.md §2).
	Structure StructureResolver
	// Figures counts what counts in a collection, after the structure (UC-WRK-29).
	Figures FigureReader
	// Milestones answers when the container was last finished (UC-WRK-29 check 4). A build
	// without it answers none.
	Milestones repository.Milestones
}

type GetContainerQuery struct {
	ContainerID shared.ID
}

type GetRecurrence struct {
	Recurrences repository.Recurrences
	Items       repository.Items
	Containers  repository.Containers
	Authorizer  Authorizer
	UnitOfWork  persistence.UnitOfWork
}

type GetSavedView struct {
	Views      viewrepo.SavedViews
	Containers repository.Containers
	Permits    Permitting
	UnitOfWork persistence.UnitOfWork
}

type GetTemplate struct {
	Writer TemplateWriter
}

type GetWorkItem struct {
	Items      repository.Items
	ItemLabels repository.ItemLabels
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
	// Gate marks what the entry's collection hides of it.
	Gate EntryGate
}

type GetWorkItemQuery struct {
	ItemID shared.ID
	// CalendarUID names the entry by the address a calendar client knows it by instead of by its
	// identifier (offline-sync.md §4.2) - the tree's question when a PUT arrives at an address the
	// view does not answer. Read when ItemID is empty; the permission is decided the same way,
	// because the entry found is the same entry.
	CalendarUID string
	// ExpandLabels asks for the labels the entry carries.
	//
	// Asked for rather than always included, which is what `expand` is for (api-guidelines.md §4):
	// the labels are a second query, and a client rendering a plain list should not pay for chips
	// it is not drawing. Absent rather than empty when it was not asked for - so that a client can
	// tell "this entry has no labels" from "I did not ask".
	ExpandLabels bool
	// ForCalendar answers the entry as a calendar shows it: without a due date its collection
	// hides (ExportView.shown), so that a client's write that leaves DUE out clears nothing.
	ForCalendar bool
}

type GiveKudos struct{ Desk KudosDesk }

type InstantiateTemplate struct {
	Quota       ItemQuota
	Writer      TemplateWriter
	Items       repository.Items
	ItemMembers repository.ItemMembers
	// Visibility answers whether a node's fixed assignee can see the collection the tree lands in.
	// The same question an assignment asks, asked here because a template written last year
	// may name somebody who has left.
	Visibility Visibility
	// Restrictions answers whether a rule is instantiating for a node's restricted assignee: the
	// entry is made unassigned and the drop reported (data-protection.md §4). Nil restricts nobody.
	Restrictions RestrictedAccounts
	Events       outbox.Events
	Activity     ActivityJournal
}

type InstantiateTemplateCommand struct {
	TemplateID   shared.ID
	CollectionID shared.ID
	ParentID     shared.ID
	// Anchor is the day the relative dates count from, and the zero time for "now". A day rather
	// than an instant: "+3 days for a project starting Monday" is about days, and it is read in
	// the caller's own zone.
	Anchor time.Time
	Title  string
}

type InstantiationResult struct {
	TemplateID shared.ID
	Root       domain.WorkItem
	// Created is the size of the tree, the root included.
	Created int
	// DroppedReferences is what the destination could not carry, from every entry that lost
	// something. Empty rather than nil: a client that iterates the losses should not have to
	// nil-check the field.
	DroppedReferences []domain.DroppedReference
}

type ItemAttachmentSet struct {
	ItemID   shared.ID
	MediaIDs []shared.ID
}

type ItemAttachmentWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate        EntryGate
	Attachments mediarepo.Attachments
	Media       MediaReferences
	Authorizer  Authorizer
	Events      outbox.Events
	Changes     changelog.ChangeLog
	Audit       audit.Sink
	Activity    ActivityJournal
	UnitOfWork  persistence.UnitOfWork
	Clock       clock.Clock
	IDs         clock.IDGenerator
	HLC         clock.HLCSource
}

type ItemLabelSet struct {
	ItemID   shared.ID
	LabelIDs []shared.ID
}

type ItemLabelWriter struct {
	Items      repository.Items
	ItemLabels repository.ItemLabels
	Labels     repository.Labels
	Containers repository.Containers
	Profiles   metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
}

type ItemMemberSet struct {
	ItemID     shared.ID
	AccountIDs []shared.ID
}

type ItemMemberWriter struct {
	Items       repository.Items
	ItemMembers repository.ItemMembers
	Containers  repository.Containers
	Profiles    metarepo.CapabilityProfiles
	// Gate is what the entry's collection offers it: the refusal before a write of what it
	// hides, and the mark on the answer (domain-model.md §2).
	Gate       EntryGate
	Authorizer Authorizer
	Visibility Visibility
	// Accounts answers whether a rule is about to put a restricted person on the entry: no rule
	// does (data-protection.md §4). Nil restricts nobody.
	Accounts   RestrictedAccounts
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
}

type ItemQuota interface {
	Items(ctx context.Context, tenant string, adding int64) error
}

type Jobs interface {
	Enqueue(ctx context.Context, request queue.Request) (shared.ID, error)
}

type KeptOutReader interface {
	Read(ctx context.Context, tenantID shared.ID) (integration.KeptOut, error)
}

type KeptOwnValue struct {
	Container domain.Container
	Settings  []domain.StructureSetting
}

type KudosDesk struct {
	Kudos      repository.Kudos
	Items      repository.Items
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type LabelCommand struct {
	ItemID  shared.ID
	LabelID shared.ID
}

type LabelWriter struct {
	Labels     repository.Labels
	Containers repository.Containers
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	HLC        clock.HLCSource
	// Text brings the names people type to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type LastMember struct {
	Hubs   repository.OrphanedHubs
	Writer ContainerWriter
	// Owners tells the workspace's owners. Optional: wired without it the hub still goes to the
	// trash, which is the half nobody could do by hand.
	Owners OwnersNotice
}

type LifecycleCommand struct {
	ItemID shared.ID
	// ExpectedVersion is the version the caller read, from If-Match. Zero means the caller read none
	// and accepts whatever is there (api-guidelines.md §5).
	ExpectedVersion int
}

type LifecycleWriter struct {
	Items      repository.Items
	Containers repository.Containers
	Authorizer Authorizer
	Events     outbox.Events
	Changes    changelog.ChangeLog
	Audit      audit.Sink
	Activity   ActivityJournal
	UnitOfWork persistence.UnitOfWork
	// Gate marks the answer with what the entry's collection hides; it gates nothing here, since
	// the lifecycle is not a write of what a collection offers.
	Gate  EntryGate
	Clock clock.Clock
	IDs   clock.IDGenerator
	HLC   clock.HLCSource
	// Queue is where a deletion asks for the tenant's cleanup to be scheduled.
	//
	// A deletion scheduling its own cleanup is not only convenient, it is the only shape available:
	// nothing in this system may enumerate tenants - the `tenant` table is behind row level security
	// with no bypass for the application role - so no scheduler can create one sweep job per tenant.
	// The job reschedules itself forever afterwards (queue.KindRetentionSweep); provisioning and
	// every session opened seed it too, so a deletion is not the only way a workspace gets one.
	Queue queue.Queue
}

type ListActivity struct {
	History    activityrepo.History
	Items      repository.Items
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListActivityQuery struct {
	ItemID shared.ID
	Cursor string
	Size   int
}

type ListBuckets struct {
	Buckets    repository.Buckets
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListBucketsQuery struct {
	CollectionID shared.ID
}

type ListCalendarFeeds struct{ Writer CalendarFeedWriter }

type ListComments struct {
	Comments   repository.Comments
	Items      repository.Items
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListCommentsQuery struct {
	ItemID shared.ID
	Cursor string
	Size   int
}

type ListContainers struct {
	Containers repository.Containers
	Authorizer Authorizer
	Reader     Reader
	UnitOfWork persistence.UnitOfWork
	// Structure resolves each container's structure in force, after the page was narrowed to what
	// the caller may see.
	Structure StructureResolver
	// Figures counts what counts in each collection of the page, one statement per kind on it.
	Figures FigureReader
	// Milestones answers when each container of the page was last finished, in one statement.
	Milestones repository.Milestones
}

type ListContainersQuery struct {
	// ParentID is the hub whose collections are wanted. Empty means the hubs, which is the one level
	// anchored to nothing.
	ParentID shared.ID
	// Type narrows the level; empty means both kinds.
	Type            domain.ContainerType
	IncludeArchived bool
	Cursor          string
	Size            int
}

type ListCustomFields struct {
	Fields     repository.CustomFields
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListCustomFieldsQuery struct {
	// CollectionID is the collection whose definitions are wanted, together with the
	// workspace-wide ones above it. Zero answers the workspace-wide ones alone.
	CollectionID shared.ID
}

type ListEmergencyNotices struct {
	Accesses   repository.EmergencyAccesses
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type ListJumbleDestinations struct {
	Collections repository.Collections
	Authorizer  Authorizer
	Reader      Reader
	UnitOfWork  persistence.UnitOfWork
}

type ListLabels struct {
	Labels     repository.Labels
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListLabelsQuery struct {
	CollectionID shared.ID
	// IncludeDeleted adds the labels taken out of the vocabulary, for a reader that offers to bring
	// one back. The same permission: a deleted label is the same vocabulary, out of use.
	IncludeDeleted bool
}

type ListPresets struct {
	Profiles metarepo.CapabilityProfiles
	// Presets reads the saved ones; a build without it answers Hubtask's four alone.
	Presets repository.Presets
	// Installation reads the installation's; a build without it answers none.
	Installation repository.InstallationPresets
	UnitOfWork   persistence.UnitOfWork
}

type ListPrivateHubAccesses struct {
	Accesses   repository.EmergencyAccesses
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListPrivateHubs struct {
	Hubs       repository.PrivateHubs
	Policies   lifecyclerepo.Policies
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
	// Accesses, Owners and Clock answer each row's emergency access for the caller (ADR-0073
	// §4): whether they may open the hub now, and until when theirs runs. Without them every row
	// says it is not offered - the safe answer for a control that must not be drawn where the
	// server would refuse it (P-05).
	Accesses repository.EmergencyAccesses
	Owners   Permitting
	Clock    clock.Clock
}

type ListReminders struct {
	Reminders  repository.Reminders
	Items      repository.Items
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListRemindersQuery struct {
	ItemID shared.ID
}

type ListSavedViews struct {
	Views      viewrepo.SavedViews
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListSavedViewsQuery struct {
	// ContainerID widens the answer to what is shared along that container's path. Zero answers
	// the caller's own views alone.
	ContainerID shared.ID
}

type ListTemplates struct {
	Templates  repository.Templates
	Containers repository.Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ListTemplatesQuery struct {
	ContainerID shared.ID
	Cursor      string
	Size        int
}

type ListTrash struct {
	Trash      repository.Trash
	Reader     Reader
	UnitOfWork persistence.UnitOfWork
	// Policies and TombstoneWindow are the two numbers the retention pass removes by - the trash
	// period it reads and the installation's offline window the Purger is given - so that the date
	// each entry carries is the pass's own.
	Policies        lifecyclerepo.Policies
	TombstoneWindow time.Duration
	// Holds and Contributors are what says whether a legal hold keeps a deletion: its rows are
	// judged as the retention pass judges them (lifecycle.Holds.Blocking), so `held` is the pass's
	// own answer rather than a second rule.
	Holds        lifecyclerepo.HoldList
	Contributors lifecyclerepo.ContributorReader
	// Restrictions is whose processing is restricted: the automatic pass keeps what such a person
	// contributed as it keeps a held account's (data-retention.md §4 item 2), so the listing says so.
	Restrictions privacyrepo.Restrictions
}