lifecycle

type ArchiveSource struct {
	TargetID shared.ID
	Path     string
}

type ArchivedHolds struct {
	Holds []HoldRecord
	Path  string
	// SnapshotAt is when the archive was taken: a hold placed between it and the loss is not in
	// it, which is the gap the operator reports per workspace.
	SnapshotAt time.Time
	// AuditTrail is whether the archive includes the trail, whose entries name the holds its own
	// copy of the workspace no longer carries.
	AuditTrail bool
	// UnreadableEntries counts the records of a hold, in the archive's copy or its trail, that name
	// too little to place it again. Left out rather than refused: one damaged record must not cost
	// the other holds.
	UnreadableEntries int
}

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

type CreateRetentionPolicy struct{ Rules Rules }

type CreateRetentionPolicyCommand struct {
	Scope          domain.Scope
	DataKind       domain.DataKind
	Condition      string
	RetainDays     int
	Action         domain.Action
	ThenAfterDays  int
	ThenAction     domain.Action
	GraceDays      *int
	Notify         *domain.Notify
	Justification  string
	Enabled        *bool
	ExportTargetID shared.ID
}

type DeleteRetentionPolicy struct{ Rules Rules }

type DispatchedEvents interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)

	// DeleteExpiredConsumption removes the record of who has already consumed what. The outbox's
	// twin table, swept at the same period and by the same pass: a record whose event has been
	// swept can say nothing about an event nobody can deliver again (ADR-0007).
	DeleteExpiredConsumption(ctx context.Context, cutoff time.Time, batch int) (int, error)
}

type EffectiveRule struct {
	Rule domain.Rule
	// InForce is whether this is the rule that would act on an object in the container asked
	// about. False for one a narrower rule beats, and for one that is switched off.
	InForce bool
}

