Application‐Wide Glossary - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Enterprise Remote Systems (ERS) — Application-Wide Glossary

Scope: Current application terminology through Bite 30E — Session and Tenant Selection Refactor.
Purpose: Establish one consistent vocabulary for requirements, implementation discussions, manual tests, diagnostics, patches, API output, and database inspection.

1. Canonical Terminology Rules

These rules take precedence over older Bite-specific wording.

1.1 Use the full term “Authentication Account”

Avoid using Account by itself when there is any possibility of confusion with a Collaborator Current Account.

Use:

Authentication Account

for login/session identity.

Use:

Current Account

for a Collaborator’s financial ledger.

1.2 “Person ID” means the global Person ID

Unless explicitly qualified otherwise:

Person ID = global_people.id

The pre-Bite-30 tenant-owned people.id is a transitional compatibility identifier and must be called:

Legacy Person ID — people.id. A tenant-owned compatibility identifier retained temporarily during the Bite 30 migration. As of Bite 30F, Legacy Person ID is not the canonical parent of a Collaborator Journey. The canonical parent is the Person–Tenant Membership. Collaborator APIs expose this compatibility value as legacyPersonId, and the database temporarily retains it as collaborator_journeys.person_id.

when it needs to be discussed.

1.3 “Actor ID” means the persisted authorization Actor ID

Canonical term:

Actor ID = authz_actors.id

Some APIs use:

actorRecordId

When discussing those APIs, write:

actorRecordId (Actor ID)

Do not treat actorRecordId as a different kind of Actor.

1.4 Actor ID and Actor Key are different

Actor ID
= authz_actors.id
= internal persisted record identifier

Actor Key
= authz_actors.actor_key
= stable semantic/external key used to recognize an Actor

Never call an Actor Key an Actor ID.

1.5 “Membership ID” means Person–Tenant Membership ID

Membership ID = person_tenant_memberships.id

Use the full term Person–Tenant Membership when discussing the relationship itself.

1.6 “Tenant ID” means the immutable Tenant record ID

Tenant ID = tenants.id

A Tenant’s name, code, and id are different values.

The Tenant ID is the authoritative API scoping identifier.

1.7 “Collaborator ID” currently means the Collaborator Journey record ID

In the current implementation:

Collaborator ID = collaborator_journeys.id

It is not a:

Person ID
Actor ID
Membership ID

This is a current implementation convention that may be revisited in later Bite 30 cutovers.

2. Identity and People

Person

The application-wide business identity for one real human.

A Person is global across ERS rather than being owned by one Tenant.

A Person can:

  • exist without being a Collaborator;
  • belong to zero, one, or many Tenants through Person–Tenant Memberships;
  • have at most one ordinary Authentication Account;
  • have separate tenant Actors for different Tenants.

Canonical implementation:

global_people

Canonical identifier:

Person ID

Global Person

Implementation term for the Bite 30 authoritative Person record.

Global Person = Person

Use Person in requirements, manual tests, and normal discussion.

Use Global Person only when it is necessary to distinguish the authoritative Bite 30 record from the transitional legacy people row.

Legacy Person

The pre-Bite-30 tenant-owned Person record retained temporarily so older business modules can continue operating during the Bite 30 refactor.

Implementation:

people

Identifier:

Legacy Person ID

A Legacy Person is not the canonical human identity.

Relationship:

Person
  -> Person–Tenant Membership
      -> Legacy Person

The Legacy Person relationship is transitional and should not be used as the primary vocabulary for new Bite 30 requirements.

Person Profile

The personal, contact, address, banking, emergency-contact, and related information stored for a Person.

Examples include:

First Name
Last Name
Nickname
CPF
RG
Cellular
Email
Address
Bank details
PIX key
Emergency contact

Operationally Inactive Person

A global Person whose operational lifecycle has been explicitly deactivated. Operational deactivation makes every Person–Tenant Membership inactive, prevents Account-backed Tenant Actor access, and lifecycle-suspends existing delegated Role Grants without deleting historical identity, authorization, Journey, financial, or audit records. A Tenant Administrator may reactivate the Person only for the Administrator's own Tenant, subject to any application-level security suspension.

Profile Completion Status

Indicates how complete a Person profile is for downstream workflows.

Current Person records include a profile-completion state such as:

PERSONAL_ONLY
COMPLETE

The exact completion state may control whether the Person is eligible for actions such as Collaborator creation.

Can Create Collaborator

A Person-level eligibility indicator showing whether the Person has enough required information to enter the Collaborator workflow.

Implementation field:

canCreateCollaborator

This is not an authorization Role.

3. Tenancy

Tenant

An organizational/business partition within ERS.

Tenant-owned business data includes, among other things:

  • Person–Tenant Memberships;
  • Collaborator Journeys;
  • Expenses;
  • Gold Prices;
  • Price List Items;
  • Work Periods;
  • Work Period Assignments;
  • Gold Production;
  • Accruals;
  • Current Account ledger entries;
  • Receipts;
  • Tenant Settings;
  • Tenant Reference Data.

Canonical identifier:

Tenant ID

Default Tenant

The historically established Tenant whose ID is:

default

default is a real Tenant ID, not a wildcard and not an absence of tenant selection.

Tenant Name

Human-readable Tenant name.

Example:

Byte 28A Manual Test

A Tenant name is not the Tenant ID.

Tenant Code

Human-readable/administrative code associated with a Tenant.

Tenant codes are normalized and unique.

A Tenant code is not the Tenant ID and should not be used as the API scoping identifier unless an endpoint explicitly says otherwise.

Tenant ID

Immutable identifier for a Tenant.

Canonical implementation:

tenants.id

Use Tenant ID when:

  • calling tenant-scoped APIs;
  • comparing Actor bindings;
  • comparing Memberships;
  • recording manual-test fixtures.

Active Tenant

A Tenant whose active state permits normal tenant operations.

An inactive Tenant remains historically visible but normal write operations are restricted.

Tenant Operational Status

