doc: Add power group design document and naming rationale

Document current implementation: primary_influencer_only, constraint
model, hierarchy algorithm, BRREG roles, import flow.

Add naming rationale: "Power Group" replaces "Enterprise Group" because
the EU term confuses Enterprise (economic grouping) with Enterprise Group
(political control hierarchy). Control defines the tree, ownership
enriches the graph.

Document future directions: multi-root PGs, set-import, activity
aggregation, public/private influence analysis.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jhf

doc/DOMAIN-MODELS.md

@@ -1,10 +1,68 @@
 # STATBUS Domain Models
 
-The Formal Economy is modeled as
-<img src="./diagrams/domains-formal.svg" alt="Domain Models Formal Economy" style="max-width:100%; max-height:300px;">
+## Overview
+
+STATBUS organizes data into distinct domains based on what we **observe** versus what we **derive/label**:
+
+| Domain | Nature | Temporal? | Example |
+|--------|--------|-----------|---------|
+| **Legal** | Observed from registries, contracts | Yes | Legal Unit, Legal Relationship |
+| **Physical** | Observed in the real world | Yes | Establishment |
+| **Statistical** | Derived artifact for statistics | No | Enterprise |
+| **Political** | Derived from ownership structures | No | Power Group |
+
+### Key Insight
+
+**Temporal entities** (Legal Unit, Establishment, Legal Relationship) represent things we observe over time - they have `valid_from`, `valid_to`, and history.
+
+**Non-temporal entities** (Enterprise, Power Group) are statistical/analytical artifacts that **emerge from** temporal observations. They don't have independent temporal existence - their "state at time T" is derived from the temporal entities that reference them.
+
+## Formal Economy
+
+<img src="./diagrams/domains-formal.svg" alt="Domain Models Formal Economy" style="max-width:100%; max-height:400px;">
+
+### Relationships
+
+- **Legal Unit → Enterprise**: Every LU belongs to exactly one EN (always)
+- **Legal Relationship → Power Group**: Each controlling relationship (≥50%) belongs to a PG
+- **Legal Relationship → Legal Unit**: Tracks ownership/control between LUs (`influencing_id` owns/controls `influenced_id`)
+- **Establishment → Legal Unit**: Every ES belongs to exactly one LU
+
+Note: Power group membership of a Legal Unit is derived through `legal_relationship` - an LU is in a power group if it participates in any relationship (as influencer or influenced) that has a `power_group_id`.
+
+### Domain Details
+
+**Legal Domain** (observed, temporal):
+- `legal_unit` - A legally registered entity (company, organization)
+- `legal_relationship` - Ownership/control relationship between two legal units
+  - `influencing_id` → `influenced_id` (influencer owns/controls influenced)
+  - `percentage` - ownership/control percentage (≥50% = controlling interest)
+  - `power_group_id` - assigned by worker when relationship forms a controlling cluster
+
+**Physical Domain** (observed, temporal):
+- `establishment` - A physical location where economic activity occurs
+
+**Statistical Domain** (derived, non-temporal):
+- `enterprise` - The smallest combination of legal units that is an organizational unit producing goods or services
+
+**Political Domain** (derived, non-temporal):
+- `power_group` - A hierarchy of legal units connected by controlling ownership (≥50%)
+- Power groups are **TIMELESS** - once created, they exist forever as a registry entry
+- Active status is **derived** at query time from `legal_relationship.valid_range`
+- The `power_group_id` lives on `legal_relationship`, not `legal_unit`
+
+## Informal Economy
 
-The Informal Economy is modeled as
 <img src="./diagrams/domains-informal.svg" alt="Domain Models Informal Economy" style="max-width:100%; max-height:300px;">
 
 In the informal economy the establishment is directly assigned to an enterprise, because there
 is lacking stable identifiers, such as a tax registration.
+
+## Why This Matters
+
+The domain model clarifies:
+
+1. **What we observe**: Legal registrations, physical locations, ownership records (temporal)
+2. **What we derive**: Statistical groupings, power hierarchies (non-temporal)
+3. **Data integrity**: Temporal entities need history tracking; derived entities need consistency with their sources
+4. **Query patterns**: Historical queries traverse temporal entities; current-state queries can use derived entities directly

doc/data-architecture.md

@@ -0,0 +1,21 @@
+# STATBUS Data Architecture
+
+## Three Layers
+
+1. **Import** — writes data to base tables (`legal_unit`, `establishment`, `legal_relationship`, `power_group`, `enterprise`, etc.)
+
+2. **statistical_unit** — derived high-speed view of base table data, convenient for queries and aggregations. Built from `timepoints → timesegments → timeline_* → statistical_unit`.
+
+3. **Reports** — high-speed reporting derived from `statistical_unit`: `statistical_*_history`, `statistical_*_facet`, etc.
+
+## Key Invariant
+
+All derived tables (layers 2 and 3) can be **cleared and recreated** from base tables at any time. The derive pipeline is idempotent — running it produces the same result regardless of prior state.
+
+## Consequence for Pipeline Design
+
+- Only **import** modifies base tables.
+- `derive_statistical_unit` **reads** base tables and writes derived tables.
+- `derive_reports` **reads** `statistical_unit` and writes report tables.
+
+Any operation that creates or modifies base table records (e.g., creating `power_group` records, setting `legal_relationship.power_group_id`) belongs in the **import** layer, not in the analytics pipeline.

