# Data Model — Operational Controls

**Spec**: [spec.md](spec.md)

The first operational-controls slice adds one persisted runtime-safety record and two derived runtime concepts. It reuses existing execution and audit truth.

## Existing Canonical Entities Reused

### Workspace (`workspaces`)

**Purpose**: Existing workspace boundary for targeted operational-control scope.

**Key fields (existing)**:
- `id`
- `name`

**Feature use**:
- Identifies the workspace targeted by a workspace-scoped control activation.
- Continues to anchor workspace isolation and audit scope.

### Tenant (`tenants`)

**Purpose**: Existing tenant boundary for the affected execution surfaces.

**Key fields (existing)**:
- `id`
- `workspace_id`
- `name`
- `external_id`

**Feature use**:
- Supplies workspace context for findings and restore execution checks.
- Does not own control records in this slice.

### PlatformUser (`platform_users` or equivalent platform-authenticated user model)

**Purpose**: Existing platform-plane actor for control management.

**Feature use**:
- Owns pause/resume actions in the system plane.
- Supplies actor identity for audit and attribution on control changes.

### OperationRun (`operation_runs`)

**Purpose**: Existing canonical execution truth for in-scope starts when execution is allowed.

**Key fields (existing)**:
- `id`
- `workspace_id`
- `tenant_id`
- `type`
- `status`
- `outcome`
- `context`

**Feature use**:
- Remains the only execution truth for allowed starts.
- Must not be created when an in-scope start is blocked by an active control.
- Existing queued or historical `OperationRun` records remain unchanged when a later control activation blocks only new starts.

### RestoreRun (`restore_runs`)

**Purpose**: Existing restore execution truth for queued restore work.

**Feature use**:
- No new queued execution `RestoreRun` is created by a blocked `restore.execute` start path.
- Continues to link to `OperationRun` only when execution is allowed.

### AuditLog (`audit_logs`)

**Purpose**: Existing audit truth for control changes and blocked execution evidence.

**Feature use**:
- Records pause, update, resume, and blocked-execution events with stable action IDs.
- Avoids introducing a second historical record model for the first slice.

## New Persisted Entity

### OperationalControlActivation (`operational_control_activations`)

**Purpose**: The active runtime-safety record that pauses one bounded control key for either all workspaces or one specific workspace.

**Key fields**:
- `id`
- `control_key` — bounded to the first-slice catalog keys `findings.lifecycle.backfill` and `restore.execute`
- `scope_type` — `global` or `workspace`
- `workspace_id` — nullable; required when `scope_type = workspace`
- `reason_text`
- `expires_at` — nullable
- `created_by_platform_user_id`
- `updated_by_platform_user_id` — nullable
- `created_at`
- `updated_at`

**Display rule**:
- `owner` on the controls surface resolves to `updated_by_platform_user_id` when present, otherwise `created_by_platform_user_id`.

**Constraints**:
- At most one active row per `control_key + scope_type + workspace_id` combination.
- `workspace_id` must be null for `global` scope and present for `workspace` scope.
- Expired rows are ignored by the evaluator.
- PostgreSQL uniqueness is enforced with partial unique indexes: one active global row per `control_key` where `scope_type = global`, and one active workspace row per `control_key + workspace_id` where `scope_type = workspace`.
- Writes must delete expired conflicting rows before inserting a new activation so ignored expired rows do not block a new active pause.

**Lifecycle**:
- Created when a control is paused.
- Updated when reason or expiry changes.
- Expired rows are deleted by the write path before a replacement activation for the same control/scope is inserted.
- Removed when the control is resumed.
- No explicit `enabled` rows are stored; enabled is derived from no active matching row.

**Relationships**:
- Optionally `belongsTo Workspace`
- `createdBy` / `updatedBy` platform-user relations if the existing platform-user model supports them

## Derived Runtime Entities

### OperationalControlDefinition (derived, not persisted)

**Purpose**: Catalog metadata for one controllable risky action.

**Proposed runtime fields**:
- `key`
- `label`
- `supported_scopes`
- `operation_types`
- `affected_surfaces`
- `default_state` (derived `enabled`)

**Feature use**:
- Drives the controls page and evaluator without turning the catalog into a user-managed taxonomy.

### OperationalControlDecision (derived, not persisted)

**Purpose**: The evaluated result returned to an affected surface or service start seam.

**Proposed runtime fields**:
- `control_key`
- `effective_state` — `enabled` or `paused`
- `matched_scope_type` — `global`, `workspace`, or `none`
- `workspace_id` — nullable
- `reason_text` — nullable when enabled
- `expires_at` — nullable
- `source_activation_id` — nullable

**Feature use**:
- Tells a surface whether execution may proceed.
- Supplies one shared reason for blocked-state messaging and audit context.

## Evaluation Rules

- The evaluator resolves workspace context before checking control scope.
- A matching global activation wins over a workspace activation in v1. Workspace-scoped activations only take effect when no active global activation exists for the same control.
- Expired activations do not block execution.
- Missing entitlement or missing capability is resolved before control-state disclosure on tenant/admin surfaces.

## Data Ownership Notes

- No tenant-owned control records are introduced in the first slice.
- Control activations are platform-operated runtime-safety truth.
- Global control changes audit as platform-plane events with null workspace/tenant ownership.
- Workspace-targeted changes and blocked execution events with concrete workspace/tenant context retain truthful workspace/tenant audit scope.
- Blocked system-plane all-tenant attempts audit as platform-plane events with null workspace/tenant ownership plus requested-scope metadata.
- Tenant/admin surfaces consume only the derived decision, never direct activation editing.