164 lines
6.1 KiB
Markdown
164 lines
6.1 KiB
Markdown
# 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. |