# Plans & tiers

Graphden's cloud stratifies tenants into tiers. A tier is a slug on the org
(`:plan`) that resolves to (a) the side **effects** its graph may use and
(b) its **quota** ceilings — the source of truth is `graphden.tenancy.plan`
(in the private `graphden-tenancy` repo).

**Pricing** is published at [graphden.dev](https://graphden.dev) (or contact
`licensing@graphden.dev`); this page documents what each tier *includes*, not
what it costs.

| | Anonymous (demo) | Free (registered) | Cloud Shared | Cloud Dedicated |
|---|---|---|---|---|
| Effects allowed | `db` `state` `time` `random` | + `network` | + `network` | + `network` `process` |
| Outbound HTTP (`network`) | ✗ | ✓ (egress-guarded, rate + size capped) | ✓ | ✓ |
| Connect to your OWN database | ✗ | ✓ (external `:sql-query`/`:sql-exec`) | ✓ | ✓ |
| Outbound calls / min | 0 | 120 | 6,000 | ∞ (uncapped) |
| Max fns | 200 | 500 | 5,000 | 5,000 |
| Max list items | 2,000 | 50,000 | 500,000 | 500,000 |
| Persistence | ephemeral (reaped) | persistent while used (see note) | persistent | persistent |
| Always-on services | ✗ | ✗ | ✗ | ✓ (up to 20) |
| Resource isolation | shared pod | shared pod | shared pod | dedicated cgroup-limited shard |
| BYO executor (run your own — [BYO_RUNBOOK.md](BYO_RUNBOOK.md)) | ✗ | ✗ | ✓ | ✓ |
| `raw-sql` (platform DB) | ✗ | ✗ | ✗ | ✗ |

Notes:

- **Publishing to the shared marketplace** is open to every registered
  tier (the org's `:publish-packages` right), but a tenant's **public**
  listing is **moderated**: it waits in the operator's queue and reaches
  the shared catalog (and the anonymous storefront) only once approved;
  the publisher is emailed the decision. Private packages, themes and
  keymaps are listed for the org at once. Public names are first come,
  first served across the registry ([MARKETPLACE.md § 2, § 8](MARKETPLACE.md)).
- **Anonymous** is the LOCKED landing-demo tier and the fail-safe default (an
  un-provisioned / un-slugged org resolves here): no outbound network, small
  ceilings, ephemeral (reaped by the demo GC). It exists to let someone *try
  graphs* with nothing to lose.
- **Free (registered) is kept while it is used.** A free org with no sign-in
  or token use by its owner or any member, no run, no edit, and an owner
  account older than the window (`GRAPHDEN_FREE_ORG_INACTIVE_DAYS`, 60) is marked for deletion a
  grace period out (`GRAPHDEN_FREE_ORG_GRACE_DAYS`, 14); the owner and every
  member are **emailed the deletion date** at that moment and reminded
  `GRAPHDEN_FREE_ORG_REMIND_DAYS` (2) before it, and any sign-in or run
  inside the grace un-marks it. Paid and suspended orgs are never
  selected. The mechanics live in the tenancy addon's reaper
  (`:tenancy/demo-gc`, [OPERATIONS.md § Inactive free organizations](OPERATIONS.md#inactive-free-organizations)).
- **Free (registered)** is what a signed-up account gets — base effects PLUS
  metered `:network`, so you can build a personal Telegram bot, keep a few
  hundred records, and connect to your OWN external database, all within the
  egress rate + size caps + the SSRF / platform-DB guard. It is not a locked
  tier; it is a genuinely useful one. Upgrading to a paid tier is a change to
  the org's `:plan` row (operator `set-org-plan`, no migration).
- **Outbound `network`** is guarded by the SSRF egress broker plus a per-tier,
  per-org outbound-call rate cap (the "outbound calls / min" row) and a response-
  byte cap — see [SECURITY_MODEL.md](SECURITY_MODEL.md). A suspended org's cap is
  0 (no outbound at all).
- **Connecting to your own database** uses the external `:sql-query` /
  `:sql-exec` base-fns; they count as the `network` effect (egress-guarded so
  they can only reach a validated-public host, never the platform DB or an
  internal service) — NOT `raw-sql`.
- **Services** (persistent tenant processes) require the **dedicated** tier: a
  continuous tenant workload needs a hard resource boundary, which only the
  dedicated shard provides — see [SCALING.md § Tenant isolation](SCALING.md).
- **`raw-sql` is never granted on the cloud** — it means arbitrary SQL against
  the *platform* Postgres (`:pg-query` / `:pg-execute` / `:pg-tx`), which a
  tenant pod shares, so it would cross tenants; use the org-scoped
  `:query-entities` family instead.
- **Single-tenant self-host** is unrestricted and uncapped — no tier applies.

## Starting an anonymous demo

A landing visitor gets an anonymous org through the unauthenticated endpoint:

```text
POST /api/demo/start   →   {"token": "<bearer>", "org": "demo-xxxxxxxx"}
```

It mints a throwaway `anonymous`-tier org (locked, no network, small ceilings)
plus a bearer token, and stamps an `:expires-at` so the demo-GC reaper purges
the whole org after the TTL (`GRAPHDEN_DEMO_TTL_MS`, default 1 h). The visitor
uses the returned token like any bearer.

This endpoint is **OFF by default** — a public, zero-friction row-creating
endpoint is an abuse surface. A deploy opts in with
`:tenancy/user-ops {:demo-signup-enabled? true}`. When off it returns 404; when
on it is per-IP rate-limited (429 over the window), and the anonymous tier + TTL
bound each demo's blast radius.

## Founding beta — paid tiers before billing exists

Until billing ships, paid tiers are granted **by hand** and never sold:

- A user asks for a plan (the landing's pricing note links
  `mailto:social@graphden.dev`; the plan-limit errors point at
  `graphden.dev/#pricing`). The operator flips the org with the route below
  (or Operate → Orgs in the editor) and records it in the private register
  (`graphden-internal/docs/FOUNDING_ORGS.md`: org, contact, tier, date, what
  was promised).
- One public condition for everyone: free until billing launches, then a
  fixed discount window on the same tier, in exchange for feedback. Capped
  (30 orgs; Dedicated is a real pod, so at most a handful).
- **Never tied to sponsorship.** Donations to the Open Collective do not buy
  a tier — the fiscal host forbids selling through the collective — so
  "support us and we unlock X" is not a thing this project says.
- The first org that wants to *pay* triggers the billing work: a pilot on a
  free tier meanwhile, then it converts first.

### The billing seam — invoices today, a provider later

Whatever bills, the org row ends up carrying three fields, written only
through the operator route (`POST /api/orgs/plan`, or Operate → Orgs):

| Field | Meaning |
|---|---|
| `:plan` | the tier slug |
| `:plan-until` | when the plan ends (a `YYYY-MM-DD` day, inclusive); nil = open-ended (a founding grant, a hand-set tier) |
| `:plan-note` | operator free text — the invoice number, the founding-beta promise, later a provider subscription id |

The reaper (`:tenancy/demo-gc`) is the clock: a paid org past
`:plan-until` drops to `free` on the next sweep (nothing is deleted — the
free ceilings apply from its next request), its people are emailed, and the
note keeps the history (`… · network ended 2026-12-31`); a week before the
end they get one warning. So an invoice paid through a freelance platform
is `plan=network, until=<period end>, note=<invoice>` today, and a payment
provider's webhook tomorrow is a handler that calls the same route with the
period end it was told — the provider never reaches the schema.

For invoices and the founding-orgs register, `GET /api/orgs/usage.csv?days=30`
answers every org's runs / failures / summed duration over the window as
CSV (operator context only; a tenant gets the header).

## Funding

Where each kind of money goes, so the lanes never mix:

| Source | Goes to | Pays for |
|---|---|---|
| Donations, GitHub Sponsors, grants | the project's [Open Collective](https://opencollective.com/graphden) (fiscal host: Open Source Europe; public ledger) | contributor work on the open-source repository, against invoices at the published rate; community expenses |
| Cloud subscriptions, implementation work, paid support, commercial licences | the maintainer's own business | servers, the hosted service, the maintainer's time |

Rules that follow: the collective never pays for the servers that run the
hosted service (they are shared with the free tier); a donation never buys
a cloud tier; cloud revenue never flows through the collective. Support
and implementation are described in [SUPPORT.md](https://github.com/Graphden/graphden/blob/main/SUPPORT.md), the
commercial licence in [COMMERCIAL.md](https://github.com/Graphden/graphden/blob/main/COMMERCIAL.md).

## Suspending an org (abuse kill-switch)

`suspended` is a special tier — not something a tenant buys, but an operator's
throttle-to-zero for a misbehaving org. It grants **no effects at all** and sets
**every row ceiling to 0**, so a suspended org can neither run any graph
(execution is blocked at the effect gate) nor create any entity (the row-cap
rejects even the first write). Deletion stays allowed, so the tenant can still
clean up its own data.

An operator sets any org's tier — to suspend, to restore, or to upgrade /
downgrade — through the platform-only route:

```text
POST /api/orgs/plan     (form-encoded: name=<org-slug>&plan=<tier>)
```

`plan` is one of `free` / `network` / `dedicated` / `suspended`; an unrecognised
slug is rejected (`:plan/unknown`) so a typo can't silently drop an org to the
free default. The change takes effect on the org's next request (the resolver is
not memoised). This route is platform-only — the `:org` entity is tenant-
forbidden, so a tenant cannot change its own or another org's tier.