doc/data-model.md

@@ -8,26 +8,37 @@ This document provides a compact overview of the StatBus database schema, focusi
 ## Core Statistical Units (Hierarchy)
 The system revolves around four main statistical units, often with temporal validity (`valid_from`, `valid_after`, `valid_to`):
 
-- `enterprise_group(id, short_name, name, enterprise_group_type_id, reorg_type_id, edit_by_user_id, unit_size_id, data_source_id, foreign_participation_id, valid_range, valid_from, valid_to, valid_until, edit_at, contact_person, edit_comment, reorg_references, reorg_date)` (EG) (temporal)
-  - Key FKs: data_source_id, edit_by_user_id, enterprise_group_type_id, foreign_participation_id, reorg_type_id, unit_size_id.
-- `enterprise(id, short_name, edit_by_user_id, edit_at, enabled, edit_comment)` (EN)
-  - Key FKs: edit_by_user_id.
-- `legal_unit(id, short_name, name, sector_id, status_id, legal_form_id, edit_by_user_id, unit_size_id, foreign_participation_id, data_source_id, enterprise_id, image_id, valid_range, valid_from, valid_to, valid_until, edit_at, birth_date, death_date, free_econ_zone, edit_comment, primary_for_enterprise)` (LU) (temporal)
-  - Key FKs: data_source_id, edit_by_user_id, enterprise_id, foreign_participation_id, image_id, legal_form_id, sector_id, status_id, unit_size_id.
 - `establishment(id, short_name, name, sector_id, status_id, edit_by_user_id, unit_size_id, data_source_id, enterprise_id, legal_unit_id, image_id, valid_range, valid_from, valid_to, valid_until, edit_at, birth_date, death_date, free_econ_zone, edit_comment, primary_for_legal_unit, primary_for_enterprise)` (EST) (temporal)
   - Key FKs: data_source_id, edit_by_user_id, enterprise_id, image_id, legal_unit_id, sector_id, status_id, unit_size_id, valid_range.
+- `legal_unit(id, short_name, name, sector_id, status_id, legal_form_id, edit_by_user_id, unit_size_id, foreign_participation_id, data_source_id, enterprise_id, image_id, valid_range, valid_from, valid_to, valid_until, edit_at, birth_date, death_date, free_econ_zone, edit_comment, primary_for_enterprise)` (LU) (temporal)
+  - Key FKs: data_source_id, edit_by_user_id, enterprise_id, foreign_participation_id, image_id, legal_form_id, sector_id, status_id, unit_size_id.
+- `enterprise(id, short_name, edit_by_user_id, edit_at, enabled, edit_comment)` (EN)
+  - Key FKs: edit_by_user_id.
+- `power_group(id, ident, short_name, name, type_id, unit_size_id, data_source_id, foreign_participation_id, edit_by_user_id, edit_at, contact_person, edit_comment)` (PG)
+  - Key FKs: data_source_id, edit_by_user_id, foreign_participation_id, type_id, unit_size_id.
+
+## Legal Unit Ownership & Control
+Tables and views for tracking ownership/control relationships between legal units:
+
+- `legal_relationship(id, type_id, reorg_type_id, power_group_id, influencing_id, influenced_id, edit_by_user_id, valid_range, valid_from, valid_to, valid_until, edit_at, primary_influencer_only, percentage, edit_comment)` (temporal)
+  - Key FKs: edit_by_user_id, influenced_id, influencing_id, power_group_id, primary_influencer_only, reorg_type_id, type_id, type_id, valid_range, valid_range.
+- `legal_unit_power_hierarchy(path, legal_unit_id, root_legal_unit_id, valid_range, power_level, is_cycle)`
+- `power_group_def(root_legal_unit_id, depth, width, reach)`
+- `legal_relationship_cluster(legal_relationship_id, root_legal_unit_id)`
+- `power_group_active(id, ident, short_name, name, type_id)`
+- `power_group_membership(power_group_ident, power_group_id, legal_unit_id, valid_range, power_level)`
 
-## Common Links for Core Units (EG, EN, LU, EST)
+## Common Links for Core Units (PG, EN, LU, EST)
 These tables link to any of the four core statistical units:
 
-- `external_ident(id, type_id, ident, idents, labels, establishment_id, legal_unit_id, enterprise_id, enterprise_group_id, edit_by_user_id, edit_at, shape, edit_comment)`
+- `external_ident(id, type_id, ident, idents, labels, establishment_id, legal_unit_id, enterprise_id, power_group_id, edit_by_user_id, edit_at, shape, edit_comment)`
   - Key FKs: edit_by_user_id, enterprise_id, type_id.
   - Enums: `shape` (`public.external_ident_shape`).
 - `image(id, type, uploaded_by_user_id, uploaded_at, data)`
   - Key FKs: uploaded_by_user_id.
