Build and Deploy

A push to an app's default branch becomes the live release. Nothing else does. This chapter follows that push from the git server through the compilers to the atomic promotion, and covers previews, rollback, and what happens after a deploy.

---

#From Push to Release Rows

The git role receives the push, makes it durable in S3, and runs its post-receive step. See Git Hosting. Post-receive records which refs moved and creates a release row per pushed branch: a default-branch push creates a release that will be promoted; any other branch creates a release that will become a preview. The default branch is always built, and the fan-out of one push is capped, so a push of many branches cannot start an unbounded number of builds. A newer push to the same branch cancels the builds it supersedes at their next checkpoint.

A release row is the unit of everything downstream: it has a status, a build log with timestamped phases, the commit it was built from, and the manifest as read from that commit.

---

#The Compile

Compilation runs in the platform and delegates the two heavy steps to job runners on the jobs island. See Job Runners.

1. Read and validate the manifest. Methods, tables, roles, interfaces, jewels, mappers. Validation errors fail the build here, with the message the builder needs.
2. Compile methods. The method compiler bundles each method to JavaScript, resolves the release's dependencies inside a worker-derived image, and builds the dependency artifact: a node_modules tarball with an ABI stamp. Outputs upload through presigned grants to the release's prefix in S3.
3. Compile the web interface. When the app has one, the web build runner runs the interface's own build with the asset base pointed at the release-addressed static origin, and uploads the output. Mounted child apps and web routing are validated alongside.
4. Compile the other interfaces. API, MCP, cron, webhook, email, agent, voice and jewel interfaces are compiled to their platform representations and diffed against the live release, so the promotion knows what to add, change and remove.
5. Diff the tables. Table definitions are parsed from their TypeScript, and the result is diffed against the live database's recorded schema. The platform confirms the recorded schema agrees with the live file before trusting the diff, so a misplaced file fails with the missing tables named rather than producing a phantom migration.
6. Apply the schema change to a clone. When the diff is not empty, the platform clones the live database file to a staging copy and applies the change there. Adds, drops and constraint changes that a plain alter cannot express are performed by rebuilding the table through a copy. A failed migration leaves live untouched and marks the release failed.

The release is now compiled. Its logs, artifacts and staged database exist; nothing is serving from it yet.

---

#Promotion

For a default-branch release, promotion runs as one operation:

1. A race guard: if a newer release on the same branch is already live, or this build was superseded by a later push, the release is marked superseded and the live pointer is left alone.
2. Pending effects are applied: cron jobs, agent configuration, voice configuration, jewel identities and roles, and the tables diff. The tables diff clones fresh from live and runs the schema change again, so the promoted database reflects writes that landed during the build. When auth is enabled, the sync triggers that mirror the app's users table are installed.
3. The app's live pointer is swapped to this release. The previous live release is marked superseded. The change is idempotent, so re-promoting the same commit is a no-op.
4. The previous release's sandboxes are stopped by app label, so the next request claims a sandbox configured for the new release.
5. An audit event records the deploy, and the workspace's changelog gains an entry from the commit messages.

The cutover is the pointer swap. Requests in flight finish on the release they started on; the next request resolves the new one.

---

#Previews

A non-default-branch release is set to preview instead of promoted. It is served on a gated host whose label contains a double hyphen, in two forms: an immutable release-addressed one and a stable branch alias. Its data plane is a clone keyed by its own release id, so it never reads or writes live. Workspace members reach it with their session; anyone else needs a share link the workspace issues. See Environments.

---

#After the Deploy

Post-deploy effects run after promotion or preview. Each runs independently, each is recorded in the release's build log under its own phase, and none can fail the deploy or each other:

• Frontend diagnostics. A headless-browser audit of the built interface, run on the jobs island, with results in the dashboard.
• Data source mappers. Newly declared mappers are activated against their sources.
• The assessment report. A static analysis of the release: its auth methods, its data handling, and the models and data it sends. It is regenerated behind a commit classifier, so an unchanged release reuses the prior report.
• The CAIQ attestation. Filled from the report and the platform's cited facts. See Compliance and Attestation.
• Mirrors. The app's overview, roadmap and pitch material, when it declares them.

---

#Rollback

A release is immutable, and its database file is left in place when it is superseded. Rolling back is either a revert and push, which builds a new release through the same pipeline, or re-promoting a prior release, which swaps the pointer back. Neither path applies a destructive schema change: the auto-migration handles additions and removals, but never type changes or renames. A builder makes those changes explicitly.

---

#Development

Between pushes, a builder works in a dev environment: a dev box or the CLI tunnel, with their own dev database cloned from live. Saving a table definition syncs the change to the dev database with the same migration rules as production. The editor can reset the dev database from live, truncate it, or lift data between dev and live. Method edits take effect on the next invocation, with per-request transpilation. See Dev Boxes.