TenantAtlas/specs/158-artifact-truth-semantics/research.md

# Research: Governance Artifact Truthful Outcomes & Fidelity Semantics

## Decision 1: Implement the first slice as a shared presentation/read-model layer over existing persisted artifact fields

- **Decision**: Introduce a shared artifact-truth presenter or view-model layer that composes current persisted artifact state from existing enums, badge domains, `summary` payloads, and `OperationRun.context` rather than adding a new database table in the first slice.
- **Rationale**: Baseline snapshots already expose fidelity and gap summaries, evidence snapshots already persist completeness plus missing/stale counts, tenant reviews already persist completeness and publish blockers, and review packs already persist generation state plus source review/evidence metadata. The main problem is inconsistent operator interpretation, not missing primary persistence.
- **Alternatives considered**:
  - Add a new `artifact_truth_states` table: rejected because the first slice would duplicate existing truth and risk divergence.
  - Hard-code per-page label logic: rejected because it would regress BADGE-001 and Spec 156.

## Decision 2: Reuse centralized badge semantics and reason translation instead of creating a parallel truth taxonomy

- **Decision**: Build the truth envelope on top of `BadgeCatalog`, `BadgeRenderer`, `OperatorOutcomeTaxonomy`, and `ReasonPresenter`, extending or remapping badge domains only where existing domains still collapse artifact meanings.
- **Rationale**: Evidence completeness and tenant review completeness already consume the taxonomy, baseline fidelity already uses a centralized badge domain, and run detail already translates blocked reasons through `ReasonPresenter`. This creates visible adoption of Specs 156 and 157 instead of inventing a competing presentation model.
- **Alternatives considered**:
  - Create dedicated per-artifact truth enums for every surface: rejected because it would fragment semantics and duplicate the taxonomy.
  - Rely only on free-form helper text: rejected because operator consistency would remain untestable.

## Decision 3: Keep canonical workspace summaries entitlement-safe by filtering tenants before deriving labels, counts, and filter options

- **Decision**: Preserve the current query-first tenant filtering pattern on canonical workspace pages and derive truth labels, readiness counts, and filter options only from the already-authorized record set.
- **Rationale**: `EvidenceOverview` builds rows only from tenants for which the user can `evidence.view`, and `ReviewRegister` limits both the query and tenant filter options to entitled tenants via `TenantReviewRegisterService` and `CanonicalAdminTenantFilterState`. This is the correct security boundary for Spec 158's non-leakage requirements.
- **Alternatives considered**:
  - Precompute workspace-wide aggregate truth counts and hide unauthorized rows later: rejected because counts and filter options would become leakage-prone.
  - Allow canonical pages to read all tenant rows and filter in Blade/Livewire: rejected because that would weaken 404/403 semantics and be harder to regression-test.

## Decision 4: Attach artifact-truth messaging to tenantless run detail via the existing enterprise-detail builder and related-link model

- **Decision**: Extend `OperationRunResource::enterpriseDetailPage()` and the tenantless run viewer to add an artifact-truth section for baseline capture, evidence generation, tenant review composition, and review-pack generation, reusing `OperationRunLinks` and `ReasonPresenter`.
- **Rationale**: The canonical run detail page already leads with operator-first state, exposes related links, and has operation-type-specific sections for baseline compare and baseline capture evidence. Adding artifact-produced/usable/degraded interpretation there stays aligned with the existing Ops-UX reference implementation.
- **Alternatives considered**:
  - Add a separate artifact-truth run detail page: rejected because it would violate the single canonical run-detail surface.
  - Expose only raw `context` or failure JSON: rejected because it does not satisfy FR-158-012.

## Decision 5: Use targeted summary enrichment only where current persisted fields cannot explain truthful artifact provenance

- **Decision**: Preserve existing models as the primary source, but allow small, backward-compatible enrichment of existing `summary` or `context` payloads when current fields cannot truthfully answer whether an artifact is usable, current, or publishable.
- **Rationale**: Some families already have enough persisted state, while others, especially review packs and baseline-capture runs, may need a stable provenance or degraded-artifact explanation beyond the lifecycle enum alone. Enriching current JSON payloads is lower-risk than adding new tables or widening operation types.
- **Alternatives considered**:
  - Force the entire slice to use current fields only: rejected because some false-green cases would stay ambiguous.
  - Redesign underlying artifact schemas first: rejected because it would turn a bounded truth-semantics slice into a domain rewrite.

## Decision 6: Review-pack truth should derive from pack lifecycle plus source review and evidence provenance, not from pack status alone

- **Decision**: Model review-pack truth as a composition of pack lifecycle (`queued`, `generating`, `ready`, `failed`, `expired`), source review readiness or publication state, anchored evidence completeness, and freshness/provenance metadata already persisted in `summary`.
- **Rationale**: `ReviewPackStatusBadge` currently treats `ready` as if it were enough, but the spec explicitly requires operators to know whether the pack is a trustworthy export of a publishable review or only a historical derivative.
- **Alternatives considered**:
  - Keep `ReviewPackStatus` as the sole operator state: rejected because it cannot distinguish “pack file exists” from “pack is a trustworthy stakeholder output.”
  - Add a second lifecycle enum to `ReviewPack`: rejected for the first slice because provenance can be derived from existing linked models and summary payloads.

## Decision 7: Migration guidance is semantic migration, not data migration, for the first slice

- **Decision**: Treat FR-158-017 as a semantic migration of labels, helper copy, badge usage, and empty-state wording rather than a schema or record backfill migration.
- **Rationale**: The current ambiguity stems from overloaded labels such as `missing`, `partial`, `ready`, and `draft`. Existing records remain valid if the new truth layer interprets them more precisely and, where needed, supplements them with cause-specific explanation.
- **Alternatives considered**:
  - Backfill historical records with new truth fields: rejected because current records can be interpreted through derived envelopes.
  - Leave old wording in place for backward compatibility: rejected because the feature's core value is truthful operator meaning.