Derived administrative state of a Tenant.

Current values include:

ACTIVE_READY
ACTIVE_NO_TENANT_ADMIN
INACTIVE

ACTIVE_READY

Tenant is active and has at least one active Actor with an active TENANT_ADMIN grant for that Tenant.

ACTIVE_NO_TENANT_ADMIN

Tenant is active but currently has no active Tenant Administrator.

INACTIVE

Tenant itself is inactive.

4. Person–Tenant Membership

Person–Tenant Membership

The authoritative relationship between one global Person and one Tenant. A Person–Tenant Membership is the canonical parent of all Collaborator Journeys for that Person in that Tenant. One Person–Tenant Membership may have multiple historical closed Collaborator Journeys, but at most one open Collaborator Journey.

It answers:

“Does this Person belong to this Tenant, and what is the status of that relationship?”

Canonical implementation:

person_tenant_memberships

Canonical identifier:

Membership ID

Relationship:

Person
  -> Person–Tenant Membership
      -> Tenant

A Person can have Memberships in multiple Tenants.

Membership ID

Identifier of a Person–Tenant Membership.

Membership ID = person_tenant_memberships.id

It is not the Person ID, Actor ID, or Tenant ID.

ACTIVE Membership

A Person–Tenant Membership whose status is ACTIVE.

For an ordinary Authentication Account to use a Tenant in Bite 30E, its Tenant Actor must be backed by an ACTIVE Membership in the same Tenant.

Same-Tenant Membership

A Membership whose Tenant ID equals the Tenant in the Authentication Account → Actor binding.

Required ordinary tenant identity shape:

Authentication Account
  -> TENANT Actor binding
      -> Tenant X
      -> Membership
          -> Tenant X
          -> ACTIVE

A Membership from Tenant Y cannot validate an Actor bound to Tenant X.

5. Collaboration

Collaborator

A Person is a Collaborator in a Tenant when the Person's Person–Tenant Membership for that Tenant has an open Collaborator Journey. Collaborator is a tenant-scoped lifecycle/capability state and is not a separate Person identity.

In the current implementation, the persisted Collaborator identity used by business modules is a Collaborator Journey record.

A Person and a Collaborator are not synonyms:

Every Collaborator represents a Person
but
not every Person is a Collaborator

Collaborator Journey

A tenant-scoped, time-bounded collaboration lifecycle belonging to exactly one Person–Tenant Membership. A Person–Tenant Membership may have multiple historical closed Collaborator Journeys, but at most one open Collaborator Journey. Closing a Collaborator Journey ends current Collaborator capabilities only; it does not deactivate or delete the Person, Person–Tenant Membership, Authentication Account, or Tenant Actor.

Canonical implementation:

Global Person
  -> Person–Tenant Membership
      -> Collaborator Journey

It contains business state such as:

  • journey start date;
  • default end date;
  • extension days;
  • projected end date;
  • payment method/configuration;
  • sector;
  • location;
  • task;
  • status;
  • planning availability;
  • close date.

Collaborator ID

Current implementation identifier for a Collaborator Journey.

Collaborator ID = collaborator_journeys.id

It is distinct from:

Person ID
Membership ID
Actor ID

Active / Current Collaborator Journey

A Collaborator Journey that is still operational and has not been closed.

A Person can have historical Collaborator Journeys while no longer being an active Collaborator.

Journey Start Date

Date on which the Collaborator Journey begins.

Default End Date

Original expected end date before any extensions.

Extension Days

Number of days added to a Collaborator Journey.

Projected End Date

Current expected Journey end date after applying extensions.

Planning Availability

Indicates whether a Collaborator or Work Period Assignment is available for work planning.

Current assignment values include:

ACTIVE
DAY_OFF
LEAVE_OF_ABSENCE

6. Authentication

Authentication

The process of proving which Authentication Account is using ERS.

Authentication answers:

“Which Authentication Account has logged in?”

Authentication does not by itself determine all actions the user may perform.

That is authorization.

Authentication Account

The single application-global login identity for one human.

Canonical implementation:

auth_user_accounts

Canonical identifier:

Authentication Account ID

An ordinary Authentication Account normally represents exactly one Person.

A single Authentication Account may own multiple Tenant Actors.

Conceptual relationship:

Person
  -> one Authentication Account
      -> Tenant Actor A
      -> Tenant Actor B
      -> ...

Application Administrator Authentication Accounts are intentionally different: they own a GLOBAL Actor and do not require an ordinary Person binding.

Authentication Account ID

Identifier of the Authentication Account.

Authentication Account ID = auth_user_accounts.id

Do not shorten this to “Account ID” in documentation where Current Account might also be discussed.

Login

Normalized login value used to authenticate an Authentication Account.

Current implementation stores login in lowercase and enforces uniqueness.

Example:

[email protected]

A Login is not necessarily identical to the Person’s business email address, although they may be the same.

Authentication Account Status

An Authentication Account can be:

ACTIVE
INACTIVE

ACTIVE Authentication Account

May authenticate, subject to valid credentials and session rules.

INACTIVE Authentication Account

Cannot authenticate until reactivated.

Authentication Account activation is independent of Tenant Actor activation.

Account–Person Binding

The relationship connecting an ordinary Authentication Account to its one global Person.

Canonical implementation:

auth_account_people

Application Administrator Authentication Accounts intentionally do not use this ordinary Person binding.

Account–Actor Binding

The authoritative ownership relationship connecting an Authentication Account to an Actor.

Canonical implementation:

auth_account_actors

A binding contains:

Authentication Account ID
Actor ID
Binding Scope
Tenant ID, when TENANT
Membership ID, when applicable
Primary compatibility flag

Binding Scope

Scope stored on the Authentication Account → Actor binding.

Current values:

GLOBAL
TENANT

Do not confuse this with the Current Actor API’s effective scope, which uses:

APPLICATION
TENANT

GLOBAL Account–Actor Binding

An Authentication Account → Actor binding that is application-global.

