TenantAtlas/specs/101-golden-master-baseline-governance-v1/data-model.md

# Phase 1 — Data Model

This is the proposed data model for **101 — Golden Master / Baseline Governance v1**.

## Ownership Model

- **Workspace-owned**
  - Baseline profiles
  - Baseline snapshots + snapshot items (data-minimized, reusable across tenants)

- **Tenant-owned**
  - Tenant assignments (joins a tenant to the workspace baseline standard)
  - Operation runs for capture/compare
  - Findings produced by compares

This follows constitution SCOPE-001 conventions: tenant-owned tables include `workspace_id` + `tenant_id` NOT NULL; workspace-owned tables include `workspace_id` and do not include `tenant_id`.

## Entities

## 1) baseline_profiles (workspace-owned)

**Purpose**: Defines the baseline (“what good looks like”) and its scope.

**Fields**
- `id` (pk)
- `workspace_id` (fk workspaces, NOT NULL)
- `name` (string, NOT NULL)
- `description` (text, nullable)
- `version_label` (string, nullable)
- `status` (string enum: `draft|active|archived`, NOT NULL)
- `scope_jsonb` (jsonb, NOT NULL)
  - v1 schema: `{ "policy_types": ["string", ...] }` — array of policy type keys from `InventoryPolicyTypeMeta`
  - An empty array means "all types" (no filtering); each string must be a known policy type key
  - Future versions may add additional filter dimensions (e.g., `platforms`, `tags`)
- `active_snapshot_id` (fk baseline_snapshots, nullable)
- `created_by_user_id` (fk users, nullable)
- timestamps

**Indexes/constraints**
- index: `(workspace_id, status)`
- uniqueness: `(workspace_id, name)` (optional but recommended if UI expects names unique per workspace)

**Validation notes**
- status transitions: `draft ↔ active → archived` (archived is terminal in v1; deactivate returns active → draft)

## 2) baseline_snapshots (workspace-owned)

**Purpose**: Immutable baseline snapshot captured from a tenant.

**Fields**
- `id` (pk)
- `workspace_id` (fk workspaces, NOT NULL)
- `baseline_profile_id` (fk baseline_profiles, NOT NULL)
- `snapshot_identity_hash` (string(64), NOT NULL)
  - sha256 of normalized captured content
- `captured_at` (timestamp tz, NOT NULL)
- `summary_jsonb` (jsonb, nullable)
  - counts/metadata (e.g., total items)
- timestamps

**Indexes/constraints**
- unique: `(workspace_id, baseline_profile_id, snapshot_identity_hash)` (dedupe)
- index: `(workspace_id, baseline_profile_id, captured_at desc)`

## 3) baseline_snapshot_items (workspace-owned)

**Purpose**: Immutable items within a snapshot.

**Fields**
- `id` (pk)
- `baseline_snapshot_id` (fk baseline_snapshots, NOT NULL)
- `subject_type` (string, NOT NULL) — e.g. `policy`
- `subject_external_id` (string, NOT NULL) — stable key for the policy within the tenant inventory
- `policy_type` (string, NOT NULL) — for filtering and summary
- `baseline_hash` (string(64), NOT NULL) — stable content hash for the baseline version
- `meta_jsonb` (jsonb, nullable) — minimized display metadata (no secrets)
- timestamps

**Indexes/constraints**
- unique: `(baseline_snapshot_id, subject_type, subject_external_id)`
- index: `(baseline_snapshot_id, policy_type)`

## 4) baseline_tenant_assignments (tenant-owned)

**Purpose**: Assigns exactly one baseline profile per tenant (v1), with optional scope override that can only narrow.

**Fields**
- `id` (pk)
- `workspace_id` (fk workspaces, NOT NULL)
- `tenant_id` (fk tenants, NOT NULL)
- `baseline_profile_id` (fk baseline_profiles, NOT NULL)
- `override_scope_jsonb` (jsonb, nullable)
- `assigned_by_user_id` (fk users, nullable)
- timestamps

**Indexes/constraints**
- unique: `(workspace_id, tenant_id)`
- index: `(workspace_id, baseline_profile_id)`

**Validation notes**
- Override must be subset of profile scope (enforced server-side; store the final effective scope hash in the compare run context for traceability).

## 5) findings additions (tenant-owned)

**Purpose**: Persist baseline compare drift findings using existing findings system.

**Required v1 additions**
- add `findings.source` (string, **nullable**, default `NULL`)
  - baseline compare uses `source='baseline.compare'`
  - existing findings receive `NULL`; legacy drift-generate findings are queried with `whereNull('source')` or unconditionally
- index: `(tenant_id, source)`

**Baseline compare finding conventions**
- `finding_type = 'drift'`
- `scope_key = 'baseline_profile:<id>'`
- `fingerprint = sha256(tenant_id|scope_key|subject_type|subject_external_id|change_type|baseline_hash|current_hash)` (using `DriftHasher`)
- `evidence_jsonb` includes:
  - `source` (until DB column exists)
  - `baseline.profile_id`, `baseline.snapshot_id`
  - `baseline.hash`, `current.hash`
  - `change_type` (missing_policy|different_version|unexpected_policy)
  - any minimized diff pointers required for UI

## 6) operation_runs conventions

**Operation types**
- `baseline_capture`
- `baseline_compare`

**Run context** (json)
- capture:
  - `baseline_profile_id`
  - `source_tenant_id`
  - `effective_scope` / `selection_hash`
- compare:
  - `baseline_profile_id`
  - `baseline_snapshot_id` (frozen at enqueue time)
  - `effective_scope` / `selection_hash`

**Summary counts**
- compare should set a compact breakdown for dashboards:
  - totals and severity breakdowns