ores.iam.account_messages

/**
 * @brief The workflow step that publishes a DQ-cleared accounts bundle.
 *
 * A trigger rather than a request: the DQ publisher sends it and reads no
 * reply, so it states a subject and no response. Its body is the DQ artefact
 * the server-side function knows how to expand, which is why it declares no
 * fields.
 */

/**
 * @brief A member's write on the party quick sign-in uses.
 *
 * The session names the account, so the request cannot aim the write at
 * another account, and the write needs no permission. The party must be one
 * the account is associated with, or the write is refused: the server checks
 * the association rather than trusting the caller.
 *
 * An empty =party_id= clears the stored default. A party id is a UUID, so an
 * empty string is unambiguous, and this is the only way the request can say
 * "no default" — the reason the member's screen had no clear control before.
 */

/**
 * @brief Re-scopes an *already-logged-in* session to a different party.
 *
 * Deliberately a separate subject/handler from select_party rather than a
 * relaxed version of it: select_party only accepts a narrowly-scoped,
 * single-use token (audience "select_party_only") issued exclusively by
 * the login flow, by design -- see account_operations_handler.hpp's select_party for
 * why. switch_party accepts a normal, already-authenticated session token
 * instead (any token that is NOT that single-use one), so an account with
 * access to more than one party (e.g. a tenant admin with cross-entity
 * access) can change which party's data is in view mid-session without
 * logging out and back in. Same party-membership check and new-token
 * issuance as select_party otherwise.
 */

/**
 * @brief A member's write on their own account.
 *
 * The session names the account: the request carries no account id, so it
 * cannot name another account. The three fields a member owns are the whole
 * of the profile write; the three a member does not own are declared beside
 * them so a stated value is refused by name rather than dropped in silence.
 *
 * The write states the owned fields whole: an empty string replaces the
 * field with nothing. The same empty string on an unowned field means the
 * field is not stated, and the write leaves it as it is.
 */

/**
 * @brief A member's write on their own contact record.
 *
 * The session names the account and the record is found from it, so the
 * request carries no account id and no record id, and it cannot name another
 * account's record. A member who has no contact record gets one on the first
 * write.
 *
 * The write states the nine fields whole: an empty string replaces the field
 * with nothing. A stated email must be a valid address, and a stated country
 * code must be an ISO 3166-1 alpha-2 code, or the write is refused with the
 * field named.
 */

/**
 * @brief A member's read of their own contact record.
 *
 * The session names the account, so the request carries no account id and
 * cannot name another account's record. The read needs no permission: it is
 * a self read on the allow-list of Authorised reads. Reading a colleague's
 * record is list_by_account_id, which needs
 * iam::account_contact_informations:read.
 */

/**
 * @brief A member's read of their own account.
 *
 * The session names the account, so the request carries no account id and
 * cannot name another account's. The read needs no permission: it is a self
 * read on the allow-list of Authorised reads, so a member sees their own name,
 * picture and job title without holding iam::accounts:read. Reading a
 * colleague's account is iam.v1.accounts.get, which needs that permission.
 */

/**
 * @brief A member's read of their own sign-in state.
 *
 * The session names the account, so the request carries no account id and
 * cannot name another account's. The read needs no permission: it is a self
 * read on the allow-list of Authorised reads, so a member sees whether their
 * account is locked and when they last signed in without holding
 * iam::login_info:read. Reading another account's is iam.v1.login_info.get,
 * which needs that permission.
 */

/**
 * @brief A member's read of the places their own account is signed in.
 *
 * The session names the account, so the request carries no account id and
 * cannot name another account's. The read needs no permission: it is a self
 * read on the allow-list of Authorised reads. The tenant-wide read of open
 * sessions is iam.v1.ops.get_active_sessions, which needs iam::sessions:read.
 */

/**
 * @brief One party the caller's account works in, as the member's own screen
 * reads it.
 *
 * The name, the category and the business centre come from IAM's party cache,
 * which mirrors refdata's parties per tenant; the association itself carries
 * the identifier alone. A party the cache has not seen answers with empty
 * strings rather than a half-read row.
 *
 * Declared before the response that carries it, because the generators emit
 * the messages in the order this file states them.
 */

/**
 * @brief A member's read of the parties their own account works in.
 *
 * The session names the account, so the request carries no account id and
 * cannot name another account's list. The read needs no permission: it is a
 * self read on the allow-list of Authorised reads.
 *
 * The subject exists because the association read answers with a party
 * identifier and nothing on the browser's path turns one into a name: the
 * sign-in reply is the only read that names a party today.
 */

/**
 * @brief An administrator's write on who one account reports to.
 *
 * The write names one field and nothing else, so a screen that changes the
 * reporting line does not send every other field back, and a field changed
 * elsewhere between the screen's read and this write is not silently
 * overwritten. It needs =iam::accounts:update=, as every administered account
 * write does.
 *
 * An empty =reports_to_account_id= clears the line. =expected_version= is the
 * account version the caller read: when it is stated and the account has moved
 * on since, the write is refused with a conflict rather than applied to a row
 * the caller has not seen. An absent version states no precondition.
 */

/**
 * @brief One party the reporting shape is drawn under.
 *
 * A person works in a party, and a viewer may work in several, so the shape is
 * grouped by party. The service states which parties are in scope by id; the
 * handler names them from IAM's party cache, which mirrors refdata's parties,
 * so the name and the parent are empty for a party the cache has not seen
 * rather than a half-read row.
 *
 * Declared before the node and the response that carry it, because the
 * generators emit the messages in the order this file states them.
 */

/**
 * @brief One account in the tenant's reporting shape.
 *
 * The depth counts from a root: a root is 0, its reports are 1, and so on.
 * When the read names a root, that root is 0 in the answer. An account that
 * does not reach any root — a manager who is missing, or a ring the store
 * accepted before the guard existed — is answered with depth -1 and counted in
 * the response's unrooted total.
 *
 * Declared before the response that carries it, because the generators emit
 * the messages in the order this file states them.
 */

/**
 * @brief A reporting shape in one read: the tenant's, or what the caller may see.
 *
 * The scope follows what the caller holds. A caller with =iam::accounts:read=
 * reads the tenant's own accounts, which row-level security bounds. A caller
 * with =iam::organisation:read= and not that code reads the people they may
 * see: those who work in any party their own account works in, and everyone
 * who reports to them directly or indirectly. A node never carries an email or
 * a contact detail. A caller with neither is refused. An empty =root_account_id= asks for the whole
 * scope, ordered by depth; a stated root asks for that account's branch, so a
 * screen can open one part of a large organisation without carrying the rest.
 */

/**
 * @brief Reconciles the accounts a tenant holds with the pictures they name.
 *
 * Every account that names a picture code and carries no picture gets one:
 * the image is ensured in the tenant and the account is updated. An account
 * that already carries a picture is left alone, so a repeated call writes
 * nothing.
 *
 * A trigger rather than a report: the provisioning step sends it, and an
 * operator may re-run it from a client.
 */