type EmptyTrash struct {
	Purger     Purger
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type ErasureRemainders interface {
	// Seed queues the rest of every erasure the hold kept part of, in the caller's transaction.
	Seed(ctx context.Context, tenantID, holdID shared.ID) error
	// Reconcile queues the rest of every erasure kept under a hold no longer in force.
	Reconcile(ctx context.Context, tenantID shared.ID, active domain.Holds) error
}

type ExpiredDevices interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExpiredIdempotencyKeys interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExpiredSessions interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExpiredSyncLog interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExpiringDeliveries interface{ ExpiringRows }

type ExpiringRows interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExpiringSuggestions interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ExportBeforeDelete interface {
	// Export writes one archive of the tenant to the target and answers the run it produced.
	//
	// The whole tenant rather than the objects going: the archive format's scope is a tenant or a
	// container (backup-restore.md §3), and an archive of "these forty entries" is not a thing it
	// can write. What §6 asks for is that the data exists somewhere before it stops existing here,
	// and a tenant archive is that with room to spare.
	Export(ctx context.Context, targetID shared.ID) (shared.ID, error)
}

type HoldArchive interface {
	// Read answers the holds the archive carries, under the workspace's scope. An archive that is
	// not the workspace's own is refused.
	Read(ctx context.Context, scope persistence.Scope, source ArchiveSource) (ArchivedHolds, error)
}

type HoldRecord struct {
	ID       shared.ID
	Scope    domain.HoldScope
	ScopeID  shared.ID
	Reason   string
	PlacedBy shared.ID
	PlacedAt time.Time
	// ReleasedAt is when it was released in the rewound period; zero if it was not.
	ReleasedAt time.Time
}

type Holds struct {
	Holds repository.HoldWriter
	// Remainders is what lifting a hold seeds. Optional: an installation wired without it lifts
	// holds as before, and the retention pass seeds what it would have.
	Remainders ErasureRemainders
	Authorizer Authorizer
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	// Text brings a reason to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type JumbleInbox interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type ListLegalHolds struct{ Holds Holds }

type ListRetentionPolicies struct{ Rules Rules }

type NotificationHistory interface {
	DeleteExpired(ctx context.Context, cutoff time.Time, batch int) (int, error)
	CountExpired(ctx context.Context, cutoff time.Time, ceiling int) (int, error)
}

type OrphanedHubs interface {
	Sweep(ctx context.Context, tenantID shared.ID) (int, error)
}

type Outcome struct {
	// Matched is how many rows were past their period, whether or not they were removed.
	Matched int
	// Held is how many of the matched rows a pass could not act on because something will still
	// keep them on the next one: in the trash pass a legal hold or the offline window, in the rule
	// sweep a legal hold or, in its second phase, a retained descendant. Coming back at once would
	// find them again, so they do not count towards a full batch (RunRetention.Exhausted).
	Held int
	// Removed is how many actually went.
	Removed int
	// Read is how many rows the rule sweep judged, matched or not: what reading past entries it
	// cannot act on costs, set beside what it removed.
	Read int
	// Blocked counts what was refused, by reason. The reasons are the closed set above, so this is
	// a report an operator can read and a metric can be labelled from.
	Blocked map[string]int
	// SetAside are the rules the rule sweep set aside for this pass because their condition could
	// not be evaluated on a candidate, each with why (data-retention.md §2). Judged are the rules it
	// evaluated against at least one candidate without that: their failure, if they showed one,
	// is over.
	SetAside map[shared.ID]domain.RuleFailure
	Judged   map[shared.ID]bool
	// Unfinished is true when a read of the rule sweep stopped at its budget: the rows past its place
	// are still unread in this cycle, so the job comes straight back (RunRetention.Exhausted).
	Unfinished bool
}

type PlaceLegalHold struct{ Holds Holds }

type PlaceLegalHoldCommand struct {
	Scope   domain.HoldScope
	ScopeID shared.ID
	Reason  string
}

type Preview struct {
	// Matched is how many entries are past the rule's period in its scope. Exact rather than a
	// page: the switch below is about a proportion, and a count that stopped at a batch would
	// under-report exactly the runs it exists to catch.
	Matched int
	// Blocked is what would be kept back and why, from the sample rather than from the whole set:
	// deciding a legal hold against a million rows to draw a preview would cost more than the run.
	Blocked map[string]int
	// ShareOfScope is Matched over what the scope holds, which is what §5's switch reads.
	ShareOfScope float64
	// Samples are a handful of the objects, so that "four thousand entries" is a sentence somebody
	// can check.
	Samples []Sample
	// Broad reports a rule whose first run would touch more than five per cent of the holdings.
	Broad bool
}

type PreviewRetentionPolicy struct{ Rules Rules }

type PurgeWorkItem struct {
	Items      workrepo.Items
	Containers workrepo.Containers
	Purger     Purger
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
}

type PurgeWorkItemCommand struct {
	ItemID shared.ID
}

type Purger struct {
	Trash    workrepo.Trash
	Expired  repository.Expired
	Holds    repository.LegalHolds
	Removals repository.Removals
	Events   outbox.Events
	Audit    audit.Sink
	Clock    clock.Clock
	IDs      clock.IDGenerator
	// TombstoneWindow is the maximum offline window: how long the marker of a removal has to
	// survive it, and the lower bound an automatic run observes before removing at all.
	TombstoneWindow time.Duration
	// BatchSize is how many rows one sweep reads. A deletion run works in batches so that a large
	// one does not hold a single transaction open across the whole of it (data-retention.md §5).
	BatchSize int
}

type ReleaseLegalHold struct{ Holds Holds }

type ReplaceLegalHolds struct {
	Holds      Holds
	Workspaces Workspace
	Archive    HoldArchive
}

type ReplaceLegalHoldsCommand struct {
	TenantID      shared.ID
	RecoveryPoint time.Time
	// Holds or Archive, never both.
	Holds   []HoldRecord
	Archive *ArchiveSource
}

type ReplaceResult struct {
	Holds   []Replacement
	Archive *ArchivedHolds
}

type Replacement struct {
	ID               shared.ID
	Outcome          ReplacementOutcome
	TargetPresent    bool
	ReleasedInPeriod bool
}

type ReplacementOutcome string

type RetainItem struct {
	Items      workrepo.Items
	Containers workrepo.Containers
	Marking    repository.Marking
	Authorizer Authorizer
	Audit      audit.Sink
	Changes    syncrepo.ChangeLog
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	HLC        clock.HLCSource
}

type RetentionSignals interface {
	RetentionDeleted(ctx context.Context, dataKind string, count int64)
	RetentionBlocked(ctx context.Context, reason string, count int64)
	RetentionRun(ctx context.Context, dataKind string, seconds float64)
	// RetentionRead counts the rows the rule sweep judged, which is what reading past what it
	// cannot act on costs (data-retention.md §5).
	RetentionRead(ctx context.Context, dataKind string, count int64)
}

type RetentionWarner interface {
	Warn(ctx context.Context, warning notification.RetentionWarning) error
}

type Rules struct {
	Rules repository.Rules
	// Policies is the old table, read for one thing only: the upper bound an operator has set for
	// a kind (§4.4). The periods in it are carried into rules by the sweep; the bounds stay where
	// an operator writes them.
	Policies   repository.Policies
	Marking    repository.Marking
	Holds      repository.LegalHolds
	Authorizer Authorizer
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
	IDs        clock.IDGenerator
	// Conditions compiles a rule's expression when it is written. A port, so this layer
	// never learns which engine evaluates one - and the same port the automation rules use, which is
	// what makes "the same expression language" one statement rather than two.
	Conditions expression.Compiler
	// Text brings a justification to normal form C on the way in (i18n-l10n.md §5).
	Text text.Normalizer
}

type RunRetention struct {
	Policies repository.Policies
	Runs     repository.Runs
	Purger   Purger
	// History is the notification record's remover. A second kind rather than a second job,
	// because a tenant's periods are one thing to evaluate: two schedules would mean two leases,
	// two logs and two ways for one of them to quietly stop running.
	History NotificationHistory
	// Events is the outbox's own remover. Optional, like Rules and Sweeper below: an installation
	// wired without it sweeps exactly what it did before, which is what lets the two land in
	// separate releases.
	Events DispatchedEvents
	// Inbox is the jumble's remover. Required, not optional, on the notification history's
	// reasoning exactly: an inbox holds the least trusted text in the system - raw subject, raw
	// body and the sender's address, all of it PERSONAL_CONTENT - and one that silently stops
	// being swept is personal data kept past its period (risk R-09) in the one place nobody
	// looks at afterwards.
	Inbox JumbleInbox
	// Deliveries is the webhook delivery log's remover. Optional for the outbox's reason: an
	// installation wired without it sweeps exactly what it did before.
	Deliveries ExpiringDeliveries
	// Proposals is the suggestion store's remover. Optional for the outbox's reason: an
	// installation wired without it sweeps exactly what it did before, and what it would have
	// removed is a working note rather than personal content nobody looks at - a suggestion's
	// payload is a *copy* of fields the entry itself holds, and the entry has its own period.
	Proposals ExpiringSuggestions
	// Sessions is the sign-in rows' remover. Optional for the outbox's reason: an
	// installation wired without it sweeps exactly what it did before, and the rows it would
	// have removed are already unusable - the sweep forgets, revocation ends.
	Sessions ExpiredSessions
	// Devices is the synchronising devices' remover. Optional for the session's reason,
	// and with the same shape: a device silent past its period has its sign-in revoked and its
	// row removed, and an installation wired without it sweeps exactly what it did before.
	Devices ExpiredDevices
	// SyncLog is the remover of the synchronisation's records past the offline window:
	// the operation log and the tombstones. Optional for the device's reason. The change log is
	// not swept here - its months fall as partitions, the leader's duty.
	SyncLog ExpiredSyncLog
	// IdempotencyKeys is the remover of requests' stored answers past their day. Optional for the
	// session's reason: an installation wired without it sweeps exactly what it did before.
	IdempotencyKeys ExpiredIdempotencyKeys
	// KeptTexts are the deleted comments whose text a legal hold kept; the pass clears each text
	// once no hold covers it (data-retention.md §4). Optional for the session's reason: wired
	// without it, a kept text stays until a pass that has it.
	KeptTexts repository.KeptCommentTexts
	Clock     clock.Clock
	IDs       clock.IDGenerator
	// Signals is the observability slice. Optional: a run without it still runs, which is what keeps
	// a metrics adapter from being a dependency of the deletion path.
	Signals RetentionSignals
	// Rules and Sweeper are the rule-driven half of the engine. Optional together: an
	// installation wired without them sweeps the trash and the notification history exactly as
	// before, which is what makes the two halves independently deployable.
	Rules   repository.Rules
	Sweeper Sweeper
	// RuleFailures is where a pass leaves the rules it set aside and the ones it evaluated cleanly
	// (data-retention.md §2), written by Independent in a transaction of its own: the record has to
	// outlive a pass that rolls back afterwards. Optional together: wired without them, the rules
	// are set aside all the same and only the log line says so.
	RuleFailures repository.RuleFailures
	Independent  persistence.Independent
	// Remainders seeds the rest of an erasure kept under a hold no longer in force that nothing
	// seeded (data-protection.md §4.1). Optional: wired without it, a release still seeds its own.
	Remainders ErasureRemainders
	// Orphans trashes a private hub nobody is left in that the revocation or the erasure did not
	// catch - a cascade, a pod older than the rule (ADR-0073 §5). Optional: those paths trash their
	// own.
	Orphans OrphanedHubs
	// DeletedTemplates are the templates deleted while a legal hold covered them; the pass removes
	// each once no hold does (data-retention.md §4). Optional: wired without it, they stay until a
	// pass that has it.
	DeletedTemplates repository.DeletedTemplates
}

type Sample struct {
	ID    shared.ID
	Title string
	// EffectiveAt is when the act would fall due for this one: its own anchor plus the period and
	// the grace, rather than one date for the whole set.
	EffectiveAt time.Time
}

type Selection struct {
	// Cutoff is the deletion date a row has to be older than. The retention job passes the tenant's
	// period; a person emptying a trash passes now, which is everything in it.
	Cutoff time.Time
	// Reason is why, for the journal, the events and the metric.
	Reason domain.DeletionReason
	// ObserveTombstoneWindow holds back rows deleted more recently than the maximum offline window
	// (offline-sync.md §7).
	//
	// True for the automatic paths and false for an explicit one, which is the distinction the two
	// documents together draw. A retention rule removing an object a device has not yet heard about
	// would let that device recreate it on its next push, and nobody asked for the removal to happen
	// today. A person emptying their own trash did ask, and the tombstone the purge writes is what
	// stops the resurrection there - the marker outlives the row by the whole window either way.
	ObserveTombstoneWindow bool
}

type Sweeper struct {
	Rules   repository.Rules
	Marking repository.Marking
	Holds   repository.LegalHolds
	Items   workrepo.Items
	// Entries reads a page's entries in one statement, the first time a condition on that page
	// asks for `item`. Optional: without it every candidate is read on its own through Items, which
	// is what a page of a thousand candidates costs a thousand statements for (data-retention.md §5).
	Entries workrepo.ItemBatch
	// Purger is the one engine behind every removal, which is what keeps a retention hard delete
	// owing exactly what a person's purge owes: a journal entry, a tombstone, and an event per row.
	Purger Purger
	// Warnings sends the advance warning of data-retention.md §6 (R-1). Optional: a build
	// without it marks and acts exactly as before, which is what an installation that has switched
	// its notifications off already looks like - and the marking is the visibility §6 asks for
	// first, so silence here loses the message rather than the warning.
	Warnings RetentionWarner
	// Conditions compiles a rule's expression, and it is the same port and the same language the
	// automation rules use (ADR-0009). Optional: a build with none refuses to act on a
	// conditioned rule rather than acting on all of it, which is the safe direction for a pass
	// whose job is deleting.
	Conditions expression.Compiler
	Changes    syncrepo.ChangeLog
	// Export is optional. A rule that asks for one when there is nothing to write it with is
	// refused at the act rather than silently downgraded to a deletion.
	Export ExportBeforeDelete
	Clock  clock.Clock
	IDs    clock.IDGenerator
	HLC    clock.HLCSource
	// Batch is how many objects one pass judges. A thousand by default (§5).
	Batch int
	// Cursors keeps where each read stopped, so the next pass continues there (§5). Optional: a
	// build without it reads from the start on every pass and without a budget, which is what it
	// did before - a budget without a place to continue from would starve what lies past it.
	Cursors repository.Cursors
	// ReadBudget is how many rows one read judges in a pass before it stops and keeps its place:
	// what keeps a pass inside the job's deadline however many entries the read has to pass over.
	// DefaultReadBudgetPages batches by default.
	ReadBudget int
}

type UpdateRetentionPolicy struct{ Rules Rules }

type UpdateRetentionPolicyCommand struct {
	ID              shared.ID
	Condition       *string
	RetainDays      *int
	Action          *domain.Action
	ThenAfterDays   *int
	ThenAction      *domain.Action
	GraceDays       *int
	Notify          *domain.Notify
	Justification   *string
	Enabled         *bool
	ExportTargetID  *shared.ID
	ExpectedVersion int
}

type Workspace interface {
	Find(ctx context.Context) (adminrepo.TenantRecord, error)
}