RFD study: self-hostable artifacts and user-owned deployment

[softmarshmallow]

Status

Important

This issue records research toward a possible RFD. It is not a design decision, implementation authorization, platform commitment, or claim of production readiness.

Roadmap: #1

A numbered repository RFD should follow only after this problem is studied rigorously and obtains the sponsor, shepherd, and number required by the RFD process.

Problem

Spock can check and serve one framework project as a combined Spock authority/database plus Uhura Editor/Play and Spock Studio. It does not yet define a project-level deployment artifact or a supported way for project owners to build in their own CI and choose where and how to deploy it.

The mental model is similar to Storybook: a project-local build produces portable artifacts, while the project owner's CI owns publication. Storybook explicitly builds a static web application that can be published to a web host.

The analogy stops at the artifact/deployment boundary. Spock also owns mutable authority and state. A complete deployment has at least three planes:

1. web artifacts — Uhura Editor/Play and Spock Studio;
2. authority compute — the compiled contract, API/runtime, linking, and host-owned routes; and
3. durable state — schema, seed, live data, blobs, migration/rollback, and backup behavior.

“Self-hosting” therefore cannot be assumed to mean uploading one static directory.

Desired user outcome

A project owner should be able to:

• build deterministic, inspectable, versioned project artifacts in their own CI;
• choose where and how those artifacts are deployed;
• deploy suitable web artifacts to targets such as Vercel, GitHub Pages, or Cloudflare when the target's capabilities fit;
• deploy or bind authority compute and durable state separately when a static host cannot provide them;
• verify compatibility between the web, provider/link contract, runtime, and state;
• own configuration, secrets, preview environments, rollout, and rollback; and
• use Spock without depending on a Grida-operated cloud.

“Self-hostable artifacts” or “portable deployment” may be more accurate language than “self-hosting”: a user may choose a managed infrastructure provider while still owning the build and deployment workflow.

Current boundary

Today:

• spock start checks once and serves one fixed native, same-origin generation;
• spock build emits contract JSON for one standalone .spock file; project-aware build variants remain a separate design;
• the npm package distributes the toolchain, native binaries, and Editor/Play/Wasm sidecar, not a deployable artifact for an individual project;
• the framework host uses in-memory SQLite by default, or a disposable named database reconstructed from seed at process start; and
• deployment and remote environments were explicitly outside RFD 0022.

Spock's current adoption default also says it is a prototype language and runnable contract, not a general production hosting platform. Deployment work must strengthen contract fidelity or make the production boundary explicit rather than imitate cloud infrastructure. See Production-runtime features with no contract benefit.

Verified starting points

• GitHub Pages is static hosting, although a custom Actions workflow can build and upload an arbitrary static artifact. It can host the web plane, not the authority/database by itself.
• Vercel supports configurable build output directories and a provider-specific Build Output API for static assets and functions. This makes it a candidate deployment adapter, not proof of a universal Spock artifact format.
• Cloudflare Pages can deploy custom static output, and Pages Functions can receive a D1 binding. Workers can also combine static assets, compute, and bindings.
• D1 is a managed database with SQLite SQL semantics plus Worker and HTTP API access, but “SQLite-compatible” is not “drop-in compatible with the current Spock runtime.” Spock currently embeds SQLite through rusqlite, owns request-scoped SQL functions and transaction/refusal behavior, and keeps storage bytes in SQLite. D1 is an investigation target, not a presumed backend.

These sources establish that the candidate platforms have relevant primitives. They do not establish that a complete Spock deployment works on any of them.

Research questions

Artifact and build contract

1. What is the deployable unit: a static directory, a native service plus web sidecar, a container, a serverless/edge bundle, a provider-neutral manifest consumed by adapters, or several supported profiles?
2. Which project-aware outputs are required: checked contract/IR, browser assets, provider/link metadata, routes and base paths, integrity/version metadata, runtime artifacts, database schema/migrations, seed inputs, and blob assets?
3. Should the result extend spock build, introduce packaging/target commands, require a dedicated build system, or remain a stable artifact specification with provider-owned CI recipes?
4. Which parts must be reproducible without deployment credentials, and which configuration must be bound only at deploy time?

Hosting topology

5. Must a supported deployment preserve one origin, or may the web and authority planes be split?
6. What stable configuration and discovery contract would split deployments need for base paths, API origins, CORS, auth, secrets, compatibility, and failure reporting?
7. Which profiles should be proved first?
   • native process or container with durable storage;
   • static web host plus a separately hosted authority;
   • conventional serverless functions plus a remote database;
   • edge Worker/Pages Function plus D1 or another edge database; and
   • isolated preview deployments.

Database and state

8. What durable state contract is required for provisioning, schema evolution, seed bootstrap, transactions, constraints, concurrency, storage objects, backup, restore, rollback, and deletion?
9. Can D1 implement Spock's required SQL, custom-function, transaction, actor, refusal, and storage semantics? Where would a Cloudflare target also require Workers and R2?
10. How should preview environments receive isolated databases and deterministic initial state without confusing seed state with live state?
11. How does this study interact with the still-open development-state and migration questions in RFD 0023?

Product and doctrine boundary

12. Is the first supported outcome a shareable/private prototype deployment, generated production-grade artifacts, or a production runtime? What security and availability claims attach to each?
13. How are Editor and Studio access protected, and which current development-only capabilities—especially actor impersonation—must be removed, gated, or replaced?
14. Which responsibilities belong to Spock's artifact contract, and which remain with the user's deployment platform?
15. Should deployment artifacts, database portability, production boundaries, and a managed service be one RFD or separate decisions?

Candidate approaches to compare

• portable static web artifacts plus a separately deployed native Spock authority;
• a native/container project bundle with a persistent volume or external database;
• provider adapters that translate one project artifact into Vercel Functions, Cloudflare Workers/Pages, D1, or equivalent primitives;
• a provider-neutral contract with thin, user-owned deployment recipes; and
• keeping the current local-only model.

A first-party Grida-hosted service remains a later option after demonstrated market adoption. It is not a prerequisite for portable deployment, is outside the initial delivery target, and is not being promised a date here.

Constraints and non-goals

• No implementation or supported behavior is introduced by this issue.
• Do not select or advertise Vercel, GitHub Pages, Cloudflare, D1, or another vendor before the capability study.
• Do not assume every web target can host the authority plane.
• Do not treat D1 as a configuration switch for embedded SQLite.
• Do not turn Spock into a generic production orchestrator merely to imitate cloud infrastructure.
• Do not silently weaken the one-authority rule, security boundary, or current prototype-only claims.
• Treat a dedicated build system or new CLI surface as a possible conclusion, not a premise.
• Do not make portable deployment depend on a future Grida cloud.

Expected outcome

The study should produce:

• a target/capability matrix separating web, authority, and state support;
• the minimum provider-neutral artifact and configuration contracts, or evidence that target-specific artifacts are necessary;
• an explicit persistence, migration, storage, security, and preview-environment model;
• recommended first proof targets and support tiers;
• a decision on whether existing build/CLI surfaces are sufficient; and
• a doctrine reconciliation explaining what “self-hostable” promises and what remains outside Spock.

Only then should the project decide whether to write one sponsored repository RFD or split the decisions into multiple RFDs.