Used for the Application Administrator identity.

A GLOBAL binding has no tenant-specific Membership.

TENANT Account–Actor Binding

An Authentication Account → Actor binding associated with exactly one Tenant.

For an ordinary Person, the binding also identifies the Person–Tenant Membership that validates the Actor in that Tenant.

Primary Actor

A transitional compatibility concept retained from the pre-multi-Actor authentication model.

Implementation field:

is_primary

The authoritative Bite 30 relationship is the complete set of Account–Actor bindings, not merely the primary Actor.

Do not base new business rules on “primary Actor.”

Session

An authenticated server-side session belonging to an Authentication Account.

Canonical implementation:

auth_sessions

Bite 30E rule:

Session belongs to Authentication Account
not to one Tenant Actor

Therefore:

same Session
+ different selected Tenant
= potentially different effective Actor

Session Cookie

HTTP-only cookie carrying the opaque session token used by the browser.

Default cookie name:

ers_session

The raw token is not persisted; only its hash is stored.

Password Reset Token

Short-lived, single-use token allowing an Authentication Account password to be replaced.

Canonical implementation:

auth_password_reset_tokens

Password reset is Authentication Account-level, not Actor-level.

Must Change Password

Authentication Account state requiring the user to change the password before continuing to normal application use.

Implementation:

must_change_password

Account Reactivation Request

Request to restore an INACTIVE Authentication Account.

Canonical implementation:

auth_account_reactivation_requests

Current statuses:

PENDING
APPROVED
REJECTED

A reactivation request changes Authentication Account availability only; it does not create or replace Tenant Actor bindings.

7. Actor and Effective Identity

Actor

Persisted authorization identity used by ERS to evaluate authority in an operating context.

Canonical implementation:

authz_actors

An Actor is not the Authentication Account and is not the Person.

Conceptually:

Person
  -> Authentication Account
      -> Actor

For an ordinary multi-tenant Person:

Person
  -> Authentication Account
      -> Tenant A Actor
      -> Tenant B Actor

Actor ID

Persisted Actor record identifier.

Actor ID = authz_actors.id

This is the canonical manual-test term.

actorRecordId (Actor ID)

Field name returned by APIs such as:

GET /api/v1/authz/current-actor

It refers to the same persisted:

authz_actors.id

Use in documentation as:

actorRecordId (Actor ID)

Actor Key

Semantic key identifying an Actor.

Implementation:

authz_actors.actor_key

Actor Key is distinct from Actor ID.

Actor Display Name

Human-readable label stored on an Actor for administrative display.

It is not an identity key and should not be used for authorization comparisons.

Active Actor

An Actor whose active state permits it to be considered for effective authorization.

Actor activation is independent of Authentication Account activation.

Inactive Actor

An Actor that cannot serve as the effective Actor.

For Bite 30E ordinary tenant identity:

ACTIVE Authentication Account
+
inactive Tenant Actor
=
Authentication Account remains authenticated
but that Tenant is unavailable

Tenant Actor

An Actor owned by an Authentication Account through a TENANT binding for one specific Tenant.

For an ordinary Person, a usable Tenant Actor requires:

Tenant Actor
= activates a Tenant operating context,
  delegated Tenant authority,
  and current Collaborator capabilities

It does not activate or revoke base Person self-service.

No Tenant Access should be replaced, for this state, by:

No Tenant Workspace

Meaning:

The Authentication Account is authenticated and base Person self-service remains available, but no Tenant operating context can currently be selected.

Global Actor

An Actor owned through a GLOBAL Authentication Account → Actor binding.

Used for application-global administration.

A Global Actor is not a Tenant Actor.

Current Actor

The Actor resolved by the backend for the current request.

Endpoint:

GET /api/v1/authz/current-actor

For an ordinary Authentication Account:

Authentication Account Session
+
selected Tenant
=
Authentication Account-owned Tenant Actor for that Tenant

For an Application Administrator during the current transitional model:

Authentication Account Session
+
selected Tenant
=
same GLOBAL Application Actor

Effective Actor

Synonym for the Current Actor when emphasizing that it is the Actor actually used to evaluate authorization for the request.

Prefer Current Actor when referring to the API.

8. Tenant Selection

Tenant Selection

The user’s choice of which Tenant context to operate in.

Bite 30E rule:

Tenant selection does not authenticate another user.
Tenant selection resolves another Authentication Account-owned Actor.

For an ordinary multi-tenant Authentication Account:

Tenant A -> Actor A
Tenant B -> Actor B

while the Authentication Account and Session remain unchanged.

Selected Tenant ID

Tenant ID currently selected by the browser.

Frontend storage key:

ers.auth.selectedTenantId

The browser persists the Tenant ID, not the Actor ID.

X-Tenant-ID

HTTP request header carrying the selected Tenant ID.

Canonical interpretation:

tenant-selection hint

It does not identify the user and does not grant authority.

The backend validates it against the authenticated Authentication Account’s persisted identity.

Tenant Option

A Tenant context that the authenticated Authentication Account is permitted to select.

Endpoint:

GET /api/v1/auth/tenant-options

For an ordinary Authentication Account, a Tenant Option requires:

Authentication Account owns Actor
+
Actor ACTIVE
+
binding scope TENANT
+
binding Tenant matches option Tenant
+
Membership exists
+
Membership belongs to Authentication Account Person
+
Membership belongs to same Tenant
+
Membership ACTIVE

A delegated Role is not required merely to produce a valid Tenant Option for intrinsic Person self-service.

No Tenant Access

Authenticated state in which the Authentication Account remains valid but currently has no usable Tenant Actor.

This is intentionally different from being logged out.

tenant_actor_unavailable

Error code returned when an authenticated Authentication Account cannot resolve a valid Actor for the selected Tenant.

Typical result:

HTTP 403
tenant_actor_unavailable

It means:

Authentication Account authentication is valid
but selected Tenant identity is unavailable

It is not an invalid-password or expired-session error.

9. Authorization

Authorization

