Phase 1 Journey Hardening

OneProtect now treats persona journey validation as a first-class architecture guardrail. Unit, route, contract, and component tests remain necessary, but a feature is not demo-ready until the intended persona can complete the sequence through authenticated APIs and the deployed console path.

Why This Matters

Recent AWS dev validation exposed bugs that isolated tests could not catch:

• SQLite and Postgres schema drift.
• duplicate read-model SQL serving the same object differently.
• frontend mutation state disappearing after navigation.
• role context changing in empty tenant states.
• OIDC and public URL behavior that only fails behind ingress.
• smoke jobs running before the Helm deploy they were supposed to validate.

The new guardrail is simple: prove the journey, not just the handler.

Journey Validation Layers

Layer	Purpose
Schema contract lock	Catch SQLite/Postgres and migration drift on critical tables.
Canonical read models	Keep console-visible entity shapes consistent across list, detail, and timeline views.
API persona journeys	Exercise real role sequences through FastAPI endpoints.
Frontend response contracts	Pin API response shapes consumed by the console.
Browser/deployed probes	Validate OIDC, ingress, cookies, router behavior, and deployed revision health.

OP-081 implements the first always-on schema contract lock with make validate-read-model-contracts. It introspects SQLite init_db(), statically parses Postgres migrations, fails on table/column drift for the initial critical tenant/asset/agent tables, reports type-class warnings, and fails closed on unsupported critical-table rename/drop/type-change migrations until the parser is extended. It also pins asset read-model aliases such as approved_by AS owner. It is an extensible mechanism; remaining console read models should be added as their persona journeys land.

The AWS dev smoke job is also sequenced behind Helm deploy evidence: deploy_aws_dev writes a dotenv marker after a successful Helm release, and smoke_aws_dev is a manual post-deploy job that needs that artifact before probing the environment. When Helm deploy is not run, smoke is inapplicable rather than a failing job.

OP-083 extends that post-deploy job with an opt-in deployed persona probe. When AWS_DEV_PERSONA_SMOKE_ENABLED=true and protected AWS_DEV_SMOKE_* variables are present, scripts/ci/aws_dev_persona_smoke.py obtains short-lived OIDC tokens, verifies /api/v1/session and authenticated API docs, creates a throwaway smoke tenant/admin, issues and revokes an enrollment token, exchanges it, submits a runtime-lite agent heartbeat, and verifies the resulting asset through list and detail APIs. Reports are written under artifacts/aws-dev-smoke/ with token, password, certificate, and key material redacted.

OP-084 expands frontend/API response contracts from read-only shapes into mutation journey states. The first set covers ticket mutation, alert triage, enrollment token issue/revoke, SCIM connection setup, compliance export request, and compliance policy fork/update. Each API contract performs the mutation, validates the follow-up read or list shape consumed by the UI, and probes denied-role behavior where that workflow has an authorization boundary. Frontend tests also assert successful visible mutations call router.refresh() so the server-rendered console snapshot is invalidated before the user navigates away and returns.

OP-085 removes the first duplicate read-model assembly path. Asset list, detail, and timeline now share canonical response assembly for approved inventory, runtime identity, inventory JSON, discovery source, lifecycle, and confidence fields. The enrolled endpoint heartbeat contract compares list and detail responses and verifies timeline references include the same canonical context.

Persona Journey Map

Persona	What they can or need to do	What success means
system_admin	Log in, create tenants, create tenant bootstrap users, open API docs.	Keycloak claims and SQL role rows agree; tenant creation is audited; no customer data leaks into platform context.
tenant_admin	Create enrollment tokens, manage discovery policy, SCIM, Intune posture, compliance policies, auditor sessions, and exports.	Empty tenant state keeps tenant-admin controls; mutations persist across navigation; audit evidence exists.
operator	Triage alerts, create/update tickets, inspect assets, search SIEM logs, and investigate incidents.	Operational mutations are API-backed, audited, tenant-scoped, and visible after refresh.
auditor	Use time-boxed read-only evidence, logs, tickets, and export views.	No mutation controls render; redaction and every-read audit are enforced.
endpoint agent	Exchange an enrollment token and send heartbeats.	Runtime token is tenant/agent/collector/asset-bound and heartbeats create visible asset state.
collector/service account	Request discovery authorization or provision SCIM lifecycle changes.	Service identity is bounded to tenant/source and denials are audited.

Required Feature Note Content

Every user-visible feature note should include:

• persona,
• user journey,
• API-backed path,
• security, tenant, audit, or redaction boundary,
• validation performed,
• explicit non-scope.

Initial Follow-Up Work

• OP-081: schema/read-model contract lock. Done for the initial tenant/asset/agent table set and asset read-model alias tokens.
• OP-082: Phase 1 API persona journey suite. Done for the agent-to-asset portal journey.
• OP-083: AWS dev deployed persona smoke probes. Done for the first platform-admin to tenant-admin to agent-to-asset deployed path.
• OP-084: frontend/API response contract expansion for journey states. Done for the first critical mutation-success, follow-up read/list, denied-role, and navigation-return coverage set.
• OP-085: canonical read-model consolidation, starting with assets. Done for asset list/detail/timeline responses and pinned by the heartbeat-created asset contract.