quoin

Spec 05 — Delivery

The Quoin specification

The static output contract, environments, previews, publishing, hosting and backups.

1. The static output contract

A build produces a self-contained static directory (HTML + assets). The delivery path is: build → object storage → CDN. No runtime service (§ Constitution 3). Forms, bookings, payments are external services referenced by link — never implemented in the site.

2. Environments

A Quoin site has exactly two environments:

  • Preview — per-PR, ephemeral.
  • Live — the output of main.

There is deliberately no staging. A persistent staging environment invites state drift from live, and its purpose (realistic pre-publication review) is exactly what per-PR previews do better and more cheaply.

3. Preview

Every PR gets a preview deployment:

  • Unguessable path: <pr-number>-<random-suffix>.<preview-domain>. The random suffix is required — a sequential path is enumerable.
  • Noindex: every preview response carries X-Robots-Tag: noindex (and robots.txt disallows the preview host).
  • Origin: the same build as CI runs — a preview is the real rendered result of the branch, not an approximation.
  • Lifecycle: created on PR open/update; deleted when the PR merges or closes (object-storage lifecycle rule keyed by PR path).
  • Access: open by URL. Client-sensitive sites MAY add basic auth at the edge; the default is unguessability, not secrecy.

4. Publish

Merging to main is the only path to production (Constitution §4):

merge → CI build (schemas re-validated; red merge impossible under branch protection)
      → atomic publish: sync to live bucket + CDN invalidation
      → release recorded (tag or release note with the PR list)
  • Publish is atomic at the switch: the CDN begins serving the new output as a unit.
  • Rollback is a revert PR — git revert, CI, publish. There is no hand-editing of production storage, ever; the storage bucket is a projection of main (drystone constitution §3, borrowed verbatim).

5. Reference hosting (illustrative)

AWS, per site: S3 bucket (live), S3 bucket prefix per PR (preview), CloudFront distributions (one per environment class), Lambda@Edge or CloudFront function for X-Robots-Tag on previews, ACM/TLS, GitHub Actions for CI/build/publish. Any equivalent stack conforms if §1–§4 hold.

6. Domains, redirects, and the long tail

  • Slug changes are structural; a slug change PR SHOULD include the old URL → new URL redirect in the CDN configuration in the same PR.
  • The 404 page is a page like any other — chrome included.
  • Sites are HTTPS-only; www/apex canonicalisation is CDN configuration, not content.

7. Backups

The repository is the source of truth; hosting storage is disposable (§4). Backup strategy = Git hosting + (optionally) scheduled repo mirrors. No separate content backup system is required, and none SHOULD be built — a second store of content is a second truth waiting to diverge.