Constructive Sites

Constructive Sites

A site is a routable web property: a hostname, a content origin (a bucket, an authored page set, or an installed service), and the serving rules in between. This skill covers the whole site surface from the application layer, through the generated SDK ORM: provisioning a bucket-backed static site in one call, deploying it as an immutable release with named previews and rollback, authoring Merkle-versioned pages, installing the platform's Mantra auth pages and content presets, and associating a mobile app with a host.

It intentionally does not cover the SQL, trigger, static-gateway or reconciler internals — those live in the sites-*, mantra-auth-pages and testing-static-gateway-planes skills in constructive-db. Every symbol below is taken from the generated @constructive-db/constructive-sdk ORM (the api target) or, where noted, the infra target.

When to Apply

Use this skill when:

• Provisioning a static site (docs, marketing, SPA) with a bucket origin and a hostname in one call
• Deploying a build as an immutable release, publishing it atomically, and rolling back by moving a pointer
• Minting a named preview URL (<name>--<site>.<apex>) per branch and moving/retiring it
• Reading any historical release without publishing it (time travel)
• Authoring pages whose every write is versioned, and publishing a chosen version
• Installing the Mantra page set (sign-in/up/out, reset, 2FA, OAuth callback, legal, robots/sitemap/webmanifest) onto a site
• Seeding a site with a content preset (pages:legal, robots:no-ai) without overwriting tenant edits
• Associating a mobile app with a host (AASA / assetlinks) and adding /l/<slug> deep links
• Deciding between the tenant (db.site) and platform (db.platformSite) surfaces

Not this skill: bucket and upload mechanics (constructive-storage), API-route/service deployment and DNS (constructive-platform), the login flows the Mantra pages drive (constructive-auth).

Two lanes, one surface

The ORM exposes the same site surface twice. The tenant (database) lane is the default: unprefixed models and operations whose rows carry a databaseId. The platform lane — on-prem / self-hosted, and the platform's own sites — is the identical surface with a platform prefix and no scope key.

Rules of thumb:

• If an operation "doesn't exist", you are on the wrong lane — check for the platform prefix.
• Tenant create calls pass databaseId in data; platform calls do not.
• The platform lane checks the manage_sites capability (NOT_AUTHORIZED otherwise); the tenant lane confines every read and write to the session's own database.
• Every model call takes a required select. Prefer .unwrap() (returns data, throws on GraphQL error) over .execute() (returns { ok, data, errors }) — swallowing errors is how a failed deploy looks successful.

Client setup

import { createClient } from '@constructive-db/constructive-sdk';

const db = createClient({
  endpoint: 'https://api.example.com/graphql',
  headers: { Authorization: `Bearer ${token}` },
});

Quick start: a static site, deployed as a release

// 1. One call: public bucket + site + web config + hostname + route.
const { sitesProvisionStaticSite } = await db.mutation
  .sitesProvisionStaticSite(
    {
      input: {
        name: 'docs',
        label: 'docs',                       // subdomain label under a published apex
        siteConfig: { spa_fallback: true, not_found_path: '404.html' },
      },
    },
    { select: { result: { select: { id: true, path: true, targetSiteId: true, domainId: true } } } },
  )
  .unwrap();
const siteId = sitesProvisionStaticSite?.result?.targetSiteId!;

// 2. Upload each file to cas/sha256/<sha256> in the site's bucket
//    (presigned upload — see constructive-storage), then commit one manifest.
const { createSiteRelease } = await db.siteRelease
  .create({
    data: {
      siteId,
      databaseId,
      manifest: {
        files: {
          'index.html': { hash: '9a3f…', content_type: 'text/html', size: 2841 },
          'assets/app.4f2c.js': { hash: '1be5…', content_type: 'application/javascript', size: 91043 },
        },
        file_count: 2,
        total_bytes: 93884,
      },
    },
    select: { id: true, commitId: true, storeId: true },
  })
  .unwrap();
const release = createSiteRelease.siteRelease;
if (!release.commitId || !release.storeId) throw new Error('release was not versioned');

// 3. Publish: one pointer move, atomic for every in-flight visitor.
await db.site
  .update({
    where: { id: siteId },
    data: { activeCommitId: release.commitId },
    select: { id: true, activeCommitId: true },
  })
  .unwrap();

Rollback is step 3 with an older commitId. A site whose activeCommitId is null serves straight from the bucket root (no release). Details, previews and time travel: static-sites.md, releases-and-previews.md.

Core models (tenant lane)

commitId / storeId are string | null in the generated types because a trigger stamps them; assert once after the write.

Custom operations

All input fields are optional in the generated types; the server raises a structured error when a required one is missing.

Pages, Mantra, presets, app links — at a glance

// A page: every write commits; nothing is published until the site pointer moves.
const { createPage } = await db.page
  .create({
    data: { siteId, databaseId, slug: 'home', content: { title: 'v1' } },
    select: { id: true, commitId: true, storeId: true },
  })
  .unwrap();

// Mantra auth/legal pages onto an already-routed site.
await db.mutation
  .sitesInstallMantra({ input: { siteId } }, { select: { result: { select: { id: true, name: true } } } })
  .unwrap();

// Seed legal pages and a no-AI robots policy — never overwrites what the site already has.
await db.mutation
  .sitesInstallContentPreset({ input: { siteId, presetKind: 'pages', presetSlug: 'legal' } }, { select: { result: true } })
  .unwrap();
await db.mutation
  .sitesInstallContentPreset({ input: { siteId, presetKind: 'robots', presetSlug: 'no-ai' } }, { select: { result: true } })
  .unwrap();

// A deep link under the reserved /l/ prefix.
await db.siteDeepLink
  .create({
    data: { siteId, databaseId, slug: 'welcome', webPath: '/getting-started', fallbackUrl: 'https://acme.com/welcome' },
    select: { id: true, slug: true },
  })
  .unwrap();

Details: pages-and-content-presets.md, mantra.md, app-links.md.

Error codes

Known SDK gaps

Document these as gaps — do not work around them with SQL:

• Listing a site's previews. getSitePreviews(targetSiteId) exists in the GraphQL schema but the generated db.getSitePreviewsRecord.findMany cannot pass targetSiteId. Use getSitePreviewCommit for single-ref reads; list with a raw GraphQL query if you must. The create/update/delete methods on that record model are meaningless (it is a function result, not a table).
• App store identities. The app-owned half of mobile app links (appStoreIdentity: platform, bundle/package id, team id, certificate fingerprints, store URL) has no model in the generated api ORM; only the host-owned siteAppLink does. Create the identity through whichever surface owns your app, then reference its id.
• Service-backed (SSR) sites. A site with resourceId / installationId resolves to a running service at reconcile time, but the install_app verb that creates the definition → installation → service chain is not exposed by the generated ORM. Route a hostname at an existing service with db.route.create({ data: { domainId, path, targetServiceId } }) instead; see the sites-ssr-apps skill in constructive-db for the internals.
• Historical page reads. Reading a page's content at an arbitrary past commit (as opposed to the published one via pagePublished) is a merkle-store read that the api ORM does not front; db.commit.findMany gives you the history, not the content.

Reference Files

Related Skills

• constructive-storage — presigned uploads into the site's bucket
• constructive-platform — services, API routing, deployment, domains
• constructive-auth — the sign-in/2FA/reset behaviour the Mantra pages drive
• constructive-flow-graphs — the merkle store that versions releases and pages
• constructive-billing — STATIC_SITES_LIMIT and other plan caps