-- `tag_for_unit(id, tag_id, establishment_id, legal_unit_id, enterprise_id, enterprise_group_id, edit_by_user_id, created_at, edit_at, edit_comment)`
+- `tag_for_unit(id, tag_id, establishment_id, legal_unit_id, enterprise_id, power_group_id, edit_by_user_id, created_at, edit_at, edit_comment)`
   - Key FKs: edit_by_user_id, enterprise_id, tag_id.
-- `unit_notes(id, notes, establishment_id, legal_unit_id, enterprise_id, enterprise_group_id, edit_by_user_id, created_at, edit_at, edit_comment)`
+- `unit_notes(id, notes, establishment_id, legal_unit_id, enterprise_id, power_group_id, edit_by_user_id, created_at, edit_at, edit_comment)`
   - Key FKs: edit_by_user_id, enterprise_id.
 - `enterprise_external_idents(unit_type, external_idents, unit_id, valid_from, valid_to, valid_until)` (temporal)
   - Enums: `unit_type` (`public.statistical_unit_type`).
@@ -79,13 +90,13 @@ These tables link to any of the four core statistical units:
 These tables typically store codes, names, and flags for `custom` and `enabled` status.
 
 - `data_source(id, code, name, created_at, updated_at, enabled, custom)`
-- `enterprise_group_type(id, code, name, created_at, updated_at, enabled, custom)`
-- `enterprise_group_role(id, code, name, created_at, updated_at, enabled, custom)`
+- `power_group_type(id, code, name, created_at, updated_at, enabled, custom)`
 - `external_ident_type(id, code, name, labels, enabled, shape, description, priority)`
   - Enums: `shape` (`public.external_ident_shape`).
 - `foreign_participation(id, code, name, created_at, updated_at, enabled, custom)`
 - `legal_form(id, code, name, created_at, updated_at, enabled, custom)`
-- `reorg_type(id, code, name, created_at, updated_at, enabled, description, custom)`
+- `legal_reorg_type(id, code, name, created_at, updated_at, enabled, description, custom)`
+- `legal_rel_type(id, code, name, created_at, updated_at, enabled, description, primary_influencer_only, custom)`
 - `sector(id, path, label, code, name, parent_id, created_at, updated_at, enabled, description, custom)`
 - `status(id, code, name, created_at, updated_at, enabled, assigned_by_default, used_for_counting, priority, custom)`
 - `tag(id, path, label, code, name, type, parent_id, context_valid_on, created_at, updated_at, enabled, level, description, context_valid_from, context_valid_to, context_valid_until)`
@@ -106,7 +117,7 @@ Enumerated types used across the schema, with their possible values.
 - **`public.import_data_column_purpose`**: `source_input`, `internal`, `pk_id`, `metadata`
 - **`public.import_data_state`**: `pending`, `analysing`, `analysed`, `processing`, `processed`, `error`
 - **`public.import_job_state`**: `waiting_for_upload`, `upload_completed`, `preparing_data`, `analysing_data`, `waiting_for_review`, `approved`, `rejected`, `processing_data`, `failed`, `finished`
-- **`public.import_mode`**: `legal_unit`, `establishment_formal`, `establishment_informal`, `generic_unit`
+- **`public.import_mode`**: `legal_unit`, `establishment_formal`, `establishment_informal`, `generic_unit`, `legal_relationship`
 - **`public.import_row_action_type`**: `use`, `skip`
 - **`public.import_row_operation_type`**: `insert`, `replace`, `update`
 - **`public.import_source_expression`**: `now`, `default`
@@ -121,7 +132,7 @@ Enumerated types used across the schema, with their possible values.
 - **`public.stat_frequency`**: `daily`, `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semesterly`, `yearly`
 - **`public.stat_type`**: `int`, `float`, `string`, `bool`
 - **`public.statbus_role`**: `admin_user`, `regular_user`, `restricted_user`, `external_user`
-- **`public.statistical_unit_type`**: `establishment`, `legal_unit`, `enterprise`, `enterprise_group`
+- **`public.statistical_unit_type`**: `establishment`, `legal_unit`, `enterprise`, `power_group`
 - **`public.tag_type`**: `custom`, `system`
 - **`public.time_context_type`**: `relative_period`, `tag`, `year`
 - **`worker.pipeline_phase`**: `is_deriving_statistical_units`, `is_deriving_reports`
@@ -199,7 +210,7 @@ Handles background processing. A long-running worker process calls `worker.proce
   - Key FKs: queue.
   - Enums: `phase` (`worker.pipeline_phase`).
 - `queue_registry(queue, description, default_concurrency)`
-- `pipeline_progress(updated_at, phase, step, total, completed, affected_establishment_count, affected_legal_unit_count, affected_enterprise_count)`
+- `pipeline_progress(updated_at, phase, step, total, completed, affected_establishment_count, affected_legal_unit_count, affected_enterprise_count, affected_power_group_count)`
   - Enums: `phase` (`worker.pipeline_phase`).
 - `base_change_log(establishment_ids, legal_unit_ids, enterprise_ids, edited_by_valid_range)`
 - `base_change_log_has_pending(has_pending)`