Docs/Start

#Factory Zero backend harness — architecture

Status: v2 (Rust), adopted 2026-09-05, ADR 0008 added 2026-09-06, ADR 0009 added 2026-09-06. Owner: Factory Zero. Decisions are recorded in docs/adr. Supersedes the TypeScript v1 design entirely.

#1. What this is

One reusable, open-source backend harness, written in Rust, that every Factory Zero venture compiles its own backend from. A venture's backend is a small Cargo project that depends on the harness crates it wants, wires adapters, and builds one stateless Cloudflare Worker (Rust compiled to WebAssembly via workers-rs). Nothing is shared at runtime between ventures: each venture has its own Worker, its own database, its own secrets.

Modules are Rust crates resolved at compile time. The kernel and most modules are public; some modules are private. Cloudflare D1 is the database today; the design keeps compute and storage swappable so everything can move to a self-hosted native binary later without rewriting modules.

First deliverables: an email signup module (double opt-in via Resend) and a waitlist module, deployed for factory0.ventures.

#2. Principles

1. Modules only see ports. A module never touches a Cloudflare binding, std::env, or a vendor client. It receives trait objects: Database, Mailer, Captcha, RateLimiter, Signer, KeyValue, Clock, IdGen, Actors. Adapters implement the traits. This is what makes the self-hosted move a change of one runtime crate, not a rewrite.
2. Compile-time composition. A venture backend lists module crates in Cargo.toml and composes them in src/lib.rs. The wasm binary contains exactly those modules it serves in-process. No runtime plugin loading, no registry service. Cargo features select adapters. One narrowing, ADR 0009: a module whose source must stay with its owner may run as a sidecar, its own Worker reached over a service binding and mounted at the same /v1/<name>. It is still composed, just not into the same binary.
3. Stateless by construction. No static mut, no thread_local! state that outlives a request, no per-isolate caches of request data. Anything that must persist goes through Database or KeyValue. Confirmation and unsubscribe links are HMAC-signed tokens, so they need no server-side session. Request scope (request id, tracing span, wait_until) travels in axum request extensions, never in shared mutable state.
4. Runtime-agnostic kernel. cratefield-core depends on http, axum (default features off), serde, tracing, and pure-Rust crypto. It has no wasm-bindgen, worker, tokio or std::fs dependency. Runtime-specific code lives in cratefield-runtime-cloudflare (wasm) and, later, cratefield-runtime-native (tokio).
5. Portable SQL. Migrations are hand-written SQL in a subset that both SQLite (D1) and Postgres accept, with per-dialect overrides only when unavoidable. Queries are built with sea-query, which renders the same query for either backend; execution goes through the Database trait.
6. Small surface, boring crates. axum, serde, sea-query, tracing, hmac, sha2, base64, subtle, ulid, askama, clap. No framework of our own beyond the Module trait.

#3. Crate map

Crate names encode visibility and distribution. There are no scopes on crates.io, so the prefix does the job.

Every crate lives in this repository (ADR 0013). The prefix says who owns the name and whether it is published; publish = false in the manifest is what actually keeps a crate off crates.io.

#The published crates

#The unpublished crates

