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

Phase 0 — Research

This document records the key technical decisions for 101 — Golden Master / Baseline Governance v1 (R1.1–R1.4), grounded in existing TenantPilot patterns.

Existing System Constraints (confirmed in repo)

Operation runs are tenant-scoped and deduped at DB level

• OperationRunService::ensureRunWithIdentity() requires a Tenant with a non-null workspace_id, and always creates runs with workspace_id + tenant_id.
• Active-run idempotency is enforced via the operation_runs_active_unique partial unique index (queued/running).

Implication: Baseline capture/compare must always be executed as tenant-owned OperationRun records, even though baseline profiles are workspace-owned.

Findings fingerprinting expects sha256 (64 chars)

• findings.fingerprint is string(64) and unique by (tenant_id, fingerprint).
• DriftHasher already implements a stable sha256 fingerprint scheme.

Implication: Any baseline-compare “finding key” should be hashed before storage, and must be stable across repeated compares.

Decisions

D-001 — Baseline snapshot storage is workspace-owned (and data-minimized)

Decision: Store baseline_snapshots and baseline_snapshot_items as workspace-owned tables (workspace_id NOT NULL, no tenant_id) so a golden master snapshot can be used across tenants without requiring access to the source tenant.

Rationale:

• The product intent is a workspace-level standard (“Golden Master”) reusable across multiple tenants.
• Treat the snapshot as a standard artifact, not tenant evidence, and enforce strict data-minimization so we do not leak tenant-specific content.

Guardrails:

• Snapshot items store only policy identity + stable content hashes and minimal display metadata.
• Any tenant identifiers (e.g., “captured from tenant”) live in the capture OperationRun.context and audit logs, not on workspace-owned snapshot rows.

Alternatives considered:

• Tenant-owned baseline snapshot (include tenant_id): rejected because it would require cross-tenant reads of tenant-owned records to compare other tenants, which would either violate tenant isolation or force “must be member of the source tenant” semantics.

D-002 — OperationRun types and identity inputs

Decision:

• Introduce OperationRun.type values:
  • baseline_capture
  • baseline_compare
• Use OperationRunService::ensureRunWithIdentity() for idempotent start surfaces.

Identity inputs:

• baseline_capture: identity inputs include baseline_profile_id.
• baseline_compare: identity inputs include baseline_profile_id.

Rationale:

• Guarantees one active run per tenant+baseline profile (matches partial unique index behavior).
• Keeps identity stable even if the active snapshot is switched mid-flight; the run context should freeze baseline_snapshot_id at enqueue time for determinism.

Alternatives considered:

• Include baseline_snapshot_id in identity: rejected for v1 because we primarily want “single active compare per tenant/profile”, not “single active compare per snapshot”.

D-003 — Precondition failures return 422 and do not create OperationRuns

Decision: Enforce FR-014 exactly:

• The start surface validates preconditions before calling OperationRunService.
• If unmet, return HTTP 422 with a stable reason_code and do not create an OperationRun.

Rationale:

• Aligns with spec clarifications and avoids polluting Monitoring → Operations with non-startable attempts.

D-004 — Findings storage uses existing findings table; add a source discriminator

Decision:

• Store baseline-compare drift as Finding::FINDING_TYPE_DRIFT.
• Persist source = baseline.compare per FR-015.

Implementation note:

• The current findings schema does not have a source column.
• In Phase 2 implementation we should add findings.source (string, nullable, default NULL) with an index (tenant_id, source) and use source='baseline.compare'.
• Existing findings receive NULL — legacy drift-generate findings are queried with whereNull('source') or unconditionally.
• A future backfill migration may set source='drift.generate' for historical findings if needed for reporting.

Alternatives considered:

• Store source only in evidence_jsonb: workable, but makes filtering and long-term reporting harder and is less explicit.
• Non-null default 'drift.generate': rejected because retroactively tagging all existing findings requires careful validation and is a separate concern.

D-005 — Baseline compare scope_key strategy

Decision: Use findings.scope_key = 'baseline_profile:' . baseline_profile_id for baseline-compare findings.

Rationale:

• Keeps a stable grouping key for tenant UI (“Soll vs Ist” for the assigned baseline).
• Avoids over-coupling to inventory selection hashes in v1.

D-006 — Authorization model (404 vs 403)

Decision:

• Membership is enforced as deny-as-not-found (404) via existing membership checks.
• Capability denials are 403 after membership is established.

Capabilities:

• Add workspace capabilities:
  • workspace_baselines.view
  • workspace_baselines.manage

Rationale:

• Matches the feature spec’s two-capability requirement.
• Keeps baseline governance controlled at workspace plane, while still enforcing tenant membership for tenant-context pages/actions.

Alternatives considered:

• Add a tenant-plane capability for compare start: rejected for v1 to keep to the two-capability spec and avoid introducing a second permission axis for the same action.

Open Questions (none blocking Phase 1)

• None.