ores.inbox.approval_operations

/**
 * @brief Asks for something that a person who may decide it must approve.
 *
 * The request is raised for the signed-in person, waiting, and expiring when
 * its kind says. The component that owns the kind writes the detail that names
 * what is asked for, keyed by the request's id.
 */

/**
 * @brief Takes back a request the signed-in person raised.
 *
 * Only an open request can be withdrawn, and only by the person who asked.
 */

/**
 * @brief Approves, refuses, holds or resumes a request.
 *
 * The decider needs the permission the request's kind names, and is not the
 * person who asked. The request moves to the state the decisions reach: an
 * approval closes it only once the kind's approvals_required approvals stand.
 */

/**
 * @brief Reads the open requests the signed-in person may decide, and the ones
 * answered within the installation's window.
 *
 * Open means waiting or held. A request is in the queue when the person holds
 * its kind's decide permission and did not raise it. Oldest first.
 *
 * A request leaves the queue the moment it is answered, which leaves the person
 * who answered it nothing to look at: the notice that says what happened links
 * to a request the queue no longer holds. So the answer carries the requests
 * answered recently beside the open ones, newest answer first, for as long as
 * the installation says. How long is the variability system setting
 * =inbox.approval_queue.answered_window_seconds=; the read falls back to an
 * empty tail when that setting cannot be read, because the open queue is the
 * read's reason to exist and it is not.
 */

/**
 * @brief Reads the requests the signed-in person raised, newest first.
 */

/**
 * @brief Reads whether the caller's tenant enforces approvals, and who said so.
 *
 * Any signed-in person may ask, so that a request which did not wait can be
 * explained to whoever is looking at it.
 */

/**
 * @brief Turns auto-approval on or off for the caller's tenant.
 *
 * Needs inbox::approvals:set_mode. Each change is a new version of the setting,
 * with who made it and why.
 */

/**
 * @brief Reads the one request an identifier names.
 *
 * A notice a person is given carries the request it is about, so the notice
 * has to be able to open it. The queue cannot answer that: it holds what is
 * waiting, and a notice is usually read after the request stopped waiting.
 * The request a person may open is therefore read on its own, and the caller
 * states which request they mean rather than reading a list to find it.
 *
 * What the caller may open is the store's to decide: the person who asked,
 * and whoever may decide a request of that kind. A stranger is answered as if
 * the request did not exist, so the read tells nobody that a request they may
 * not see is there.
 */

/**
 * @brief Closes every open request past its kind's deadline, across every
 * tenant.
 *
 * The scheduler fires this, so it acts as the service rather than as a person
 * and reaches requests no tenant-scoped caller could read. Each person who
 * asked is told; a request already closed is not open, so a repeated call
 * changes nothing.
 *
 * A scheduler firing is a plain publish with no token, so this carries no
 * session: it is trusted at the transport, as the compute reaper is. That is
 * affordable here because it takes no input and closes only what is already
 * past its deadline, which a caller could reach by waiting.
 */

/**
 * @brief Warns the deciders of every open request whose deadline is close.
 *
 * The other half of the deadline. The sweep that closes what nobody answered
 * keeps the queue moving, but a decider who never looked learns afterwards;
 * this gives them the chance the deadline was there to give.
 *
 * It has its own schedule and its own window, because warning somebody is a
 * nudge with its own timing and its own audience, while closing a queue that
 * has stopped moving is housekeeping. The window is the variability setting
 * =inbox.approval_expiry.reminder_window_seconds=.
 *
 * A request is warned about once, and the notice is what says so: a reminder
 * already raised names the request, so there is no second mark to keep in step
 * with the first. A request answered before its deadline passes stops matching,
 * and the one the sweep closed is left out by the close.
 *
 * A scheduler firing is a plain publish with no token, so this carries no
 * session: it takes no input, and it only reads requests that are already close
 * to a deadline their kind set.
 */

/**
 * @brief Resumes the applies that stopped, and ends the ones that ran out of
 * time.
 *
 * An approved request whose kind names an apply workflow stays approved until
 * the workflow applies it. When the run stopped on a failure that can pass, or
 * the start was lost, nothing moves it on. This finds those requests, starts
 * the run again (a repeated start names the same run, so it changes nothing when
 * the run exists) and asks the engine to resume a stopped run. A run that
 * stopped on a refusal never reaches here: the refusal moves its request to
 * apply_failed.
 *
 * When the kind's window ends, the request moves to apply_failed with the
 * reason "could not apply", and the person who asked is told, so a request never
 * retries forever.
 *
 * A scheduler firing is a plain publish with no token, so this carries no
 * session: it takes no input, and it only acts on requests that are already
 * approved.
 */

/**
 * @brief One field of a request at one version, as a screen names and draws it.
 *
 * The value is text whatever its type: the renderer that fills this in is the
 * same one the record screens' history panel reads, so a story and a panel
 * draw the same request the same way.
 */

/**
 * @brief One version of a request, with who wrote it, when, and every field it
 * held.
 *
 * The oldest version is the request as it was raised. Each later one is a
 * decision that moved it, so this is the request's own half of its story. The
 * screen pairs each version with the one before it to draw what changed.
 */

/**
 * @brief Reads every version of one request, newest first.
 *
 * Answered when the caller raised the request, and when the caller may read
 * approval requests. Answered as not found otherwise, so a caller learns
 * nothing about a request they may not read.
 *
 * The entity read of approval requests and the generic history read both gate
 * on the administrator's permission, so neither can answer the person who
 * raised the request with their own request's versions. This is the read that
 * can, and it is why the story of a request is an operation rather than a
 * composition of the reads that already exist.
 */

/**
 * @brief Where one part of a request stands.
 *
 * A request that needs several functions to approve lists one of these for each.
 * The state says what a person reading the request needs to know: whether the
 * part has answered, whether its turn has come, or whether an earlier part
 * must answer first.
 */

/**
 * @brief Reads where each part of one request stands.
 *
 * Answered when the caller raised the request, and when the caller may decide
 * a request of its kind. Answered as not found otherwise, as opening the
 * request is. The person who asked is the one who waits on the parts, so the
 * entity read of the parts, which gates on the administrator's permission,
 * cannot serve them.
 */