Run the control plane

Safe local first success#

Prerequisites: macOS or Linux; `git`, `make`, and `curl`; the Rust toolchain version pinned by the `Dockerfile` builder image; access to the private wisent-ai/most repository; local port 8080 available. No local onboarding path requires production credentials.

git clone https://github.com/wisent-ai/most.git
cd most
AUTH_BYPASS=1 MOST_COMPOSITION=none make run-dev
# expected log: most-server listening

Observe the result#

In `none` composition, messaging mutation routes have no executable transport and return a capability error rather than contacting a provider. Do not interpret liveness as message-delivery readiness. Stopping with Ctrl-C leaves no background service and no Most database or provider resource.

curl --fail --silent http://127.0.0.1:8080/healthz
# expected fields:
# { "status": "ok", "version": "0.1.0",
#   "source_revision": "unknown",
#   "backends": "none", "composition": "none" }

Configuration and state#

• Configuration comes from process environment and finite Skarbiec capability IDs; `.env.example` documents inputs. Unknown compositions are invalid and must be corrected, never silently downgraded.
• PostgreSQL is required by the `prod` composition; migrations live in `migrations/` and are applied by `most-migrate` under one owner.
• Runtime code receives scoped capability handles, not committed secret values. API, database, attachment-signing, remote-worker, wisent-integrations and Apple-identity credentials are separate contracts.
• The native default bind is `127.0.0.1:8080`; the container binds `0.0.0.0:8080` and requires deployment-owned network controls.
• Optional integration startup failures degrade that integration; authoritative-storage failure prevents production startup.
• A missing MOST_DATABASE_CAPABILITY_ID refuses production startup with exit status 1 and names database initialization. Unknown MOST_COMPOSITION values also exit with status 1, rather than panicking or starting another composition.
• Deployment supplies `PUBLIC_BASE_URL`, network placement, storage, and capability identifiers. Production topology, credentials, provider accounts, DNS, and database projects stay outside the repository.

Observability and release discipline#

`/healthz` exposes version, source revision, composition, and registered backends; structured logs record routing and dependency classifications without secret material.

Most signs Skarbiec redemption requests over the capability id, nonce, workload id, redeem operation and empty authorization id. A finite capability is consumed at process startup; issue a fresh unbound capability for a new process. An incorrect API bearer returns 401, while a credential the server failed to redeem produces 503. Connection errors name the socket and failed operation in the startup log; a broker denial requires its audit record.

Schema changes require explicit forward, recovery, and rollback analysis. Once a release exists, production uses the immutable artifact and digest — never main, a moving image tag, or an uncommitted checkout.

Database migrations#

Run most-migrate apply --dsn "$DATABASE_URL" --migrations-dir migrations from the immutable release. Tables and migration history belong to the most schema, which the server's storage queries use. Repeating the command skips recorded files.

Older runners created the first five migrations in public and failed at 006_account_sources.sql with schema "most" does not exist. The repaired runner refuses that layout without changing it. For a dedicated Most database, add --adopt-legacy-public to the same command. It moves existing Most tables and history in one transaction, preserving rows and relationships, before applying outstanding migrations.

Legacy adoption refuses empty or unrecognized migration history and any existing destination table. It never merges or overwrites conflicting state. Migration errors identify the failed file, which is not recorded as applied.

Candidate build contract#

CI and Stado use make release-quality for Clippy, formatting, the Rust suite and make test-migrations. Real migration and bootstrap CLIs run against owned PostgreSQL: fresh and repeat application, lossless legacy adoption, conflicting destinations, foreign history and stored relationships are checked. Bootstrap planning and refused live provisioning must preserve existing identity material. No operator database is used.

PostgreSQL tools must be discoverable through pg_config; missing prerequisites fail the gate. Make test targets keep temporary files in .wisent-output/t. The SQL client uses an isolated environment and home, disables interactive and GSS authentication, and bounds connection establishment to 30 seconds. Command-start records identify unfinished operations; commands, exit codes, output and binary revision remain in WISENT_OUTPUT_DIR/migration-evidence, defaulting to .wisent-output/migration-evidence. These checks do not prove Apple activation, provider delivery or desktop behavior. Stado uses make release-build to stamp WISENT_SOURCE_COMMIT and stage five executables, SQL migrations and evidence relative to WISENT_OUTPUT_DIR.

GitHub CI runs that gate through python3 scripts/ci-quality.py. ECHO_WEB_DEPLOY_KEY and WISENT_ERRORS_DEPLOY_KEY select the read-only key for each private dependency, regardless of its comment. Missing keys stop the gate and name the affected repository. Host keys come from GitHub's HTTPS metadata; credentials and Git configuration are isolated to the invocation and removed afterwards.

Submit an immutable commit with stado release submit --source . --commit FULL_SHA --version 0.1.0 --channel candidate. A candidate package is not a running service. Production qualification still needs real authenticated API access, PostgreSQL persistence, provider sends and receipts, webhook delivery and the desktop journey.