ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
548a37c888
TenantAtlas/specs/329-evidence-audit-log-disclosure-productization/repo-truth-map.md
ahmido 7ce066dd00 Spec 329: productize evidence and audit log disclosure (#390) 
## Summary
- productize the Monitoring audit log disclosure flow with richer detail inspection and updated disclosure UI
- expand the evidence overview disclosure experience, including filtering and presentation updates
- wire the monitoring pages into the Filament admin panel and workspace sidebar navigation
- add English and German disclosure copy for the new audit and evidence surfaces
- include Spec 329 implementation artifacts and supporting presenter/route updates

## Tests
- added/updated monitoring acceptance and feature coverage for the disclosure flow
- touched tests include `Spec329EvidenceAuditDisclosureSmokeTest`, `Spec329EvidenceAuditDisclosureProductizationTest`, `AuditLogPageTest`, `AuditLogDetailInspectionTest`, `AuditLogInspectFlowTest`, and related monitoring/navigation coverage
- no additional test run was performed as part of this commit/push/PR workflow

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #390
2026-05-19 21:34:23 +00:00

121 lines
18 KiB
Markdown
Raw Blame History

# Spec 329 Repo Truth Map
Status: implemented
Created: 2026-05-19
Implemented: 2026-05-19
Purpose: classify each Evidence Overview and Audit Log disclosure element before and after runtime implementation. This map is based on repository inspection and the Spec 329 implementation diff.
## Classification Legend
- `repo-verified`: exact runtime source exists and was inspected.
- `foundation-real`: backend model/service/policy exists, but exact page binding still needs implementation verification.
- `derived from existing model`: display value can be derived from existing persisted/domain truth.
- `empty/unavailable state`: no safe source/action exists for v1; show explicit unavailable state or omit.
- `deferred future capability`: outside Spec 329 and must not be shown as live runtime truth.
## Required Data Areas
| Data area | Repo source | Preparation finding |
|---|---|---|
| Evidence Overview route | `apps/platform/routes/web.php`, route `admin.evidence.overview` | repo-real path is `/admin/evidence/overview`; route appears duplicated and should be verified during implementation |
| Workspace sidebar Evidence entry | `WorkspaceSidebarNavigation`, `AdminPanelProvider`, route `admin.evidence.overview` | repo-real sidebar entry under Monitoring links to the existing workspace-owned route |
| Evidence Overview page | `EvidenceOverview` and `evidence-overview.blade.php` | repo-real current layout is scope text plus table |
| Evidence Snapshots | `EvidenceSnapshot`, `EvidenceSnapshotResource`, `EvidenceSnapshotPolicy` | repo-real snapshot status, completeness, summary, generated/expiry timestamps, tenant/workspace scope, operation run relation, detail route |
| Evidence Snapshot Items | `EvidenceSnapshotItem` relation | foundation-real item inventory for deeper proof path; raw item/payload detail must not be default-visible |
| Review Packs | `ReviewPack`, `ReviewPackResource`, `ReviewPackPolicy`, `ReviewPackDownloadController` | repo-real statuses and detail/download surfaces; Evidence Overview currently does not expose pack availability |
| Stored Reports / export artifacts | `StoredReport`, `StoredReportResource` | repo-real report types and capability-bound detail resources; no generic export engine is implied |
| OperationRuns | `OperationRun`, `OperationRunLinks` | repo-real operation proof links for evidence snapshot/review pack generation where linked to run |
| Audit Log route | `apps/platform/routes/web.php`, route `admin.monitoring.audit-log` | repo-real path is `/admin/audit-log`; middleware includes `ensure-environment-context-selected` and must be verified for workspace-hub shell safety |
| Audit Log page | `AuditLog` and `audit-log.blade.php` | repo-real current page is summary-first history with selected-event detail |
| Audit Log events | `AuditLog` model | repo-real actor/action/target/outcome/time/scope fields and derived snapshots |
| Actor/action/target/outcome/time | `AuditLog::actorSnapshot()`, `targetSnapshot()`, `normalizedOutcome()`, `recorded_at`, `action` | repo-verified fields; action label via `AuditActionId::labelFor()` |
| Risk/Decision links if present | `FindingException`, `FindingExceptionEvidenceReference`, `RelatedNavigationResolver` | foundation-real; only show where related route and authorization exist |
| Customer Review Workspace evidence links | `CustomerReviewWorkspace`, `EvidenceSnapshotAuditLogTest`, review/evidence source query params | foundation-real context for evidence proof links; no redesign in Spec 329 |
| Governance Inbox evidence links | `GovernanceInbox`, Spec 327 repo truth | foundation-real context only; no redesign in Spec 329 |
| Operations proof links | `OperationRunLinks::tenantlessView()`, `OperationRunLinks::related()` | repo-real for operation proof/details and linked evidence/review pack artifacts |
| Environment filter state | `WorkspaceHubEnvironmentFilter`, `WorkspaceHubFilterStateResetter`, `ClearsWorkspaceHubEnvironmentFilterState`, `CanonicalAdminEnvironmentFilterState`, filter chip partial | repo-real canonical `environment_id`, clear filter, alias rejection, cross-workspace guard |
| Diagnostics/raw metadata availability | `AuditLog::technicalMetadata()`, `AuditLog::metadata`, `OperationRun.context`, snapshot/report payload fields | repo-real raw/support sources exist but must stay collapsed/hidden and capability-aware |
## UI Element Map
| UI element | Surface | Source model/service/page | Status source | Authorization/capability | Workspace/Environment scope | OperationRun/evidence/audit/export link | Fallback/empty state | Classification |
|---|---|---|---|---|---|---|---|---|
| Evidence Overview route | Evidence Overview | `admin.evidence.overview` | route | workspace middleware + page access | current workspace | none | 404/workspace chooser per middleware | repo-verified |
| Workspace sidebar Evidence entry | Workspace sidebar | `WorkspaceSidebarNavigation`, `AdminPanelProvider`, route `admin.evidence.overview` | static navigation item | workspace sidebar visibility | current workspace | `/admin/evidence/overview` | item absent only if sidebar group is unavailable | repo-verified |
| Evidence Overview title/question | Evidence Overview | page/view stable copy | static copy | page access | workspace/filter | none | static title | repo-verified |
| Workspace scope label | Evidence Overview | `WorkspaceContext` and shell | current workspace/session | workspace membership | workspace shell | none | 404 if unavailable | repo-verified |
| Environment filter chip | Evidence Overview | `environmentFilterChip()`, shared chip partial | `WorkspaceHubEnvironmentFilter` + table state | actor must access environment | `?environment_id={id}` only | none | no chip on clean URL | repo-verified |
| Clear filter action | Evidence Overview | `clearOverviewFilters()`, resetter | generated clean route | page access | removes canonical/table/session state | none | hidden when unfiltered | repo-verified |
| Legacy alias rejection | Evidence Overview | `WorkspaceHubFilterStateResetter` + navigation tests | forbidden query/session keys | page access | aliases do not set filter | none | workspace-wide view or safe 404 | repo-verified |
| Cross-workspace environment guard | Evidence Overview | `WorkspaceHubEnvironmentFilter::fromRequest()` and `normalizeTenantFilter()` | environment scoped by workspace/access | workspace and environment entitlement | current workspace only | none | 404 / safe no-access | repo-verified |
| Proof readiness workbench | Evidence Overview | new page-local payload over existing rows | derived from latest accessible snapshots and related artifacts | evidence/report/review/run capabilities | current workspace/filter | evidence/review/report/operation links where authorized | `No evidence for this scope` | derived from existing model |
| Evidence snapshot state | Evidence Overview | `EvidenceSnapshot.status`, `completeness_state`, `ArtifactTruthPresenter` | persisted fields + derived presenter | `evidence.view` and `EvidenceSnapshotPolicy` for links | current workspace/filter | `EvidenceSnapshotResource::getUrl('view')` | `Evidence snapshot unavailable` | repo-verified |
| Evidence freshness | Evidence Overview | `generated_at`, `expires_at`, `ArtifactTruthPresenter` | timestamps and derived freshness | evidence visibility | current workspace/filter | evidence snapshot detail | `Freshness unavailable` | derived from existing model |
| Evidence path: snapshot | Evidence Overview | `EvidenceSnapshot` | active/current snapshot | evidence visibility | current workspace/filter | evidence snapshot detail | unavailable/not generated | repo-verified |
| Evidence path: review pack | Evidence Overview | `ReviewPack`, `EvidenceSnapshot::reviewPacks()` | status/generated/expired fields | `review_pack.view`, `ReviewPackPolicy` | current workspace/filter | review pack detail/download if authorized | `Review pack unavailable` / `Not generated` | foundation-real |
| Evidence path: operation proof | Evidence Overview | `EvidenceSnapshot::operationRun()`, `ReviewPack::operationRun()`, `OperationRunLinks` | relation/run id | operation visibility | current workspace/filter | operation detail | `Operation proof unavailable` | foundation-real |
| Evidence path: stored report/export | Evidence Overview | `StoredReport`, `StoredReportResource` | report type/fingerprint/payload | report-type capability | current workspace/filter | stored report detail | `Stored report unavailable` | foundation-real |
| Evidence path: decision/risk record | Evidence Overview | `FindingExceptionEvidenceReference`, related resources | evidence reference relation | finding exception/evidence capabilities | current workspace/filter | finding/exception/evidence route if authorized | `Decision proof unavailable` | foundation-real |
| Evidence path: audit trail | Evidence Overview | `AuditLog` events for evidence actions | action/resource metadata | `audit.view` | current workspace/filter | audit log filtered/selected link if implemented | `Audit event unavailable` | foundation-real |
| Export/report availability panel | Evidence Overview | `ReviewPack`, `StoredReport` | existing statuses and report types | review/report capabilities | current workspace/filter | review pack download/detail, stored report detail | `Unavailable` / `Not generated` | foundation-real |
| Evidence inventory table | Evidence Overview | existing Filament table | latest accessible snapshots | evidence visibility | current workspace/filter | row URL to evidence snapshot | existing empty state | repo-verified |
| Evidence diagnostics disclosure | Evidence Overview | raw snapshot/report/run payloads | raw fields exist | `support_diagnostics.view` or stricter | current scope | existing detail/support surfaces only | collapsed/hidden | foundation-real |
| Raw provider payloads | Evidence Overview | raw Graph/provider payloads | not safe default | support-only future | N/A | N/A | never default-visible | deferred future capability |
| Audit Log route | Audit Log | `admin.monitoring.audit-log` | route | workspace middleware + `audit.view` | current workspace | none | 404/403 per existing resolver | repo-verified |
| Audit Log title/question | Audit Log | page/view stable copy | static copy | audit page access | workspace/filter | none | static title | repo-verified |
| Workspace scope label | Audit Log | `WorkspaceContext` and shell | current workspace/session | workspace membership | workspace shell | none | 404 if unavailable | repo-verified |
| Environment filter chip | Audit Log | `environmentFilterChip()`, shared chip partial | `WorkspaceHubEnvironmentFilter` + table state | actor must access environment | `?environment_id={id}` only | none | no chip on clean URL | repo-verified |
| Clear filter action | Audit Log | empty state/header clear flow + resetter | generated clean route | audit page access | removes canonical/table/session state | none | hidden/unavailable when unfiltered | repo-verified |
| Legacy alias rejection | Audit Log | resetter and navigation tests | forbidden query/session keys | audit page access | aliases do not set filter | none | workspace-wide view or safe 404; explicit Spec 329 coverage required | foundation-real |
| Cross-workspace environment guard | Audit Log | `WorkspaceHubEnvironmentFilter::fromRequest()`, `authorizedTenants()` | environment scoped by workspace/access | workspace and environment entitlement | current workspace only | none | 404 / safe no-access | repo-verified |
| Audit proof workbench | Audit Log | new page-local payload over `AuditLog` | latest/selected visible event | `audit.view` | current workspace/filter | selected event, related record, operation link | `No audit events in scope` | derived from existing model |
| Selected event proof panel | Audit Log | `selectedAuditRecord()`, selected-event partial | `event` query + normalized table/filter visibility | `audit.view` and row scope | current workspace/filter | related record/proof via resolver | no selected event panel | repo-verified |
| Actor | Audit Log | `AuditLog::actorSnapshot()`, `actorDisplayLabel()` | actor fields/metadata | `audit.view` | current workspace/filter | selected event proof | `Actor unavailable` | repo-verified |
| Action | Audit Log | `action`, `AuditActionId::labelFor()` | action id | `audit.view` | current workspace/filter | selected event proof | `Action unavailable` | repo-verified |
| Target | Audit Log | `targetSnapshot()`, `targetDisplayLabel()` | target fields | `audit.view` | current workspace/filter | related target link if authorized | `No target snapshot` | repo-verified |
| Outcome | Audit Log | `normalizedOutcome()`, `BadgeRenderer` | outcome/status | `audit.view` | current workspace/filter | selected event proof | `Outcome unavailable` | repo-verified |
| Time | Audit Log | `recorded_at` | timestamp | `audit.view` | current workspace/filter | selected event proof | `Time unavailable` | repo-verified |
| Scope | Audit Log | `workspace`, `tenant`, `workspace_id`, `managed_environment_id` | relationship/ids | `audit.view`, environment entitlement | workspace/filter | selected event proof | workspace-wide event | repo-verified |
| Related operation proof | Audit Log | `AuditLog::operationRun()`, `RelatedNavigationResolver`, `OperationRunLinks` | operation relation/resource target | operation/source authorization | current workspace/filter | operation detail/source record | `Operation proof unavailable` | foundation-real |
| Related evidence/export proof | Audit Log | resource type/id + resolver | target relation where supported | source authorization | current workspace/filter | source detail route | `Related proof unavailable` | foundation-real |
| Readable context | Audit Log | `AuditLog::contextItems()` | safe scalar metadata subset | `audit.view` | current workspace/filter | selected event proof | no additional context | repo-verified |
| Technical metadata | Audit Log | `AuditLog::technicalMetadata()` | technical fields | raw/diagnostics capability | current scope | collapsed diagnostics only | hidden by default; current default exposure must change | repo-verified |
| Raw audit metadata blob | Audit Log | `AuditLog.metadata` | raw JSON/array | support/raw capability only | current scope | collapsed diagnostics only if ever exposed | hidden by default | foundation-real |
| Support access history filter/export | Audit Log | existing header actions | supportAccess query/export action | current page access; export needs review | workspace/filter | CSV stream for support actions only | existing action hidden/available per current page; not a generic audit export claim | repo-verified |
| Audit table/history | Audit Log | existing Filament table | scoped query, filters, columns | `audit.view` + environment entitlement | workspace/filter | inspect action with event query | existing empty state | repo-verified |
| Disclosure rule panel | Both | page-local copy/state | static hierarchy + capabilities | page access | current scope | links only when authorized | compact panel | derived from existing model |
| Tenant platform copy guard | Both | runtime copy/tests | string assertions | N/A | page copy | N/A | use Workspace/Environment; implementation test required | repo-verified |
## Required Runtime Element Decisions
| Element | v1 decision |
|---|---|
| New evidence backend | deferred future capability; do not build |
| New audit ingestion engine | deferred future capability; do not build |
| New immutable/certification/integrity claim | deferred future capability; do not claim |
| Generic compliance readiness badge | deferred future capability; do not show |
| Generic export engine | deferred future capability; use only existing ReviewPack/StoredReport/download truth |
| Evidence freshness | derive from existing generated/expires/artifact truth only |
| Review pack state | derive from existing `ReviewPack.status` and timestamps only |
| Stored report availability | derive from existing `StoredReport` records and report-type capabilities only |
| Operation proof | link only through existing run relations/helpers and authorization |
| Audit event selected panel | actor/action/target/outcome/time first; raw metadata collapsed |
| Diagnostics | collapsed/hidden by default and capability-aware if exposed |
| Raw provider payloads | never default-visible |
| Dangerous/mutating actions | do not add unless spec/plan updated first |
| Legacy query aliases | rejected/neutralized; do not support |
## Implementation Update Rule
If implementation discovers that a planned UI element has no safe source, no authorization path, or would require new persisted truth, the element must become `empty/unavailable state` or `deferred future capability`. Do not create backend foundation inside Spec 329 without updating `spec.md`, `plan.md`, `tasks.md`, and this map first.
## Implementation Close-Out
- Evidence Overview now renders a proof-first workbench from existing `EvidenceSnapshot`, `ReviewPack`, `StoredReport`, `OperationRun`, artifact-truth, policy, and workspace-hub filter sources. The existing inventory table remains secondary context, and the existing route is reachable from the Workspace Monitoring sidebar.
- Audit Log now renders an event-proof-first workbench from existing `AuditLog` actor/action/target/outcome/time/scope fields, related navigation, and operation proof links. The existing event history table and selected-event inspect flow remain available.
- Diagnostics/raw metadata are not default-visible. Evidence diagnostics are collapsed with guidance to use authorized detail surfaces; audit technical metadata is behind collapsed, capability-aware disclosure.
- The duplicated `/admin/evidence/overview` route registration was removed; the canonical route name and path remain unchanged.
- UI coverage registry files were not changed because route names, paths, archetypes, and strategic surface classifications remain the existing UI-025 and UI-044 entries. Spec 329 carries the implementation proof through this repo truth map, targeted tests, and browser screenshots.
- Browser screenshots are stored in `specs/329-evidence-audit-log-disclosure-productization/artifacts/screenshots/`.
- No migrations, seeders, packages, environment variables, queues, scheduler changes, storage changes, deployment assets, backwards compatibility layer, or legacy tenant alias support were added.
Reference in New Issue View Git Blame Copy Permalink