The process of determining what the Current Actor may do.

Authorization answers:

“Given this authenticated Authentication Account, selected Tenant, Current Actor, intrinsic authority, and delegated Role Grants, is this operation allowed?”

Intrinsic Authority

Authority derived directly from the identity relationship itself rather than from a delegated Role.

Bite 30D introduced intrinsic self-service authority.

Examples include a Person being allowed to access their own permitted Person information without needing the historical PERSON Role.

Intrinsic Permission

Permission included because of intrinsic identity state.

Returned by the Current Actor API as:

intrinsicPermissions

Delegated Authority

Authority explicitly assigned to an Actor through active Role Grants.

Examples:

TENANT_ADMIN
EARNINGS_OPERATOR
EXPENSE_OPERATOR
APPLICATION_ADMIN

Delegated Permission

Permission derived from active persisted Role Grants.

Returned by the Current Actor API as:

delegatedPermissions

Effective Permission

Permission the Current Actor actually has after combining:

Intrinsic Permissions
+
Delegated Permissions

Returned as:

permissions

Permission

Fine-grained authorization capability.

Permissions are what protected operations ultimately require.

Role

Named bundle of delegated Permissions.

Canonical implementation:

authz_roles

Relationship:

Actor
  -> Role Grant
      -> Role
          -> Permissions

Role Code

Stable programmatic identifier for a Role.

Current delegated Role codes include:

APPLICATION_ADMIN
TENANT_ADMIN
EARNINGS_OPERATOR
EXPENSE_OPERATOR

Role Grant

Persisted assignment of a Role to an Actor.

Canonical implementation:

authz_actor_role_grants

A Role Grant identifies:

Actor
Role
Tenant target
Active state

Active Role Grant

Role Grant currently contributing delegated authority.

Inactive grants remain historical records but do not provide authority.

Application-Global Role Grant

Role Grant whose Tenant target is:

*

The * value means application-global scope.

It is not a Tenant ID.

Tenant Role Grant

Role Grant targeted at one exact Tenant ID.

A Tenant Role Grant must not be applied to an Actor that is not properly bound to that Tenant.

Tenant Role Grant Eligibility

Administrative determination of whether an Actor is eligible to receive a tenant-scoped Role.

For an ordinary Tenant Actor, eligibility requires:

Actor ACTIVE
+
Authentication Account binding exists
+
binding scope TENANT
+
binding identifies target Tenant
+
Membership exists
+
Membership ACTIVE
+
Membership belongs to same Tenant

The Authorization → Actors screen exposes these facts.

Lifecycle-Suspended Role Grant

A retained Role Grant assignment that does not contribute effective delegated permissions because the Person was operationally deactivated. The Role Grant remains assigned for historical and cardinality rules, including Tenant Administrator slot accounting, until explicitly revoked. Tenant reactivation does not clear lifecycle suspension; an authorized administrator must explicitly grant the Role again to make it effective.

APPLICATION_ADMIN

Application Administrator Role.

Application-global control-plane authority.

Canonical behavior:

GLOBAL Account–Actor binding
Current Actor scope = APPLICATION
Role = APPLICATION_ADMIN

An Application Administrator is not a Tenant Administrator merely because a Tenant is selected.

TENANT_ADMIN

Tenant Administrator Role — A Tenant-scoped delegated authorization role (TENANT_ADMIN). A Tenant may have zero, one, or two active TENANT_ADMIN Role Grants at a time, and two occupied slots must belong to two distinct global Persons. A global Person may hold active TENANT_ADMIN authority in no more than one Tenant at a time, even through different Tenant Actors. Cardinality belongs to the active Role Grant: deactivating an Actor does not release a slot; the grant must be explicitly revoked. A Tenant with one administrator may assign a second eligible Person before revoking a departing administrator to provide redundancy or a safe handoff.

Delegated tenant-scoped administrative authority for one exact Tenant.

The Actor receiving this Role must be properly Tenant-bound.

EARNINGS_OPERATOR

Tenant-scoped delegated Role for earnings-related operations.

It does not imply Tenant Administrator authority.

EXPENSE_OPERATOR

Tenant-scoped delegated Role for expense-related operations.

It does not imply Tenant Administrator authority.

PERSON Role — Deprecated

Historical self-service Role from the pre-Bite-30D authorization model.

Current rule:

Person self-service is intrinsic

The PERSON Role is no longer a normal grantable Role and should not be used in new manual-test identity definitions.

Old upgraded databases may still contain historical inactive PERSON records/grants.

Application Scope

Effective Current Actor scope used for application-global authorization.

Current Actor API value:

APPLICATION

Typically used by the Global Application Administrator Actor.

Tenant Scope

Effective Current Actor scope for one Tenant.

Current Actor API value:

TENANT

GLOBAL vs APPLICATION

These terms occur at different layers.

Use:

GLOBAL

for the Authentication Account → Actor binding scope.

Use:

APPLICATION

for the effective Current Actor authorization scope.

For an Application Administrator:

Account–Actor binding scope = GLOBAL
Current Actor scope = APPLICATION

These are related but not interchangeable field values.

Authorization Audit Log

Immutable record of security-relevant authorization decisions and administrative operations.

Canonical implementation:

authz_audit_logs

Typical information includes:

Actor ID
Tenant ID
Permission
Operation
Target
Decision
Reason
Request path/method
Metadata
Timestamp

Application-Level Security Suspension

An application-global Authentication Account restriction controlled by an Application Administrator. A security-suspended Authentication Account cannot be reactivated by a Tenant Administrator. Clearing the security suspension does not by itself reactivate an operationally inactive Person or any Person–Tenant Membership.

Recent Reauthentication

Security control requiring the user to have recently re-proven credentials before especially sensitive operations.

It is separate from Role/Permission checks.

10. Application Administration Surfaces

Authentication Administration

Application Administrator UI for Authentication Accounts and authentication lifecycle.

Route:

/admin/authentication

