# CI and observation

The 0.1.0 source uses the environment in [toolchain.json](../toolchain.json).
Framework validation, external consumer acceptance and observation each
record the concrete source they validate.

All three workflows use `.github/actions/setup-moonbit` from their checked-out
source. It verifies the SHA-256 of the [official installer](https://cli.moonbitlang.com/install/unix.sh)
against the reviewed `installer.sha256`, then passes the exact release as a quoted
argument. Compiler and core versions must match. Installer changes require
reviewing its contents and updating that checksum before CI accepts them.
The observation workflow uses the action in the protected evidence checkout,
created from the frozen candidate during initialization.

The workflows install the pinned compiler and core, print
`moon version --all`, then run `moon update` before their first `.mbtx` script.
The installer does not initialize the registry index. This bootstrap is required
on a fresh runner even when JavaScript dependencies are cached. Standalone
scripts use import frontmatter and pin `moonbitlang/async` to 0.22.5.

Use the same order locally: install the environment in `toolchain.json`, run
`moon update`, then install dependencies and invoke the validation commands.

## Framework CI

`.github/workflows/ci.yml` runs on main pushes, release branches, pull requests
and manual dispatch. It installs frozen dependencies, the isolated StyleX
oracle and all three browsers, then runs `vp run validate-ci`. That gate
checks source, interfaces, generated artifacts, documentation, audits,
performance, Chromium/Firefox/WebKit and an independent quickstart consumer
of the actual clean Git commit. Reports are uploaded for 90 days.

Browser tests require a successful HTTP response from the development and
preview servers before opening pages. Startup checks are independent of console
colors and retain server output when a process exits or the startup deadline expires.
The scaffold acceptance test has a five-minute deadline for its fresh native
release/debug builds and browser edit/recovery checks. Other tests retain the
default two-minute deadline; browser checks do not retry.

For development, `vp run validate` explicitly tests a source snapshot. Use the
strict CI gate when accepting a committed version. Both paths preserve the
four generated distribution files and fail on generation drift.

## Manual external acceptance

`.github/workflows/consumer.yml` is manually dispatched. It resolves the full
consumer commit from `consumers/fababa.json` before private checkout. The lock
currently has `status: pending`; checkout and acceptance initialization refuse
that state with an actionable error. Ordinary framework CI needs no Fababa
credentials.

To accept Fababa, first migrate and validate its framework source pin in its
own repository. Freeze its committed source, tree, tooling and component
digests, then update the consumer lock through review. Run the manual consumer
workflow against that lock and the candidate commit. The verifier clones both
repositories, checks frozen identities, installs the lockfile, regenerates
component then application styles, verifies exact contracts, builds production
output and requires all three browsers without skips or retries.

Workflows use read-only repository permissions. `FABABA_READ_KEY` grants
read-only Contents access to the consumer. Observation additionally needs
`FABABA_ISSUES_TOKEN` with Issues read access. Missing credentials fail the
relevant gate; they do not count as successful acceptance.

## Initialize observation

Initialization requires a clean frozen framework commit, accepted full consumer
identity and a successful exact-SHA hosted `ci.yml` push or dispatch run.
Authenticated `gh` queries that run. Local validation alone cannot start the
window. Configure branch protection to prevent evidence branch force pushes
and deletion and restrict writes to the maintainer and observation automation.

```sh
git worktree add -b observation/0.1.0 ../style-observation HEAD
moon run tools/observation.mbtx init --output ../style-observation/observations/0.1.0/state.json
moon run tools/observation.mbtx persist --evidence ../style-observation
```

State schema v2 binds framework and consumer commits/trees, tooling and component
digests, the complete toolchain and hosted run URL. The repository variable
`OBSERVATION_BRANCH` selects the protected evidence branch, defaulting to
`observation/0.1.0`.

## Daily records

`.github/workflows/observe-0.1.0.yml` is scheduled for 02:17 UTC / 10:17
Asia/Shanghai and supports manual dispatch. It reads protected state and checks
out exact candidate and consumer commits. Each run performs strict framework
CI, a new budgeted benchmark, actual-commit consumer acceptance, toolchain
verification and paginated P0/P1 issue queries for both repositories.

```sh
moon run tools/observation.mbtx run --state ../style-observation/observations/0.1.0/state.json --records ../style-observation/observations/0.1.0/runs --application ../fababa
moon run tools/observation.mbtx verify --state ../style-observation/observations/0.1.0/state.json --records ../style-observation/observations/0.1.0/runs --output ../style-observation/observations/0.1.0/progress.json --decision ../style-observation/observations/0.1.0/decision.json
moon run tools/observation.mbtx persist --evidence ../style-observation
```

Only fourteen actual consecutive Asia/Shanghai dates qualify. Daily records
are immutable. Open P0/P1 issues, flaky gates, failed checks and infrastructure
errors prevent a passing day. A priority issue closed on the current date
conservatively resets that date; later clean dates may start a new streak.
Synthetic dates and missing issue access never satisfy readiness.

A source or toolchain identity change requires a newly frozen candidate,
hosted CI and a new protected `observation/0.1.0-<window-id>` branch with fresh
state. Set `OBSERVATION_BRANCH` locally and in repository variables to that
branch before persistence. Existing evidence remains immutable. Persistence
checks the selected branch and never writes evidence to main. The observation
workflow is configured but has no initialized window while acceptance is
pending. See [release policy](release-policy.md).