The auth service (crates/auth-*, packages cratefield-auth-*). One crate per login method over a shared auth-core, plus the deployable auth-worker, deployed as one branded instance per app (instances/<app>/, issue #777). Its ADRs are the 0200 block. It moved here from Factory-Zero/auth; the packages were renamed from factory0-auth-* on 2026-10-05 (ADR 0011 amendment).

Private modules are fz-* crates alongside the public ones and pass the same cratefield-testing conformance kit in this repo's own CI. fz-module-linkedin runs a LinkedIn Company Page from the harness.

The control plane (crates/control-plane*) is the managed service: sign up, pick modules, connect Cloudflare and SSO, and get a running harness venture. It is itself a harness venture. See docs/control-plane/.

Three native fz binaries — crates/auth-fz, crates/control-plane-fz, crates/control-plane-dev — are excluded from the workspace so their clap/rusqlite dependencies never reach a wasm graph. They use path dependencies and are built from their own directories.

#ventures/

A venture is a Worker composing modules. There is no template to copy: a new one starts from a manifest — fz init writes venture.json (name and host, no modules), fz add mounts modules onto it, and fz build generates the crate: src/lib.rs (Worker entry via the runtime crate and the generated harness()), src/fz_main.rs (the fz bin target), a wrangler.toml with a D1 binding, and a migrations/ dir maintained by fz migrations collect.

Deployable Workers that are crates rather than ventures keep their migrations/ beside the crate: crates/auth-worker and crates/control-plane. The control plane's wrangler.toml sits beside it too. The auth Worker is deployed once per app, so its configurations live in instances/<app>/wrangler.toml, each building the same crate (issue #777).

#4. The module contract

// cratefield-core
pub trait Module: Send + Sync + 'static {
    fn name(&self) -> &'static str;              // "email-signup" -> mounted at /v1/email-signup
    fn version(&self) -> &'static str;           // env!("CARGO_PKG_VERSION"), for /__health
    fn harness_api(&self) -> u32 { HARNESS_API } // contract version, checked by Harness::build
    fn requires(&self) -> &'static [Port];       // [Port::Db, Port::Mailer]; missing = build error
    fn optional(&self) -> &'static [Port] { &[] }
    fn tables(&self) -> &'static [&'static str] { &[] }
    fn emits(&self) -> &'static [&'static str] { &[] }
    fn public_writes(&self) -> bool { false }    // drives the production-captcha rule
    fn migrations(&self) -> Migrations;          // include_str! SQL per dialect
    fn validate_config(&self, cfg: &dyn Config) -> Result<(), ConfigError>;
    fn router(&self, ctx: ModuleContext) -> axum::Router;
    fn surface(&self) -> Surface { Surface::none() } // UI actions + views, ADR 0010
    fn events(&self) -> Vec<(EventName, EventHandler)> { Vec::new() }
    fn scheduled<'a>(&'a self, ctx: &'a ModuleContext, cron: &'a str) -> BoxFuture<'a, Result<()>> {
        Box::pin(async { Ok(()) })
    }
}

pub struct ModuleContext {
    pub ports: Ports,            // Arc<dyn Database>, Option<Arc<dyn Mailer>>, ... only what was declared
    pub config: Arc<dyn Config>, // module keys are prefixed: EMAIL_SIGNUP_CONFIRM_TTL_DAYS
    pub events: EventBus,
    pub templates: Arc<TemplateRegistry>,
    pub venture: Arc<Venture>,   // name, domain, public_url, cors_origins, env
}

/// Per-request scope, inserted by core middleware into axum extensions.
pub struct Scope { pub request_id: String, pub defer: Defer, pub span: tracing::Span }

Handlers get the request scope as an axum extractor: Scope implements FromRequestParts, so async fn join(scope: Scope, State(ctx): State<Arc<ModuleContext>>, Json(body): Json<JoinBody>). ctx.events.emit_in(&scope, "waitlist.confirmed", payload) runs handlers in that request's wait_until. There is no ambient "current request".

A venture composes:

// src/lib.rs in a venture repo
use cratefield_core::{Harness, Venture};
use cratefield_runtime_cloudflare::Cloudflare;
use cratefield_adapter_resend::Resend;
use cratefield_adapter_turnstile::Turnstile;
use cratefield_module_email_signup::EmailSignup;
use cratefield_module_waitlist::Waitlist;

pub fn harness() -> Harness {
    Harness::builder()
        .venture(Venture::new("factory0", "factory0.ventures")
            .public_url("https://factory0.ventures")
            .cors_origins(["https://factory0.ventures"]))
        .module(EmailSignup::new().double_opt_in(true))
        .module(Waitlist::new().products(["kontinuum", "undercover-rockstars"]))
        .runtime(Cloudflare::new().db("DB").mailer(Resend::from_env()).captcha(Turnstile::from_env()))
        .build()
        .expect("harness configuration is invalid")
}

