# Watchdog Run-Scoped Seed Architecture

## Goal

Decouple watchdog execution from full environment rebuild.

The target model is:

1. environment bootstrap installs pack and long-lived tenant configuration
2. each watchdog run creates its own actors and business data
3. each case reads only run-scoped seed data or run-created records
4. environment refresh and test execution can evolve independently

## Layers

### 1. Baseline Seed

Owned by environment bootstrap:

1. pack install follow-up seed
2. long-lived metadata or tenant-wide config
3. data that must exist before any run starts

Examples:

1. record types
2. approval definitions
3. layouts / profile layout bindings
4. reports / dashboards
5. webhook / integration config
6. groups / sharing graph

Baseline seed must stay:

1. idempotent
2. environment-agnostic
3. independent from watchdog `run_id`

### 2. Run Seed

Owned by each watchdog run:

1. run-scoped actors
2. run-scoped business graph
3. case-local or scene-local synthetic setup

Run seed must:

1. require a `run_id`
2. generate unique usernames, emails, names, and product codes
3. preserve business relations between seeded objects
4. be safe to rerun for the same `run_id`

### 3. Case Mutation

Owned by individual cases:

1. objects explicitly created by the test path
2. assertions against persisted side effects
3. cleanup is optional; selection must prefer `run_id` isolation over deletion

## Execution Contract

### Environment bootstrap

1. deploy / bootstrap stack
2. apply baseline seed only
3. verify health only

Environment bootstrap must not assume watchdog actor users already exist.

### Watchdog run

1. generate `run_id`
2. apply run seed
3. persist runtime seed state under run artifacts
4. execute selected scene / case set
5. emit report

## Actor Contract

Each actor definition has two responsibilities:

1. login mapping for execution
2. provisioning template for run seed

Run-scoped actors are the default.

The runner must prefer runtime-provisioned actor credentials over static env vars.
Static env vars remain the fallback for:

1. admin login
2. legacy local debugging
3. emergency manual replay

## Data Contract

Tracked seed files should separate:

1. baseline records
2. run records

Run records should use templates backed by:

1. `run_id`
2. materialized seed inputs
3. actor references
4. prior record references

The minimum reference set is:

1. `{{ run_id }}`
2. `{{ env.NAME }}`
3. `{{ inputs.key }}`
4. `{{ actor.actor-key.id }}`
5. `{{ actor.actor-key.username }}`
6. `{{ record.record-key.id }}`

## Naming Rules

Run-scoped values should be deterministic per run:

1. usernames: `<role>+<run_id>@example.invalid`
2. emails: `<purpose>+<run_id>@example.invalid`
3. business names: `Watchdog <Entity> <run_id>`
4. product codes: `WATCHDOG-<ENTITY>-<run_id>`

This enables:

1. parallel runs
2. replay of a specific failed run
3. artifact-to-record correlation

## Migration Rule

Cases must stop querying stable shared names when those objects are run-scoped.

Case contracts should reference:

1. `inputs.*` for deterministic names / emails
2. step outputs for newly created records

Do not keep querying shared seed names once run seed owns the record.

## CI Rule

The watchdog API workflow should:

1. refresh environment
2. skip post-deploy actor reconciliation
3. let the API runner create run-scoped actors and data

This keeps the environment job and the test job loosely coupled.