# Coaster World DATA — first real provider pilot

Version target: **v0.5.0-dev.1**.

This phase is deliberately **staging-only**. It proves that a real external provider can feed the active DATA server without permitting canonical writes.

## Safety state

Before the pilot, the final Ready-for-DATA audit must already be `VERIFIED / READY`.

Only this construction flag may be enabled for staging:

```env
DATA_PROVIDER_COLLECTION_ENABLED=true
```

Keep the other five locks closed:

```env
DATA_POPULATION_ENABLED=false
DATA_PROVIDER_SCHEDULES_ENABLED=false
DATA_CANONICAL_AUTO_APPLY_ENABLED=false
DATA_AI_AGENTS_ENABLED=false
DATA_RESEARCH_EXECUTION_ENABLED=false
```

The v0.5.0-dev.1 pilot supports **ThemeParks.wiki only**, a maximum of **3 explicitly selected parks**, and no proposal creation.

## 1. Discover park IDs without writing

The discovery command calls ThemeParks.wiki in preview mode and stores nothing in the database:

```bat
php artisan cw:data:pilot:discover "Efteling"
php artisan cw:data:pilot:discover "Parc Asterix"
php artisan cw:data:pilot:discover "Europa-Park"
```

Copy the exact external park IDs from the result.

## 2. Preview the exact pilot

Keep provider staging locked for this step:

```bat
php artisan cw:data:pilot:collect --park=<PARK_ID_1> --park=<PARK_ID_2>
```

By default the preview includes the park record and up to 250 child entities per park. To inspect only park records:

```bat
php artisan cw:data:pilot:collect --park=<PARK_ID> --no-children
```

Preview mode performs no fetch persistence, no normalized staging write, no proposal and no canonical write.

## 3. Take a fresh snapshot before the first staging write

```bat
php artisan cw:data:snapshot --label=before-first-real-pilot
php artisan cw:data:snapshot:verify latest
php artisan cw:data:snapshot:replicate latest
```

Do not continue if snapshot or replica verification fails.

## 4. Enable only provider staging

Edit `.env`:

```env
DATA_PROVIDER_COLLECTION_ENABLED=true
```

Then:

```bat
php artisan optimize:clear
php artisan cw:data:status
php artisan cw:data:integrity
php artisan cw:data:preflight
```

`Provider staging` should show `ENABLED (PILOT)`. Integrity and the construction-lock checks accept this exact pilot state only when the Ready-for-DATA audit is valid and the five write/execution locks remain closed.

## 5. Run the staged pilot

Use the same reviewed park IDs:

```bat
php artisan cw:data:pilot:collect --stage --park=<PARK_ID_1> --park=<PARK_ID_2>
```

The command returns a `pilot-...` identifier and stores a private report under `storage/app/private/data-pilots`.

The staged run intentionally creates only:

- ingestion runs;
- raw source fetches;
- normalized provider staging records.

It must **not** create:

- data proposals;
- canonical conflicts;
- applied canonical decisions;
- parks, attractions or POIs in the canonical catalogue.

## 6. Review the pilot

```bat
php artisan cw:data:pilot:status
php artisan cw:data:pilot:status --records
php artisan cw:data:status
```

The pilot report includes before/after protected counters and a safety guard. Every safety guard line must be `PASS`.

A `WARNING` caused only by a child-catalogue truncation means the provider returned more children than the configured pilot limit. Do not silently increase the limit during the first pilot; review the partial set first.

## 7. Safe cleanup / rollback of staging-only pilot data

If the pilot should be discarded, use the exact pilot ID:

```bat
php artisan cw:data:pilot:cleanup pilot-xxxxxxxxxxxxxxxx
```

The cleanup deletes only normalized records, source fetches and ingestion runs created by that pilot. Existing identical staging records are preserved and never re-linked by the pilot. Cleanup refuses to continue if proposals or field evidence are linked to the pilot.

After cleanup:

```bat
php artisan cw:data:pilot:status
php artisan cw:data:integrity
php artisan cw:data:status
```

## 8. End of first-pilot phase

Leave `DATA_PROVIDER_COLLECTION_ENABLED=true` only while manually running named pilot collections. Provider schedules remain disabled.

Do **not** enable canonical population, canonical auto-apply, AI agents or autonomous research in v0.5.0-dev.1.

The next milestone after a reviewed real staging pilot will define how selected staged records are mapped and promoted under administrator control.

## v0.5.0-dev.2 — workflow web prioritaire

Le pilote doit désormais être exécuté depuis **Administration → Pilote DATA**. Le terminal n'est plus requis pour les opérations normales du pilote.

Le master serveur `DATA_PROVIDER_COLLECTION_ENABLED=true` reste une permission maximale / kill-switch. L'autorisation opérationnelle est distincte : le staging web est désarmé par défaut, doit être armé explicitement juste avant l'import et est automatiquement désarmé après la tentative.

La page **Administration → Console DATA** permet d'exécuter les diagnostics et opérations Artisan autorisés depuis une interface terminal sécurisée. Elle n'est pas un shell système et n'accepte que sa liste blanche.


## v0.5.0-dev.3 — revue des propositions depuis le web

Après un staging `VERIFIED`, la page **Pilote DATA** peut générer des propositions `pending` sans toucher au canonique. Les lignes non mappées deviennent des `entity_candidate`; les lignes déjà mappées produisent des propositions champ par champ avec leurs preuves.

La revue (approbation/rejet, individuelle ou groupée) reste une étape de validation humaine. `DATA_POPULATION_ENABLED=false` et `DATA_CANONICAL_AUTO_APPLY_ENABLED=false` restent obligatoires pendant ce jalon.