Harness::build() fails when a module requires a port the runtime does not provide, when two modules claim the same route prefix or table, when a module's harness_api differs from core's, or when a template override names an unknown module. In a generated venture the harness() ends in .expect("generated venture harness is valid"), so a bad composition fails at first compose; examples/tables-canary/tests/boots.rs composes the generated venture, which turns a bad composition into a cargo test --workspace failure.

#5. Ports

All port traits are Send + Sync. On Workers the JS handles are !Send; the Cloudflare adapters wrap them in worker::send::SendWrapper, which is sound because a Workers isolate is single-threaded (ADR 0002). Async methods use async_trait until native async fn in traits with Send bounds is ergonomic for trait objects.

#6. HTTP conventions

• Prefix /v1/<module>; GET /__health lists each module with its version, the ports it requires and uses when present, and the tables it owns; each mounted sidecar appears too, with its own contract number, module name and version, and the verdict of the last probe (ok, mismatch or unreachable). The per-sidecar entry is probed lazily and cached for a short window — the stamp on each forwarded response is the real contract check (issue #61), the probe exists only so an operator can see both numbers without reading logs; the wired Mailer also lists the providers behind it under mailers, each with its name and whether it is configured and healthy (issue #793) — names and verdicts only, never a credential; GET /__ready runs SELECT 1 through Database; GET /__surface serves the composed UI surface (ADR 0010): public actions and views, plus admin ones when the admin bearer is presented, with a strong ETag per variant. With cratefield-ui mounted, /ui/<module>/<action> renders that surface as HTML and a form post there is dispatched in-process to the module route (docs/UI.md). Sidecar modules' public surfaces are fetched over their bindings and merged in per request — the fetch carries the gateway stamp when configured, and each merged document is byte-capped, contract-checked, limited to the mounted module's public part, validated, and stripped of captcha-demanding actions on a production host with no Captcha port (issue #131).
• JSON in, JSON out. Bodies deserialize with serde into types whose constructors validate. Errors are RFC 9457 application/problem+json with a stable type URI per error (<public_url>/problems/<slug> under the serving venture's own base; about:blank when it has no public URL), instance = request id.
• CORS allowlist from venture.cors_origins via tower-http. No wildcard in production. The list also takes the three browser-extension origins — chrome-extension://<id> (32 chars, a–p), moz-extension://<uuid> (lowercase) and safari-web-extension://<uuid> (either case) — as exact-match origins (issue #579). Credentials stay off, so a cross-origin caller sends only a bearer token it was given. docs/VENTURE-GUIDE.md §8 spells out the shapes.
• Every response carries x-request-id (accepted from the client if it matches ^[A-Za-z0-9_-]{8,128}$, else a fresh ULID). Tracing spans carry it; logs are JSON keyed by it.
• Public write endpoints require a Turnstile token when the Captcha port is configured, and are rate limited per IP and per email.
• Admin endpoints (/v1/<module>/admin/*) require Authorization: Bearer <ADMIN_TOKEN> and are disabled when the token is unset.
• Sidecar modules (ADR 0009) are mounted from HARNESS_SIDECARS, a JSON object of {"<module name>": "<service binding>"} read from configuration, never from the composition, so the same artifact serves ventures with and without them. A mount whose name collides with an in-process module is ignored and logged; the in-process module keeps its prefix. A mount with no dispatcher, no binding or no answer returns 503 sidecar-unavailable on that prefix only, and a sidecar answering a different HARNESS_API returns 503 sidecar-contract-mismatch. The contract is checked per response, not at cold start (issue #61): an isolate can outlive a sidecar redeploy for hours, so a cached cold-start verdict would keep serving a contract that no longer holds, and Workers forbid the global-scope I/O a true cold-start probe would need. Instead every harness response is stamped with x-harness-api (and x-harness-module when the deployment serves exactly one module — the sidecar shape), and the host reads the stamp back on every forwarded response, refusing the prefix on a wrong number. The stamp costs one header insert and catches a redeploy within one request; no /__harness identity endpoint exists and none is needed. The mount is a trust boundary (issue #131, ADR 0009 amendment): the forwarded request carries an allowlist — content-type, content-length, accept, accept-language, user-agent, the host's x-request-id, a cf-connecting-ip the host resolved itself, and a short-lived x-harness-gateway token when SIDECAR_GATEWAY_SECRET is configured; authorization and cookie never cross, and a response returns through an allowlist that drops set-cookie. Admin paths under a mount are authorized by the host before forwarding. Forwarded writes pass the host's rate limiter and fail closed. A sidecar that sets SIDECAR_REQUIRE_GATEWAY answers 401 sidecar-unauthorized for /v1/* and /__surface requests whose token it cannot verify, and fails closed (503) if the secret is missing. A truthy HARNESS_ONE_WORKER with a non-empty mount table is rejected where the table is read.

#Bodies and memory

Bodies are buffered by default, in both directions. A buffered request body is capped at 64 KiB (MAX_BODY_BYTES), raised per module by Module::max_body_bytes and enforced by axum's DefaultBodyLimit once resident; a declared content-length over it is refused before any byte is read — the 413 request-too-large pre-check of issue #440. A buffered response is read into the Workers runtime's 1 MiB response buffer (a const private to cratefield-runtime-cloudflare) before it becomes a Worker Response. That default lets a route answer problem+json before doing any work, but nothing it carries may be larger than memory.

A Workers isolate has 128 MB, so a body that fits in neither direction cannot ride that path. A module opts a route out by naming it in Module::streaming_routes() — one StreamRoute per route (a const post/put/get) with its own max_bytes ceiling. There the handler extracts a RequestStream and reads it chunk by chunk, and the route's ceiling replaces Module::max_body_bytes for that route only. The declaration governs the request body and its ceiling; a ResponseStream is honoured on any route, declared or not, because the marker rides on the response. A HEAD to a streaming GET route answers headers only, with no body read.

Each runtime carries the stream its own way. On Workers, serve() does not read a declared route's body: it hands the router an empty body plus a RequestStream over the worker-native Request::stream(), carried in the request's extensions (bridging a worker::Body through axum hangs the isolate), and response_to_worker builds the Worker Response from the ResponseStream with Response::from_stream instead of the 1 MiB buffer. On native and in the test kit, core's own request layer converts the buffered hyper/axum body into a RequestStream. Either way the request still passes through the router, so the request id, CORS, security headers, the rate limiter and RoutePolicy all apply — unlike the Realtime route (REALTIME.md), which bypasses it.

Mid-stream, a chunk that crosses the ceiling is refused the moment it arrives (the stream fuses); a declared over-ceiling content-length is the same 413 request-too-large, answered before the handler. Cloudflare itself caps the request before it reaches the Worker: 100 MB on Free and Pro; 200 MB Business, 500 MB Enterprise by default. A body over the account's limit cannot be streamed at any ceiling — it must be uploaded in parts (multipart objects, issue #586, not yet available).

#Email signup module

Table subscribers(id, email, email_normalized unique, status, source, locale, confirmed_at, unsubscribed_at, created_at, updated_at).

#Waitlist module

Table waitlist_entries(id, email, email_normalized, product, status, position, referral_code unique, referred_by, referrals, answers, created_at, confirmed_at), unique on (email_normalized, product).

Emits waitlist.confirmed; a venture can subscribe that event to also add the address to the signup list.

#Telemetry module

Table telemetry_events(bucket_key, day, install_id, client_kind, client_version, platform, arch, event, outcome, error_kind, duration_bucket, events, first_seen_at, last_seen_at), one accumulation bucket per row — no row per event — and telemetry_modules(install_id, day, module) for the payload's modules list.

Emits telemetry.recorded when a batch is accepted.

#7. Migrations

• Each module ships migrations/sqlite/NNNN_<name>.sql (and migrations/postgres/ when the SQL differs), embedded with include_str! so the crate carries its own SQL.
• fz migrations collect in the venture repo writes migrations/<GGGG>_<module>_<NNNN>_<name>.sql for wrangler d1 migrations apply. A lockfile migrations/.harness-lock.json pins module migration -> global file so adding a module later appends and never renumbers, and detects edits to already-applied SQL by content hash.
• Portable subset: TEXT ids (ULID), ISO-8601 TEXT timestamps, INTEGER counters, no AUTOINCREMENT, no dialect-specific functions in DDL. fz doctor lints it.
• Postgres later: same files run through the cratefield-adapter-postgres migrator.

Every applied migration is recorded in harness_migrations as <module>/<id> with the sha256 of its SQL. A later run compares that hash: unchanged is a skip, changed is a hard error naming the migration. Forward-only is therefore enforced by each database rather than by one repository's lockfile, which cannot see a deployment that already ran the old SQL. Rows written before checksums were recorded carry NULL and read as "applied, unverifiable" rather than as a mismatch.

#8. Tooling and release

• Cargo workspace, rust-toolchain.toml pinning stable, rustfmt + clippy -D warnings, cargo test for core and modules against cratefield-adapter-sqlite, cargo deny for licenses and advisories.
• Target wasm32-unknown-unknown built with worker-build; CI runs worker-build --release on the example venture to catch wasm-incompatible dependencies (anything pulling tokio, mio, std::fs at runtime).
• Release with release-plz: it opens a release PR with per-crate version bumps and changelogs from conventional commits; merging publishes cratefield-* to crates.io using trusted publishing (OIDC from GitHub Actions, no long-lived token). Private crates are tagged, never published.
• Ventures pin exact crate versions; Renovate (cargo manager) opens bumps.
• HARNESS_API is bumped only on breaking contract changes; cratefield-core's major follows it.

#9. Deployment

• One Worker per venture per environment (<venture>-api-staging, <venture>-api), custom domain api.<venture domain>. wrangler.toml uses main = "build/worker/shim.mjs" and [build] command = "cargo install -q worker-build && worker-build --release".
• Secrets: HARNESS_SECRET, RESEND_API_KEY, TURNSTILE_SECRET, ADMIN_TOKEN. Set with wrangler secret put by a human for production; staging via GitHub Environment secrets. Ventures with public writes or admin routes also declare the Workers Rate Limiting binding (RATE_LIMITER, a [[ratelimits]] stanza in wrangler.toml — a binding, not a secret): readiness refuses the guarded routes unless it resolves, or the operator records HARNESS_ALLOW_UNLIMITED_PUBLIC_ROUTES=<reason> (issue #437). Optional signer entries: HARNESS_SECRET_PREVIOUS (demoted, verification-only), HARNESS_SECRET_REVOKED (key ids whose signatures are refused while configured), HARNESS_VENTURE (the iss binding label; a name, not a secret).
• Mail sends from a verified sending subdomain send.<domain> (never the apex, which carries inbound Email Routing MX). Until verified, the adapter reports NotConfigured; only the orgs invitation endpoints turn that into 503 problem type=mail-not-configured so forms can show a direct address, while the waitlist logs it and still answers 202.
• Deploy workflow: main -> staging automatically; tag v* -> production behind a GitHub Environment approval.

#10. Migration path to self-hosted

Phase 3 introduces cratefield-adapter-postgres and cratefield-runtime-native. The move for a venture is:

1. Stand up Postgres, run the same module migrations (postgres set).
2. Copy D1 data with fz data export / fz data import.
3. Switch the composition in src/lib.rs to .runtime(Native::new().db(Postgres::from_env()).rate_limiter(Redis::from_env())), keep Resend and Turnstile. Build a native binary. The Dockerfile to ship is examples/venture-native/Dockerfile (distroless, the binary and nothing else); the repo's other Dockerfile, docker/Dockerfile, is the forge build image (a standalone fz plus a wasm toolchain), not a runtime image.
4. Point api.<domain> at the new host.

No module code changes. The parity suite in cratefield-testing runs every module's tests against SQLite and Postgres in CI from phase 3 onward.

#11. Security and privacy rules

• No enumeration. Signup and waitlist always answer 202 with the same body whether the address is new, pending, confirmed or unsubscribed.
• Tokens carry a purpose. Signed payload is { purpose, subject, exp?, kid, iss? }. Lifetimes are a mint-time policy, not a caller habit: confirm expires in 7 days, status in 90, anything else in 30; only the unsubscribe action has a deliberately non-expiring ceiling (ADR 0014), and the never-dying unsubscribe link now also has an opaque per-subscription form in module-email-signup that revocation can reach. A confirm token is single-use because the row state is checked before flipping.
• Key rotation. Signer verifies against a bounded key ring (four entries: HARNESS_SECRET signs; HARNESS_SECRET_PREVIOUS verifies only; ids named in HARNESS_SECRET_REVOKED are refused even while configured); tokens name their kid, so rotation never breaks links in flight, and revocation kills a key's signatures without a deletion race. New tokens carry a venture/environment iss binding, so one venture's links never verify in another. MAC comparison uses subtle::ConstantTimeEq, over every live key with no early exit.
• Fixed redirects. Confirm endpoints redirect only to URLs from Venture config. No redirect query parameter.
• Admin auth uses a constant-time compare and is disabled entirely when ADMIN_TOKEN is unset. CSV exports escape leading = + - @ \t \r to block formula injection.
• Rate limits apply to every public endpoint, including confirm and status, keyed by IP (cf-connecting-ip, never x-forwarded-for on Workers) and, for writes, by normalized email.
• Captcha is mandatory in production when a module declares a HumanForm write, or has public_writes() == true and declares no route policy at all (the conservative fallback). A write proved by an artifact this service issued — a magic link, a passkey or OAuth challenge — declares RoutePolicy::SignedLink instead, or Module::public_write_policy for a module with no surface, and needs a usable Signer rather than a Captcha (issue #143). A RoutePolicy::Signature write is proved by the module's declared verifier — Payments::verify_webhook by default, or the core webhook_signature HMAC scheme keyed by the module's own config secret (issue #533) — and production demands exactly what the module named: a Payments port, or the secret key set. The environment enforced against is the stricter of the venture's compiled VentureEnv and the deployment's ENV binding: they used to disagree silently in favour of the weaker one. Harness::build refuses the composition, Harness::router re-checks it against the resolved ports and answers 503 not-production-ready on guarded routes, and fz doctor re-reports it. Both escapes are recorded: fz doctor --allow-no-captcha <reason> for previews, HARNESS_ALLOW_UNPROTECTED_WRITES=<reason> on a deployment.
• PII minimalism. Store the email, its normalized form, timestamps, source and locale. Do not store IP addresses or user agents. Admin delete is a hard delete. A retention option purges pending rows older than N days from the scheduled handler.
• Secrets never reach logs. The tracing layer redacts fields matching (?i)secret|token|key|authorization|password; emails are logged only as a truncated SHA-256 subject_hash.
• Modules log through module_log!. On Workers a cratefield_core::module_log! line forwards through the control-event forwarder at real console levels — no tracing dispatcher is installed there — and the same redaction rules apply (issue #846).
• No unsafe outside the Cloudflare adapters' SendWrapper use, and #![forbid(unsafe_code)] in core and every module.

#12. Non-goals for v1

• Authentication and user accounts (later module).
• Payments (later, and only through the ports pattern).
• Multi-tenant single deployment on the Worker path. One venture = one Worker by design. The phase-3 native runtime does serve many tenants, one database each, with a separate control database; see ADR 0008, RECONCILIATION.md for how a boot reconciles them, and issues #23 to #44.
• Runtime plugin loading. Unchanged by ADR 0009 (when to use the sidecar mount at all: MOUNTING.md): Cloudflare's WebAssembly.instantiate() accepts only pre-compiled modules, so nothing is loaded at request time. A sidecar is a separately deployed Worker, not a plugin.

Mirrored from docs/ARCHITECTURE.md at b6f50cd. The harness is the source of truth: a correction goes there first.