Typical responsibilities include:

  • Authentication Account inspection;
  • Person association;
  • Actor bindings;
  • Authentication Account activation/deactivation;
  • password-reset operations;
  • reactivation requests.

Authorization Administration

Application Administrator UI for Actors, Roles, Permissions, and Role Grants.

Route:

/admin/authorization

Typical responsibilities include:

  • Actor inspection;
  • Actor activation/deactivation;
  • Authentication Account binding visibility;
  • Membership eligibility visibility;
  • Tenant Role Grant eligibility;
  • Role Grant creation/revocation.

Actors Presentation

The Actor catalog inside Authorization Administration.

It should use Actor terminology consistently:

Actor ID
Actor Key
Person
Authentication Account binding
Binding Tenant
Membership
Role Grants
Tenant Role Grant eligibility

11. Reference and Configuration Data

Reference Data

Tenant-owned configurable lookup/catalog values used by business records.

Canonical implementation:

reference_data

Examples include values for:

  • Person status;
  • payment methods;
  • sectors;
  • locations;
  • tasks;
  • expense categories;
  • value units;
  • other coded business choices.

Reference Data entries have:

Tenant
Type
Code
Label
Description
Active state
Sort order
optional metadata

Reference Data Type

Category of lookup values.

Examples conceptually include:

person_status
payment_method
sector
location
task
expense_category
value_unit

Tenant Setting

Tenant-specific configurable setting.

Canonical implementation:

tenant_settings

A Tenant Setting is identified by:

Tenant ID
Setting Key

and stores a value plus description/audit information.

12. Work Planning

Work Period

Tenant-owned time period used to plan, record, accrue, and close work.

Canonical implementation:

work_periods

A Work Period contains:

Work Date
Period Code
Name
Start
End
Status

Work Period Status

Current lifecycle values:

PLANNING
INFORMED
ACCRUAL_OPEN
PARTIALLY_POSTED
FULLY_POSTED
CLOSED

PLANNING

Assignments are being planned.

INFORMED

Planned work has been communicated/locked into the informed stage.

ACCRUAL_OPEN

Period is open for accrual processing.

PARTIALLY_POSTED

Some accrual results have been posted.

FULLY_POSTED

All applicable accrual results have been posted.

CLOSED

Work Period lifecycle is closed.

Work Period Assignment

Assignment of a Collaborator to one Work Period.

Canonical implementation:

work_period_assignments

A Work Period Assignment includes:

Collaborator
Planned Status
Planning Availability
Actual Status
Sector
Location
Task
Replacement relationship
Active state

Planned Status

Planning decision for a Work Period Assignment.

Current values:

INCLUDED
EXCLUDED

Actual Status

Recorded actual outcome of a Work Period Assignment.

Current values:

WORKED
ABSENT
SICK_DAY_OFF
TIME_OFF
REPLACED
CANCELLED

Replacement Assignment

A Work Period Assignment serving as a replacement for another assignment.

Implementation relationship:

replacementForAssignmentId

Sector

Reference Data describing the operational sector associated with a Collaborator or Work Period Assignment.

Location

Reference Data describing the work/production location.

Task

Reference Data describing the work task.

13. Gold Production and Gold Price

Gold Production Entry

Tenant-owned record of produced gold for a Work Period, location, and date.

Canonical implementation:

gold_production_entries

Key value:

Gold Grams Produced

Gold Production can participate in earnings calculations.

Gold Price

Tenant-owned recorded BRL price per gram of gold for a specific date.

Canonical implementation:

gold_prices

Key value:

BRL per gram

Historical Gold Price rows are retained so financial calculations can preserve the price basis used at the time.

14. Expenses and Price List

Expense

A Tenant-scoped financial charge canonically owned by a Person + Tenant. The persisted record is expenses. person_id identifies the canonical Global Person owner and tenant_id identifies the Tenant provenance. collaborator_id identifies the Collaborator Journey associated with the Expense and is retained as provenance; it is not the enduring financial owner.

Canonical implementation:

expenses

An Expense includes:

Collaborator
Expense Category
Value Unit
Amount
Expense Date
Description
Active state

Depending on how it was created, it may also retain Price List and Gold Price calculation/audit information.

Expense Category

Reference Data identifying the business category of an Expense.

Value Unit

Reference Data defining the unit in which a financial amount is expressed.

Important current examples:

BRL
GOLD_GRAM

Price List Item

Tenant-owned reusable priced item used when creating certain Expenses.

Canonical implementation:

expense_price_list_items

Contains values such as:

Item Type
Code
Description
Unit Price BRL
Active state
Sort Order
Superseded Item

Price List history is preserved rather than destructively rewriting historical pricing.

Price List Supersession

Creation of a new active Price List Item version while preserving the previous item as historical/inactive data.

Gold-Converted Expense

Expense whose calculation uses a Gold Price to convert between BRL and gold-based value.

The Expense stores audit fields for the Gold Price and calculation used, so later Gold Price changes do not rewrite the historical transaction basis.

15. Earnings and Accruals

Earnings

Financial value earned by a Person in a Tenant through work performed during a Collaborator Journey. Earnings are produced through Work Period/Accrual processing and are posted as Person-owned Ledger Entry credits. The originating Collaborator Journey remains provenance, while canonical financial ownership is Person ID + Tenant ID.

Accrual

An individual calculated earnings result canonically owned by a Person + Tenant within an Accrual Run. person_id identifies the Global Person owner; collaborator_id identifies the Collaborator Journey whose work produced the accrual and is retained as provenance.

Accrual Run

Tenant-owned processing run for one Work Period.

Canonical implementation:

accrual_runs

Current statuses:

DRAFT
PENDING_INPUT
READY_TO_POST
POSTED
VOIDED

Accrual Item

Individual calculated result for one Collaborator within an Accrual Run.

Canonical implementation:

accrual_items

An Accrual Item may contain:

BRL amount
Gold Gram amount
Direction
Calculation Type
Status
Pending Reason

Accrual Item Status

Current values:

PENDING
READY
POSTED
SKIPPED

Pending Accrual Input

Required information missing before an Accrual Item can be finalized.

Current reasons include:

ACTUAL_OUTCOME_MISSING
GOLD_PRODUCTION_MISSING
PAYMENT_CONFIGURATION_MISSING
REPLACEMENT_RULE_DEFERRED
REPLACEMENT_ASSIGNMENT_MISSING

16. Current Account and Ledger

##Financial Ownership The canonical ownership relationship for ERS financial history. For Expenses, Accrual Items, Ledger Entries, and Ledger Receipts, enduring ownership is Person ID (global_people.id) + Tenant ID (tenants.id). A Collaborator Journey may remain referenced as provenance indicating the collaboration lifecycle that produced or contextualized the record, but the Journey is not the enduring financial owner.

Current Account

The Tenant-scoped financial ledger of a Person, canonically identified by Person ID + Tenant ID. It aggregates that Person's financial history across all historical Collaborator Journeys in the same Tenant. Individual Ledger Entries retain Collaborator Journey references as provenance. Do not confuse Current Account with Authentication Account.

Conceptually:

Global Person + Tenant
  -> Current Account
      -> Ledger Entries
          -> Credits
          -> Debits

Collaborator Journey
  -> provenance on individual Ledger Entries

The Current Account may track different Value Units such as BRL and GOLD_GRAM. Journey settlement remains Journey-scoped even though the Current Account itself is Person + Tenant scoped.

Ledger Entry

A persisted financial posting canonically owned by a Person + Tenant. person_id identifies the Global Person owner and tenant_id identifies the Tenant. collaborator_id identifies the originating or contextual Collaborator Journey and is retained as provenance.

Canonical implementation:

ledger_entries

A Ledger Entry identifies:

Person
Tenant
Collaborator Journey provenance
Value Unit
Entry Type
Direction
Amount
Effective Date
Source Type
Source ID
Description
Active state
Correction metadata
Authorization/approval metadata

Credit

Ledger direction increasing the Person's Tenant-scoped Current Account balance in the applicable Value Unit.

Canonical value:

CREDIT

Debit

Ledger direction decreasing the Person's Tenant-scoped Current Account balance in the applicable Value Unit.

Canonical value:

DEBIT

A debit must have exactly one receipt obligation.

Ledger Source

Business record or process that caused a Ledger Entry.

Examples include:

EXPENSE
EXPENSE_REPLACEMENT
JOURNEY_SETTLEMENT
LEDGER_CORRECTION
ACCRUAL_ITEM
WORK_PERIOD_ASSIGNMENT

Not every source type applies to every workflow.

Ledger Correction

Audited correction of an existing Ledger Entry.

A correction can produce:

Original
Reversal
Replacement

rather than mutating history invisibly.

Correction Reason

Required explanation/code documenting why a sensitive financial correction or settlement is performed.

17. Receipts

Ledger Receipt

A Person + Tenant-owned receipt obligation associated with exactly one Current Account debit Ledger Entry. The Ledger Receipt carries the same Person ID, Tenant ID, and Collaborator Journey provenance as its Ledger Entry.

Canonical implementation:

ledger_receipts

Rule:

Every debit Ledger Entry must have exactly one Ledger Receipt obligation.

Receipt Obligation

Business requirement to issue, obtain, and return documentation for a Current Account debit.

The Ledger Receipt is the persisted record implementing the obligation.

Outstanding Receipt

Receipt that has not yet reached a terminal returned/cancelled state and still requires operational action.

Current outstanding statuses:

PENDING_ISSUE
ISSUED
PRINTED
SIGNED

Receipt Status

Current lifecycle values include:

PENDING_ISSUE
ISSUED
PRINTED
SIGNED
RETURNED
CANCELLED

PENDING_ISSUE

Receipt obligation exists but has not yet been issued.

ISSUED

Receipt has been issued.

PRINTED

Receipt has been printed.

SIGNED

Receipt has been signed but has not yet completed the returned workflow.

RETURNED

Signed receipt has been returned and accepted.

RETURNED is terminal.

CANCELLED

Receipt obligation has been cancelled with required audit information.

CANCELLED is terminal.

Signed Document Reference

Reference to the returned signed receipt document.

Required for the receipt-return workflow.

18. Settlements and Journey Closure

Journey Settlement

Persisted financial settlement associated with a Collaborator Journey.

Canonical implementation:

journey_settlements

May record:

Settlement Type
Request ID
Status
Effective Date
BRL Amount
Gold Gram Amount
Reason
Authorization
Second approval

Settlement Preview

Pre-close evaluation showing whether a Collaborator Journey can be closed.

Current blockers include:

JOURNEY_ALREADY_CLOSED
NEGATIVE_BALANCE
PENDING_ACCRUALS
OUTSTANDING_RECEIPTS

Partial Payout

Settlement operation paying part of a positive BRL and/or GOLD_GRAM Current Account balance.

Zero Gold

Settlement operation used to resolve/zero applicable gold balance under the supported audited workflow.

Journey Close

Final settlement operation that closes a Collaborator Journey after all closure invariants are satisfied.

A Journey cannot be closed while required blockers remain unresolved.

19. Second-Person Approval

Second-Person Approval

Operational control requiring a second authorized person to approve certain sensitive financial actions.

It is separate from ordinary Role authorization.

A user may have permission to initiate an operation while the configured policy still requires another authorized person to approve it.

Second-Person Approval Policy

Tenant setting controlling whether applicable sensitive financial operations require second-person approval.

20. Active, Inactive, and Historical Records

Active

Entity is currently available for its normal operational purpose.

The exact consequence depends on entity type.

Examples:

ACTIVE Authentication Account
-> may authenticate

ACTIVE Actor
-> may participate in Actor resolution

ACTIVE Membership
-> Person currently belongs to Tenant

ACTIVE Tenant
-> normal tenant writes allowed

ACTIVE Role Grant
-> contributes delegated authority

