# Environment sample states

This directory is the single source of truth for public Archal sample states.
`catalog.v1.json`, `states/**`, and the package's generated TypeScript catalog
are deterministic outputs. Edit the definitions and generator in
`packages/environment-samples`, then run:

```bash
pnpm --filter @archal/environment-samples generate
pnpm --filter @archal/environment-samples validate
```

Every GA environment has exactly five samples. `candidate`, local `validation`,
and hosted `certification` are separate facts. A missing hosted credential or
skipped promotion remains `unknown`; it never becomes a passing
certification.

Historical files under `clones/*/seeds` are immutable inputs. Their hashes are
pinned in `source-lock.v1.json`. The generator and validator fail if the
inventory or any pinned byte changes.

The five frozen v1 categories are `minimal`, `small-team`, `populated`,
`edge-case`, and `workflow`. Names describe scenario intent, not a generic
record-slicing transform: every reviewed profile has an exact constructor and
machine-checked semantic proof.

Hosted promotion is deliberately adapter-driven:

```bash
pnpm --filter @archal/environment-samples promote -- \
  --adapter ./path/to/hosted-adapter.mjs \
  --source-commit "$GIT_COMMIT" \
  --runtime-bundle-digest "$RUNTIME_BUNDLE_DIGEST"
```

The adapter must export `createPromotionAdapter({ repositoryRoot })`. Promotion
runs the workflow sample through start, readiness, state load, provider-native
read, mutation, diff, reset, baseline comparison, isolation, teardown, and
orphan checks. Evidence is written only under ignored `runs/` by default.
Missing credentials or a missing adapter is a nonzero command failure and
cannot change catalog qualification.

`packages/environment-samples/certification-adapter.mjs` projects these reports
into the fleet ledger. It accepts either `hostedEvidenceByEnvironment` or
`hostedReportDirectory`; absent reports remain `unknown`, while stale,
incomplete, or hash-mismatched reports fail closed.