TenantAtlas/specs/242-operational-controls/data-model.md

Data Model — Operational Controls

Spec: 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.