# Lily operations

Lily is a remote Cloudflare Worker installation. Run commands from the root of
this edition repository with Node 26.8.1 and pnpm 10.12.4.

`pnpm run setup` provisions or reuses the deterministic D1, R2 and Queue
resources for LILY_DEPLOY_ENV (production by default), then writes ignored
deployment state. It does not apply migrations. Add '-- --dry-run' to print the
resource plan and missing required input names without changing Cloudflare.

`pnpm run deploy` performs setup and builds the Worker, then pauses the selected
queue and new mail claims while existing work finishes. It applies migrations,
compiles canonical queue facts, and atomically enables publication enforcement
before uploading the Worker with temporary private secrets. Old Worker invocations
cannot claim new sends or commit clock changes without their matching facts.
After integrity and `/health` checks, deployment restores the queue's original
pause state, including an intentionally paused queue.

A failed upgrade retains `.seed/deployment/<environment>.queue-upgrade.json`.
Resolve the reported error and rerun the same deploy command; the receipt preserves
its original queue state. An unfinished provider attempt is never replayed or
forced complete to finish an upgrade. Local migration also compiles and enables
the same queue invariant before starting the local application. Configure the required environment values
in OPERATIONS.json; Wrangler authentication may be OAuth or
CLOUDFLARE_API_TOKEN, with CLOUDFLARE_ACCOUNT_ID needed for multiple
accounts. Optional ticket-mail, commerce, AI and sync inputs apply only when
those adapters are enabled.

`pnpm run verify` runs the local composition and implementation checks. A
nonzero result can mean only that the contract reporter found uncovered clauses;
it is evidence of the executed local checks, not complete first-release
acceptance or provider delivery. See [ACCEPTANCE.md](ACCEPTANCE.md) for the
release decision and open obligations.

`GET /health` checks D1, lists at most one R2 object, and submits a data-free
Queue probe. The consumer discards that exact probe without invoking mail.
It returns 503 on missing/unreachable dependencies or a 900ms deadline. Queue
acceptance proves reachability, not consumer execution or mail delivery. Enabled
ticket-mail additionally validates its bindings and credentials; no provider
mail is sent.

Run `node scripts/operations.mjs describe` to inspect the operation interface,
or `node scripts/operations.mjs check` to check inputs. The check validates local static inputs only and
does not contact Cloudflare or certify generated deployment state, build output,
migrations, or hosted health.

Queue pause inspection follows the [API's optional boolean](https://developers.cloudflare.com/api/resources/queues/)
and the [official Go SDK's boolean decoding](https://raw.githubusercontent.com/cloudflare/cloudflare-go/main/queues/queue.go):
an omitted `delivery_paused` in a valid settings object is interpreted as false.
The upgrade receipt preserves whether the field was absent, alongside the raw
settings. Null, non-boolean, or missing settings are rejected. This interpretation
is verified against the provider's observed response; it is not a quoted default guarantee.