ACTIVE Price List Item
-> available for new selection

Do not assume “active” has one universal side effect.

Inactive

Entity is retained but not currently available for its normal operational purpose.

ERS generally prefers deactivation over hard deletion so history remains auditable.

Historical Record

Persisted record retained to preserve past business/audit meaning even though it is no longer active.

Examples include:

  • inactive Role Grants;
  • superseded Price List Items;
  • historical Collaborator Journeys;
  • prior Gold Prices;
  • corrected Ledger Entries;
  • inactive Tenant records.

21. Important Identity Shapes

Person-Only Account

Ordinary Authentication Account representing a Person who is not currently a Collaborator and has no delegated operator/admin Roles.

Typical shape:

ACTIVE Authentication Account
-> Person
-> zero currently usable Tenant Actors
-> base Person self-service remains available

Person self-service authority is intrinsic.

Current Account should clarify that a Person may inspect their own read-only Current Account without an active Tenant Actor or ACTIVE Membership. The records retain their original Tenant provenance.

Single-Tenant Account

Authentication Account with exactly one currently usable Tenant context.

Typical shape:

one ACTIVE Authentication Account
-> exactly one usable Tenant Actor
-> one ACTIVE same-tenant Membership

“Single-Tenant” describes Tenant cardinality, not a Role.

Multi-Tenant Account

Ordinary Authentication Account with usable Tenant Actors in more than one Tenant.

Typical shape:

one ACTIVE Authentication Account
-> Tenant A Actor
-> Tenant B Actor
-> ...

Each Tenant Actor requires its own same-tenant ACTIVE Membership.

Disposable Test Account

Manual/E2E test identity intentionally safe to mutate, deactivate, reactivate, or otherwise change.

“Disposable” is a testing characteristic, not a production domain type.

22. Important Distinctions

Person vs Authentication Account

Person
= business identity of the human

Authentication Account
= login/authentication identity

A Person can exist without an Authentication Account.

Authentication Account vs Actor

Authentication Account
= who authenticated

Actor
= authorization identity used in a specific operating scope

One ordinary Authentication Account can own multiple Tenant Actors.

Actor vs Role

Actor
= identity receiving authority

Role
= bundle of delegated Permissions

An Actor may have zero or more active Role Grants.

Actor vs Membership

Actor
= authorization identity

Membership
= Person’s relationship to one Tenant

A Tenant Actor for an ordinary Person relies on a same-tenant ACTIVE Membership.

Authentication vs Authorization

Authentication:
Who logged in?

Authorization:
What may the resolved Current Actor do?

Tenant Selection vs Authorization Grant

Tenant Selection
= choose which valid Authentication Account-owned Tenant Actor becomes effective

Role Grant
= delegate additional authority to an Actor

Selecting a Tenant does not grant a Role.

Person Self-Service vs Delegated Role

Person self-service

Authentication Account -> Person -> base intrinsic own-resource self-service

It does not require an ACTIVE Tenant Actor or ACTIVE Person–Tenant Membership.

TENANT_ADMIN / EARNINGS_OPERATOR / EXPENSE_OPERATOR
= delegated authority

Authentication Account vs Current Account

Authentication Account
= security/login concept

Current Account
= Collaborator financial ledger

Never use “Account” alone when both could be relevant.

Tenant ID default vs Role Grant *

default
= real Tenant ID

*
= application-global Role Grant target

They are not equivalent.

23. Transitional / Legacy Terms

Legacy Person

Temporary tenant-owned people record retained during Bite 30 migration.

Use only when explicitly discussing compatibility.

Primary Actor

Legacy/default Actor pointer retained during the multi-Actor cutover.

Not authoritative for new Tenant selection rules.

PERSON Role

Deprecated historical Role.

Do not use it to describe current Person self-service authority.

Actor Headers

Historical/test/bootstrap mechanisms that allowed Actor identity to be supplied through request headers.

Normal application traffic now derives identity from:

Authentication Account Session
+
selected Tenant
+
persisted Account–Actor binding

The browser does not choose its authorization Actor directly.

24. Canonical Manual-Test Record Format

When recording an ordinary Bite 30 identity, use this format.

Single-Tenant Identity

Login:
Person ID:
Authentication Account ID:

Tenant ID:
Actor ID:
Actor Key:
Membership ID:

Delegated Roles:

Multi-Tenant Identity

Login:
Person ID:
Authentication Account ID:

Tenant A ID:
Tenant A Actor ID:
Tenant A Actor Key:
Tenant A Membership ID:

Tenant B ID:
Tenant B Actor ID:
Tenant B Actor Key:
Tenant B Membership ID:

Delegated Roles:

Application Administrator Identity

Login:
Authentication Account ID:

Actor ID:
Actor Key:
Account–Actor Binding Scope: GLOBAL
Current Actor Scope: APPLICATION
Role: APPLICATION_ADMIN

Do not record a Tenant Actor or Membership for the Application Administrator unless a later architecture explicitly introduces one.

25. Canonical Relationship Diagrams

Ordinary Single-Tenant Person

Person
  |
  +-- Person–Tenant Membership -> Tenant A
  |
  +-- Authentication Account
        |
        +-- TENANT Account–Actor Binding
              |
              +-- Actor A
              +-- Tenant A
              +-- Membership A

Ordinary Multi-Tenant Person

Person
  |
  +-- Membership A -> Tenant A
  |
  +-- Membership B -> Tenant B
  |
  +-- Authentication Account
        |
        +-- Actor A
        |     TENANT binding
        |     Tenant A
        |     Membership A
        |
        +-- Actor B
              TENANT binding
              Tenant B
              Membership B

Bite 30E Tenant switching:

same Authentication Account
same Session

select Tenant A -> Actor A
select Tenant B -> Actor B

Application Administrator

Authentication Account
  |
  +-- GLOBAL Account–Actor Binding
        |
        +-- Application Actor
              |
              +-- APPLICATION_ADMIN Role Grant
                    |
                    +-- Tenant target = *

