# API-First R17 Integration

This document defines how issue `#2466` coverage should move into `staging-inspection`.

## Goals

- use business acceptance coverage as the source of truth
- keep reports readable for business stakeholders
- prefer API execution whenever the business conclusion does not require a UI touchpoint
- avoid new seed data and reuse the existing staging dataset mirrored from production
- fail clearly when the expected staging fixture shape drifts

## Non-goals

- do not carry over Watchdog root-cause analysis
- do not import Watchdog seed/build-your-own-world patterns
- do not expand the runner into a generic test framework before the first migration batch lands

## Execution Policy

Order of preference for every step:

1. existing staging data located by API query
2. existing staging data referenced by stable fixture anchors
3. API write against existing staging parent records
4. UI only when the business question is explicitly about user-visible behavior

Hard rules:

- do not create new seed datasets for R17 migration work
- do not depend on historical raw record ids when a queryable business anchor can be used
- if a case needs a fixed record id today, treat that as temporary and track the resolver to remove it
- runner failures must distinguish `fixture drift` from `product regression`

## Data Strategy

The current staging data is valuable because it comes from the production-mirrored environment. We should validate against that reality instead of inventing parallel synthetic records.

Use three layers:

1. `anchor`
   - business-identifiable selectors stored in fixture JSON
   - examples: account keyword, known username, object route, parent record search criteria
2. `resolver`
   - API query that turns an anchor into a live record id at runtime
   - examples: first active Credits row for a known account, first Opportunity with non-null Pricebook2Id
3. `check`
   - API or UI action against the resolved live row

This removes most hard-coded ids while still avoiding seed creation.

## Inspection Layers

### 1. Business smoke

Purpose:

- answer "can the business scenario still be completed on staging?"

Shape:

- API setup on existing records
- API assertions
- minimal UI only for key user-visible steps

### 2. Readiness

Purpose:

- answer "do we still have the expected production-mirrored fixture shape?"

Shape:

- pure API query / describe checks
- no UI
- failures reported as readiness drift, not product regression

### 3. Contract probe

Purpose:

- keep a small number of engineering-only checks where UI is not the right tool

Shape:

- pure API
- only for checks with real product value

## When UI Is Required

Keep UI only for these classes:

- button visibility
- route accessibility
- page layout / section ordering
- business-facing error copy
- critical end-user submission flows where the click path itself matters

Current R17 compromise:

- if the UI claim is mainly "the setup surface exists and is reachable", use a route-open browser check first
- defer richer click-through or toggle-edit semantics until the browser runner grows beyond `goto` + text assertions
- keep owner-based security semantics on the API side when the UI is only a shell over the same contract

Everything else should prefer API:

- fixture lookup
- create/read/update verification
- permission probes
- sharing / group / record visibility checks
- readback and derived-field assertions

## Runner Direction

The current runner primitives are enough for batch 1:

- `http_probe`
- `api_create`
- `browser_flow`

What is missing is a scene layer above them. The next safe step is not a full rewrite. It is a thin scene manifest that composes these primitives:

1. `readiness_queries`
2. `api_steps`
3. `browser_steps`
4. `assertions`

Batch 1 can still ship with the current primitives plus better checklist/backlog mapping. Scene execution can follow after the first migrated stories prove the shape.

## Story Migration Priorities

### Batch 1

- `#1466` PoC Credits
- `#730` Permission Sets
- `#1333` SharingRule
- `#1334` Group memberships

Reason:

- highest business value
- strongest current signal from `#2466`
- mostly API-verifiable

### Batch 2

- `#732` RLS / FLS
- `#1335` Schema / RT / Layout

Reason:

- more readiness / UI-heavy
- weaker fit for naive create/read checks

## Reporting Rules

Report in business language first:

- module
- scenario
- result
- business impact

Attach technical evidence second:

- request id
- screenshot
- API response summary
- resolved record ids

## Immediate Follow-up

1. create an R17 migration backlog file under `staging-inspection/config/`
2. classify each `#2466` AC as `api`, `hybrid`, `ui`, or `defer`
3. add readiness coverage for the live-data anchors before migrating the write-path scenes
4. migrate Batch 1 story coverage into `staging-inspection`