Current effective scope:

APPLICATION

Person Becoming a Collaborator

Person
  |
  +-- Person–Tenant Membership
  |     |
  |     +-- Collaborator Journey
  |           |
  |           +-- Work Period Assignments
  |           +-- Journey Settlement
  |           +-- financial-record provenance
  |
  +-- Person + Tenant Financial Ownership
        |
        +-- Earnings / Accrual Items
        +-- Expenses
        +-- Current Account / Ledger Entries
        +-- Ledger Receipts

26. Naming Rules for Future ERS Requirements and Tests

  1. Write Authentication Account, not merely “Account,” when referring to login identity.
  2. Write Current Account for the Person's Tenant-scoped financial ledger. Do not describe the Collaborator Journey as the enduring owner of a Current Account.
  3. Write Person ID only for global_people.id.
  4. Write Legacy Person ID when explicitly referring to people.id.
  5. Write Actor ID for authz_actors.id.
  6. When an API says actorRecordId, write actorRecordId (Actor ID).
  7. Write Actor Key for authz_actors.actor_key.
  8. Write Membership ID for person_tenant_memberships.id.
  9. Write Tenant ID for tenants.id; do not substitute Tenant name or code.
  10. Write Collaborator ID for the current persisted Collaborator Journey ID.
  11. Write Financial Ownership as Person ID + Tenant ID. Treat Collaborator ID on Expense, Accrual Item, Ledger Entry, and Ledger Receipt records as Collaborator Journey provenance, not enduring financial ownership.
  12. In Collaborator Journey APIs, write Membership ID for membershipId; it identifies person_tenant_memberships.id and is the canonical parent of the Journey.
  13. In Collaborator Journey APIs, personId means Person ID and identifies global_people.id.
  14. In Collaborator Journey APIs, legacyPersonId means Legacy Person ID and identifies people.id.
  15. Distinguish Authentication from Authorization.
  16. Distinguish Intrinsic Authority from Delegated Authority.
  17. Distinguish GLOBAL binding scope from APPLICATION effective scope.
  18. Treat * as an application-global Role Grant target, never as a Tenant.
  19. Do not use the deprecated PERSON Role to explain current Person self-service.
  20. For every manual-test identity, state the complete shape explicitly: 
    Authentication Account
-> Actor(s)
-> Membership(s)
-> Delegated Role state
-> Collaborator state, when relevant
  21. When a test mutates an identity, state whether the identity is stable or disposable.
  22. When exact identifiers matter, provide or generate them before the test begins rather than asking the tester to discover them during execution.

27. Quick Reference

Canonical Term Implementation / API Meaning
Person ID global_people.id Global human identity
Legacy Person ID people.id Transitional tenant-owned Person projection
Authentication Account ID auth_user_accounts.id Login identity
Login auth_user_accounts.login Normalized authentication login
Membership ID person_tenant_memberships.id Person ↔ Tenant relationship
Tenant ID tenants.id Immutable Tenant identifier
Actor ID authz_actors.id Persisted authorization Actor
actorRecordId (Actor ID) Current Actor API Same authz_actors.id
Actor Key authz_actors.actor_key Semantic Actor key
Account–Actor Binding auth_account_actors Authentication Account owns Actor
Binding Scope GLOBAL / TENANT Authentication Account–Actor relationship scope
Current Actor Scope APPLICATION / TENANT Effective authorization scope
Collaborator ID collaborator_journeys.id Current Collaborator Journey identifier
Collaborator Journey Membership ID membershipId / person_tenant_memberships.id Canonical Person–Tenant Membership parent of the Collaborator Journey
Collaborator Journey Person ID personId / global_people.id Canonical Global Person ID returned by Collaborator APIs
Collaborator Journey Legacy Person ID legacyPersonId / people.id Transitional tenant-owned Person compatibility identifier
Role authz_roles Delegated Permission bundle
Role Grant authz_actor_role_grants Role assigned to Actor
Permission authz_permissions Fine-grained allowed operation
Session auth_sessions Authentication Account session
Selected Tenant ers.auth.selectedTenantId Browser-selected Tenant ID
Tenant Selection Header X-Tenant-ID Server-validated Tenant-selection hint
Current Account ledger_entries projection/workflow Collaborator financial ledger
Work Period work_periods Planned/actual work period
Work Period Assignment work_period_assignments Collaborator assignment to period
Gold Production Entry gold_production_entries Gold produced by period/location/date
Gold Price gold_prices BRL-per-gram price record
Expense expenses.person_id + expenses.tenant_id Person + Tenant-owned financial charge; collaborator_id is Journey provenance
Price List Item expense_price_list_items Reusable priced Expense item
Accrual Run accrual_runs Work-period earnings calculation run
Accrual Item accrual_items.person_id + accrual_items.tenant_id Person + Tenant-owned earnings calculation result; collaborator_id is Journey provenance
Ledger Entry ledger_entries.person_id + ledger_entries.tenant_id Person + Tenant-owned Current Account posting; collaborator_id is Journey provenance
Ledger Receipt ledger_receipts.person_id + ledger_receipts.tenant_id Person + Tenant-owned receipt obligation matching its Ledger Entry
Journey Settlement journey_settlements Audited Collaborator Journey settlement
Reference Data reference_data Tenant-owned coded lookup values
Tenant Setting tenant_settings Tenant configuration value

28. Glossary Maintenance Rule

This glossary should be treated as a living application contract.

Whenever an implementation refactor introduces a new term or changes the meaning of an existing term:

  1. decide whether the domain concept actually changed;
  2. preserve the canonical term if only the implementation field changed;
  3. document the implementation alias explicitly;
  4. update this glossary before writing new manual tests that use the changed terminology.

The goal is that requirements, UI labels, manual tests, diagnostic scripts, API discussions, and implementation explanations all use the same domain vocabulary. ::: ​​

Emergency Administrative Access Recovery: A controlled, auditable procedure for restoring authorized Production administration when no usable Application Administrator credentials are available.